DocuSaurus Adventures and SSG Inspiration

DIDNTREADME.MD

Most tools that are created in the world (software or otherwise) have documentation and manuals. I myself experienced this when I made an Static Site Generator called textToHTML and had to write a README file with instructions.

The Issue

For basic usage, a README file might be appropriate. However, what happens if your tool has many features, functions, combinations of features to use. All of these examples could get very hard to follow.

Bring In The DocuSaur

DocuSaurus provides an easily generated template website to use for documentation. It includes:

• Template MD files for links to blogs/documentation.
• Editable source code to customize look of the template.
• Easily deploying a fully functional template website using "yarn deploy" commands.

Using the inspiration

I saw how DocuSaurus handled the Markdown features, and also accessibility on their HTML templates. As such I decided for my own SSG to improve the Markdown capabilities and also add <title> tags to each of the generated pages.

Given that we were now allowed to use an open source library to implement these features instead of coding from scratch, I chose Markdown-it.

Down to brass tacks

Implementing the changes were fairly simple, as in my original method I used a function to take the content (excluding head, meta tags, body) and process the Markdown using regexp. Instead what I did now was pass my content to the markdown function which then calls the "md.render()" method and returns that content.

var md = require('markdown-it')({
  html: true,
  linkify: true,
  typographer: true
});

const processMarkdown = (data) => {
    return md.render(data);
};

Titles

To implement title tags, I took the file name using path.basename() method, and inside my generated HTML templates I added <title> ${fileName}</title> for each file. Commit Link.

Conclusion

Overall the features themselves were not too tricky to implement because luckily my refactoring last week made my code more modular and functional. So when the time came it was a matter of just changing the function logic to use the library rather than my own regular expressions.