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 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
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:
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." /> ---
These are some ideas for improving the workflow.
ripplydoc.pyis finished move the Markdown and HTML to seperate folders.
- Add more CSS so the local site is responsive
rippledoc.py to use YAML metadata files.
- Run the
build_index.jseach time the site is built.
- Move the search on the main page.
A list of resources that helped me along the way.
Local Lunr search
Todays cover art by: https://blush.design/artists/vijay-verma