The Objective

I was tasked with re-imagining the ExpressionEngine docs. The objectives were to simplify not only the user experience, but how the docs were maintained, and along the way, create a fresh new design that matched the new website.

I combined, renamed, re-wrote, and re-organized, over half of the docs, cutting the total page count nearly in half.

Switching to Markdown

We wanted to get away from reStructuredText, as it's not nearly as common of a language as Markdown, and its syntax is overly verbose.

Converting the docs to Markdown from reStructuredText turned out to be a time-consuming task. Although I was able to automate much of the process using Pandoc, much of it required manual conversion.

I'm happy to report I survived just with my sanity intact! Just barely.

Generating the Docs

Switching to Markdown meant we needed a new static site generator, which converts the Markdown files into an HTML website. We couldn't find a generator that did what we needed, so we decided to build our own. This would allow our own custom features and syntax extensions.

I wrote the new generator in JavaScript using Node JS and Gulp. Building the docs takes just 2 to 3 seconds, compared to the old generator, which required 30+ seconds!