Exploring Docusaurus and enhancing cli-ssg

Docusaurus

Since I had created a basic static site generator (cli-ssg), I wanted to explore other bigger projects that were working on the same problem. One such popular SSG is Docusaurus which is a React based static site generator backed by Facebook.

The project really caught my eye and I spent quite a while going through the documentation. The docs were well setup and easy to understand. I found out that there are so many cool features in Docusaurus such as

Intrigued by how feature rich Docusaurus is, I wanted to try it out to see how long it would take to setup a sample site. It actually didn't take long at all, as the project is well documented and going through the installation guide, I was able to get a working site in no time. I ended up hosting the sample through GitHub Pages and was quite inspired by Docusaurus and wanted to enhance cli-ssg.

Enhancing markdown support in cli-ssg

When markdown was introduced in cli-ssg, only a handful of its features were supported, such as: h tags, bold, italics, links and scratched. Fascinated by Docusaurus, I wanted to expand the markdown functionality so that cli-ssg could also support all markdown syntax.

Issue filed on GitHub: #20

Implementing full markdown

The markdown parsing was manually coded, and I realized that implementing the full syntax by hand would be redundant as we can use open source projects that have already solved this problem. A popular project that was perfect for this scenario is markdown-it which is a full fledged markdown parsing library, available through npm.

I created a branch and started prototyping to see how I could use markdown-it. I started off with a simple script to test how the library worked and could be used:
test.js:

var md = require('markdown-it')();
const fs = require('fs');

try {
    const data = fs.readFileSync('./README.md', 'utf8')


    var result = md.render(data);

    console.log(result);
} catch (err) {
    console.error(err)
  }

After playing around with it for a bit and testing the results, I went ahead and created a new branch and pushed all the prototyping I had so far onto it.

Next, I actually went ahead and replaced the basic parsing functionality in my program with markdown-it. This was actually quite straightforward, as cli-ssg is quite modularized and this meant that I only really needed to change one function. I ended up replacing the regex parsing that was being used earlier to generate the HTML body, with a simple call to markdown-it using the render method:

const body = md.render(data);

After some testing, I was satisfied that it was working as expected and I committed the changes again. Lastly, I had to remove the prototype file test.js, so that ended up being another commit. At this point, I was ready to push my changes so I ended up rebasing and squashing these 3 commits into one (eb670a).

cli-ssg now supports full markdown!