Almost 0 dependency local site

I had to solve for a curious use case. Creating documentation that can be used locally, is easy for other to contribute to and has little to no dependencies. There were a lot of other requirements that ruled out options such as mkDocs or even using something like Jekyll.

After asking around in #writethedocs Slack I was given two ideas:

Pandoc can be used to stitch files together into a semblance of a static site.
Lunr can be used as an offline search.

With this information in hand I started researching. I was in that predicament other technical writers find themselves in. Do I have time to write this myself or can I find something that is open-source? Thankfully, I was able to find two resources pretty quickly.

The two resources that I found and changed for my needs, Rippledoc.py and Lunr-Index-and-Search-for-Static-Sites. I am not going to explain setup for each one, you can visit the repo I made or visit each tool for more on configuration options.

Rippledoc

Rippledoc handles most of the work converting Markdown to HTML. This solved my problem of how do I take the markdown from contributors and convert it into an HTML site.

Uses Pandoc Markdown
Automatically create a table of contents
Has previous and next links
It will follow the folder paths for nested items.

To edit the script for my needs, I made most of my changes to the method pandoc_process_file.

Lunr search for static sites

After using Rippledoc the site worked great. I was able to navigate between files using a browser; the site built pretty quickly and there was no training required. But as the site gets larger how do people find information? That is where Lunr-Index-and-Search-for-Static-Sites came in. Just pass in the docs folder location and it builds the index for all the HTML files. Then add a search page and you’re done.

A few things to look out for

File paths in rippledoc.py are not straightforward, you will need to generate them as part of the script. To make sure the search file is available on every page, I added a search path:

html_bef = html_before.replace('', '../' * depth + 'search.html')

Then called it later when it builds the HTML body:

<div id="nav">
    <a href="{{path-to-search}}">Search</a>
  </div>

To control the description and keywords for search I added a YAML block to the end of the file. Pandoc will read a YAML block anywhere as long as it has the three dashes, ---, and a space before and after. There are better ways to do this, but for this quick example it works.

---
header-includes:
    <meta name="keywords" content="moon,shepard" />
    <meta name="description" content="Rear Admiral Shepard was one of the Mercury astronauts named by NASA in April 1959, and he holds the distinction of being the first American to journey into space." />
---

What you get is a static site that can be use used offline. Use Lunr as a local JavaScript file, write standard CSS only and you can take your docs anywhere.

Example site

GitHub Repo

Improvements

These are some ideas for improving the workflow.

After ripplydoc.py is finished move the Markdown and HTML to seperate folders.
Add more CSS so the local site is responsive
Change rippledoc.py to use YAML metadata files.
Run the build_index.js each time the site is built.
Move the search on the main page.