E. Advanced Publishing

In this module, we discuss publishing your StoryMapJS on your own website.

In previous modules, we saw how to publish a storymap to the web using the built-in publishing tool on StoryMapJS. When you publish that way, your storymap is stored on at a specific URL belonging to StoryMapJS. You can give the link to potential audiences using social media, or put a link from your own website or blog.

In this module, we will learn how to publish your storymap at the web page of your choice.

Some sections require:

  • use of HTML
  • access to a web server

Estimated time: 2 hours +.

Page Redirect


  • access to a blog or web server
  • use of HTML is not required for this

One simple way to put a storymap at a location of your choice is to set up a page redirect.

With a page redirect, you do not change the location where your storymap is published. Instead you create a link between the URL of your choice, and the URL where the storymap actually appears.

Let’s suppose you own the domain www.mysite.net and that you would like the URL http://www.mysite.net/my_storymap to lead to your storymap. With a page redirect, any requests for http://www.mysite.net/my_storymap will be redirected to the URL for your storymap: http://uploads.knightlab.com/realstorymap.html or whatever it may be.

If you are using WordPress, you can create a page redirect using a page Redirection plugin.

If you are using your own web server, your server documentation should tell you how to create a page redirect.

iframe Embedding


  • limited HTML
  • access to a blog or web server

In this section, we will see how to embed your storymap directly into a page on your blog or website using an iframe. This allows you to put your StoryMap directly into a page on your blog or your website, and avoids using a redirect. This also means you can put text around your storymap.

For this to work, your site must allow iframe tags.

When viewed in an iframe, unless the frame is very wide, the StoryMap will be arranged vertically, not horizontally, with the map above the slides. This is an automatic feature of StoryMapJS.

Click Share in the top right of the edit view of your StoryMap, and you will see the Embed option for your StoryMap.

You can change the horizontal and vertical options, and the iframe tag will update.
Horizontal: Here you can specify the width (in pixels) for your StoryMap on your page, or as a percentage of the potential width (i.e. max. 100%).
Vertical: Enter the height (in pixels) for your StoryMap.

Copy the iframe tag (the complete contents of the Embed box) and paste it into your webpage at the point where you want your StoryMap to appear.

iframes in WordPress etc.

Some blogging and CMS platforms, including WordPress, automatically strip out iframe tags.

On WordPress.com it is not possible to use iframes, and you will not be able to embed your StoryMap.

If your WordPress blog is hosted elsewhere, you can ask the administrator to install an iframe plugin for WordPress. Once an iframe plugin is installed on your WordPress server, you will need to enable it for your blog.

With a plugin, you can easily add a StoryMap in an iframe to your WordPress post. In the Embed box at the previous step, you will find an iframe tag like this:

<iframe src="https://uploads.knightlab.com/storymapjs/xxxxxxxxxxxx/<MYSTORYMAP>/index.html" frameborder="0" width="100%" height="800"></iframe>

To use it in WordPress with the iframe plugin:

  • delete the final <íframe>
  • replace the < at the start with [, and the > at the end with ]

So your shortcode is
[iframe src="https://uploads.knightlab.com/storymapjs/xxxxxxxxxxxx/<MYSTORYMAP>/index.html" frameborder="0" width="100%" height="800"]

Change the width and height as you wish (see above).

Other plugins will have different shortcodes.

If you don’t wish to use the plugin, it is possible for the system administrator to edit the WordPress settings to enable the option “unfiltered_html”, allowing you to postiframe tags. Other content management systems will have similar options. Enabling unfiltered HTML is a security risk.

A StoryMaps WordPress plugin was produced to design and embed StoryMaps within WordPress, but this has not been updated to work with the latest versions of WordPress. This plugin may suit users who will only be using WordPress to share their StoryMaps, including students posting a StoryMap on a WordPress blog for a class.

Direct Embedding


  • a web server
  • use of HTML

As we have seen, iframe has some limitations for StoryMaps; your iframe StoryMap will generally display vertically, and you may not be satisfied with the way your StoryMap looks.

To embed your StoryMap in a page of your choice while getting the fullscreen, horizontal layout you see at your StoryMap’s URL, you need to directly embed your StoryMap. To do this, you insert some HTML code to generate the StoryMap inside your webpage.

You will need the ability to edit the HTML on the page where you want the StoryMap to appear.

You will also need to access your StoryMap data. This is stored in a single JSON file.

To retrieve the URL for youor JSON, you can:

  • View the HTML source of the page which generates your StoryMap to see what JSON file is specified.
  • See the JSON URL within the StoryMap URL (applies to older StoryMaps only).
  • Deduce the JSON URL from the StoryMap URL (recent StoryMaps). Your StoryMap URL will be in the format:
    Replace index.html in your StoryMap URL with published.json to get the URL for your StoryMap data file.

Once you have a URL for your StoryMap data, check it is correct by opening it to see if leads to your JSON file.

Now insert the following HTML code blocks into your webpage. These will load your JSON data and generate your StoryMap.

To be inserted at the place in the page where you want the StoryMap to appear:

<!-- The StoryMap container can go anywhere on the page. Be sure to specify a width and height.  The width can be absolute (in pixels) or relative (in percentage), but the height must be an absolute value. Or you can specify width and height with CSS instead --> 
<div id="mapdiv" style="width: 100%; height: 600px;"></div>

To be inserted before the closing body tag:

<!-- Your script tags should be placed before the closing body tag. -->
<link rel="stylesheet" href="https://cdn.knightlab.com/libs/storymapjs/latest/css/storymap.css">
<script type="text/javascript" src="https://cdn.knightlab.com/libs/storymapjs/latest/js/storymap-min.js"></script>

// storymap_data can be a URL or a Javascript object
var storymap_data = '//<YOUR JSON URL>';

// certain settings must be passed within a separate options object
var storymap_options = {};

var storymap = new VCO.StoryMap('mapdiv', storymap_data, storymap_options);
window.onresize = function(event) {
    storymap.updateDisplay(); // this isn't automatic

You can also override some of the settings in your StoryMap by creating a javascript object storymap_options in the page generating the StoryMap. This means it is possible to generate two slightly different StoryMaps from the same JSON file. For example, you could override the “Call To Action” text, or change the zooming behaviour.

Hosting Your Data Independently


  • access to a blog or web server
  • HTML

The StoryMaps web authoring tool stores your data on Knight Labs’ cloud storage. In this section, we will consider the situation where you prefer to host your data yourself. For example, you might want to take steps to secure long-term preservation of your StoryMap data.

There is no “export” option in the web authoring tool, but this can be accomplished manually. Be warned that there is no “import” in the web authoring tool, either. If you move your StoryMap data to a different server, you will no longer be able to use the web authoring tool to edit your StoryMap, and you will have to edit the JSON directly if you need to make changes.

If you decide to proceed with moving your data, first copy all the media for your StoryMap to a suitable hosting location. Now use the web authoring tool to edit the media URLs in your StoryMap to their new locations.

Next, fetch the JSON for your StoryMap from the JSON URL you found in the previous section. This file can now be saved and copied to your chosen server. Your JSON will need to be accessible to the internet, or you will not be able to generate a StoryMap from it in the usual way. (Alternatively you can define the contents of the JSON as a javascript object storymap_data.)

Finally, edit – or create – the HTML file where your StoryMap is directly embedded, as described in the previous section. You will need to edit the file to use the new URL for your JSON. You are now hosting your own StoryMap data.

Once you have successfully hosted your StoryMap data at your chosen location, and if you no longer need to be able to edit your original StoryMap data using the web authoring tool, you can delete your StoryMap from your Knight Labs account.

Hosting Your Own Instance of StoryMapJS

You can continue to use the Knight Labs StoryMapJS server to generate your StoryMap even if you move your JSON. Under some circumstances, however, you may wish to run your own copy of StoryMapJS. The code is open source and instructions are provided.

To generate your StoryMap using a local copy of StoryMapJS, edit the tags:
<link rel="stylesheet" href="https://cdn.knightlab.com/libs/storymapjs/latest/css/storymap.css"> and <script type="text/javascript" src="https://cdn.knightlab.com/libs/storymapjs/latest/js/storymap-min.js"> to point to your local server.