Prototype: Markdown and static assets support for SSG 🛠

Introduction

In the past two weeks, I had the chance to play around with Docusaurus, a React-based static site generator built and maintained by Facebook. Inspired by the feature-rich and beginner-friendly nature of the project, I decided to steal some of their ideas and apply them to my own.

Docusaurus impression 🐱‍🐉

Setting up Docusaurus was simple, and this is the command I used to create my Docusaurus website:

npx create-docusaurus@latest my-site classic

I chose the classic template as the starting point, since it already shipped with documentation, a blog, customs pages, and dark mode support using a CSS framework.

To deploy the site to GitHub pages, I had to make some modifcation to the docusaurus.config.js file:

{
  // ...
  url: 'https://mqnguyen5.github.io', // Your website URL
  baseUrl: '/docusaurus-demo/',
  projectName: 'docusarus-demo', // Your project's repo
  organizationName: 'mqnguyen5',
  // ...
};

After that, I just need to run GIT_USER=<GITHUB_USERNAME> yarn deploy, and there we go: A fully-fledged documentation website!

Docusaurus also make it easy for developers to add extra customization to their website, thanks to the organized directory structure, route-based modules, and excellent documentation.

Adding new features 💡

Currently, the implementation for markdown support is entirely hand-coded and is only available for a limited number of markdown syntax. To add full markdown support with this approach is just reinventing the wheel, and the better solution is to use an npm package to do the heavy lifting.

With the features in mind, I began by creating an issue on my repo, detailing what I needed to do, and providing suggestions or resources to help me accomplish it. Implementing the code was not too difficult, and I realized that I could add more features to improve my SSG. After being satisfied with how the markdown support works, I began editing the issue to include support for static assets. It is a nice feature to have in my project, as I think images and favicons are common in most web pages today.

While working on the feature for static assets, I realized that I couldn't find a way to customize markdown.it (the packages used for markdown support) to refer to the newly created /assets folder. As such, I had to develop a workaround by using regex, and in the end, managed to make it work.

Conclusion

While I managed to implement the features, I was still unsatisfied with the result. The static assets support could be buggy, and there is still room for improvement. Additionally, I planned on adding frontmatter support to make the web pages more optimized for search engines, but it was postponed as I needed to deal with the static assets issue. I managed to file some issues for those leftovers, which I will be working on soon when I have the time. For those who are interested, the issues are #issue-16 and #issue-17, available in my GitHub repo.

Cheers! 🍻