Add Offline Documentation in 15 Minutes

Your customers want offline documentation. They want to be able to use your product on an airplane and look at the docs. They want to be anywhere and everywhere and they want to take you with them. Too bad it’s unmaintainable, risky, and complicated.

unplug-me-fb-small

Or.. Is it really?

You developed the best application in your space and now you’re looking at how to make it accessible. — That means documentation! If you’re like us, you found pandoc, did your documentation in markdown, and wrote a build script to compile it to static HTML.

Then, like us, you probably sat down and scratched your head for a bit and decided it was too much work to bake your HTML for each release, or decided it’s not worth bloating the download.

We found a great solution for implementing offline docs using HTML5 that is:

  • Easy to do (took us 30 minutes)
  • Makes minimal changes
  • Safe to deploy

The Magic Formula

There are only three easy steps to adding this useful feature to your docs:

  • Create an index-offline.html from your index.html file.
  • Add a cache.manifest file generator to your docs build script.
  • Configure your web server.

Use an HTML5 cache manifest attached to an index-offline.html file. This is like your normal index.html except that your leading <html> tag looks like this: <html manifest="cache.manifest">. Then have your doc build script create a cache manifest. Here’s how we did it in bash:

The resulting cache.manifest looks like this:

The NETWORK tag above is needed so that jquery, Google Analytics, and other off-site resources still work!

And the Revision counter is important to keep the file fresh each time you build.

Configuring nginx (for example)

Add MIME Type: text/cache-manifest

We modified /usr/local/etc/nginx/mime.types to include:

Add Cache-Control: no-cache

We modified /usr/local/etc/nginx/nginx.conf to look like this example:

If you get a 404 from curl testing it’s because you put the location outside of /. It’s important to nest location tags as in the above example.

Test it: curl

The expires -1; tells nginx to add a Cache-Control: no-cache to the response, as shown below. Also note that the Content-Type has been set to text/cache-manifest.

The curl -I command was perfect for testing.

Ship it!

Testing it was pretty easy on Mac with brew. We ran brew install nginx and made the above changes, and tested with curl. Then we deployed it to our website. We deployed with confidence because we had already tested the changes (which are minor), and the changes only affect index-offline.html.

To hook it up, point the webkit view in your app towards http://docs.mysite.com/index-offline.html instead of http://docs.mysite.com/ and you’re all set.

Users that install your app will hit index-offline.html, the attached manifest will have their browser cache the whole documentation site in the background, and then they can unplug and go anywhere with it. Whenever your documentation is rebuilt, the cache.manifest file revision rolls, and their browser will download the changes as normal. Great!

html5

It was eye opening to us that such a wonderful feature like offline documentation can be had for free thanks to HTML5. We have found a bunch of other great ways to exploit HTML5 features to simplify our release process for the Game Closure DevKit and are looking forward to sharing them. As we have time we’ll write up some of the better ones over the next few weeks.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>