Once you have published your story via Shorthand Hosting, Custom Subdomain Hosting or a self-hosted option like Amazon S3, Azure Blog Storage, or SFTP, you can use our Shorthand Embed code to easily render the story from your CMS. The story will be rendered directly into your website's HTML, as opposed to within an iframe.

Here's how to embed:

Publish your story
Click the "COPY STORY EMBED CODE" button:
Within your CMS, paste the code into a post/article where you want it to be rendered (make sure full HTML is supported).

Previewing and/or publishing from your CMS should show the full Shorthand story within your site!

Note on style clashes:

It is common for CSS styles and code in your CMS to override code in the Shorthand story and cause elements to look different or break Shorthand's functionality. You may be able to troubleshoot such issues by reading the "Keep your story looking great (CSS)" section below, otherwise you can reach out to Shorthand support for assistance and we can investigate and provide CSS or recommendations on how to fix it. This CSS can usually be added to a bespoke theme if your plan has one.

When requesting assistance from Shorthand, email [email protected] and please provide the URL of the page you're embedding into, the Shorthand preview version of the story for comparison, and provide clear details and examples of the issues. Allow up to 3 business days for Shorthand to troubleshoot and please be sure to test embedding well in advance of any important publishing deadlines.

If you republish the story to a different URL, you will need to re-embed your story.

Here is an example of the story embed as used by The World Bank

Limitations

While the embed emulates most aspects of a normally hosted Shorthand story, there are a few things that it cannot do, because of its reliance on Javascript.

Social metadata. Social metadata does not get captured by Facebook and Twitter. This is because the meta tags are added to the page after load via Javascript rather than as part of the page source. If you need this data you will need to add it manually to the container page (such as via the CMS you are using).
Some internal search engines will not be able to index the content. In particular, the search engine on your CMS. From our testing, bigger search engines like Google have no problems indexing embed content. However you will still need to use metadata in your CMS to enable site search.
Using other embeds within an embedded Shorthand story. Some Javascript snippets have issues with the embed because they assume that they are being place directly in source code. You can either put the embed directly in the page source or look for compatibility modes for the snippet.
Background media doesn't stick when scrolling. If a wrapping element on the page has an overflow, overflow-x or overflow-y of hidden, then it is not possible for the element to stick. We try to detect this and print an error, so please check the developer console on the page where the embed is set, or manually check ancestor elements.
Double tracking. If you have tracking (e.g. Google Analytics) on your Shorthand theme, AND you have tracking setup on your CMS, this may cause your tracking results to be doubled. To avoid this issue please use only one or the other when tracking embedded stories.

Developer documentation

For the embed to work on custom hosting, CORS must be enabled on the server.

There are two ways to use the story embed:

1. Automatically loaded - Place the script in the page where you want the story to be loaded.

<script src="https://demos.shorthandstories.com/embedexample/embed.js"></script>

2. Manually loaded - First, place this script in the HEAD section of the page template.

<script type="text/javascript"> 
  document.addEventListener("DOMContentLoaded", function () {
    [].slice
      .call(document.querySelectorAll("[data-shorthand]"))
      .forEach(function (embed) {
        var url = embed.getAttribute("data-shorthand");
        if (url.indexOf("http") === -1) url = "https://" + url;
        var script = document.createElement("script");
        script.src = url.replace(/\/?$/, "/embed.js");
        embed.parentElement.insertBefore(script, embed);
      });
  });
</script>

And then place a special DIV in the page where you want the story to be loaded. Make sure the DIV contains a data-shorthand attribute that points to the story's URL.

<div data-shorthand="https://demos.shorthandstories.com/embedexample"></div>

Optional arguments: you can use the story title, favicon, etc by including any/all of these data-attributes:

<script
 data-title
 data-description
 data-favicon
 data-og-url
 async
 src="https://demos.shorthandstories.com/embedexample/embed.js"></script>

CSP nonce support:

You can include a nonce attribute on the embed script when required by your site's Content Security Policy (CSP).

For example:

<script nonce="8IBTHwOdqNKAWeKl7plt8g==" src="https://demos.shorthandstories.com/embedexample/embed.js"></script>

Keep your story looking great (CSS)

Shorthand stories typically look and feel quite different to the other pages on your site, and may require some parts of your usual page templates (like page margins) to be hidden or modified to ensure the story looks as good as it does when previewed within the Shorthand editor.

This is achieved through CSS rules that can be included within the Shorthand story CSS, included as part of your custom theme, or you can modify the CSS in your CMS yourself.

CSS tips

Give the Shorthand story full page width - this can mean hiding sidebars or margins that are within your usual page templates.
Make sure that there is no overflow:hidden or overflow-x:hidden on any parent elements of the page, as these break the browser's ability to stick content to parts of the screen during scrolling.

If you notice scrollmation or reveal sections not working correctly it is probably due to overflow being set in your site template.

The embed code will warn you in the browser console if there is an element with this enabled.
The embed automatically adds a class "shorthand-embed-body" to the <body> tag of the page - this lets you add CSS to your CMS that will only affect pages with Shorthand content in it by only targeting that class.
The embed currently does not support multiple Shorthand stories in a single page.

If you'd like to elegantly link between multiple Shorthand stories, we suggest you use a Shorthand Collection.

Using embed with Single Page Applications

When embedding Shorthand stories into a Single Page App (SPA) like React, it is common to remove the embedded story once the user navigates away from the story. To accomplish this you can call a function with this signature: window.Shorthand.remove(story_url)

story_url is optional, and must not include a trailing / or /index.html.

When story_url is omitted, the function will remove all embedded stories from the page. Typically there's only one embedded story per page, so it's easiest to omit the URL and only use it if you have multiple embedded stories and want to remove one.

Shorthand Story Embed