Prototype: Markdown and static assets support for SSG 🛠
Tags: opensource
Published: 2021-10-29 20:20:49

## Introduction

In the past two weeks, I had the chance to play around with [Docusaurus](https://docusaurus.io/), 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:

```bash
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:

```js
{
  // ...
  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](https://mqnguyen5.github.io/docusaurus-demo/)!

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](https://github.com/mqnguyen5/mini-ssg/issues/15) 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](https://github.com/markdown-it/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](https://github.com/mqnguyen5/mini-ssg/issues/16) and [#issue-17](https://github.com/mqnguyen5/mini-ssg/issues/17), available in my GitHub [repo](https://github.com/mqnguyen5/mini-ssg).

Cheers! 🍻