For lab 6 in my open-source course (DPS909) we were asked to explore features of another popular static site generator (SSG) called Docusaurus. After creating our own demo website using Docusaurus, we were asked to choose one feature that we would like into our own SSG project.
What is Docusaurus?
Docusaurus is an open-source project that is used to build, deploy maintain websites (usually for project documentation). Docusaurus allows you to use tools you may already be familiar with, such as Markdown, to write documentation/blogs. The website is easily customizable as well because it's built using React.
Setting up a Docusaurus Project
Setting up a Docusaurus website wasn't not difficult at all. I first needed to create a blank project repo on GitHub then just use a command line tool (npx create-docusaurus@latest my-website classic) that builds everything you need for a basic Docusaurus site.
New SSG Feature
After exploring Docusaurus, I decided I wanted to implement full Markdown (MD) support to replace the basic MD parser my SSG currently has. This is because in order to have a good SSG, like Docusaurus, you need to have a good Markdown-to-HTML parser as the backbone of the project. Adding anything else seems unnecessary until you get the basics done and perfected.
Approach
I created some issues to help plan the process.
To start, I first began to look for an open-source NPM module that does exactly what I need and is compatible with how I set my project up.
I found a NPM library called markdown-it that parses all MD syntax into HTML. I thought this was a good module because it also supports plugins to extend it's functionality, so if I need additional features to be supported I can easily implement them.
I then installed the module in my project and began working on adjusting the code. I first got rid of my initial MD parser and then added the new module to replace it. It was rather easy to replace since the new module made the code simpler. All I had to do was import the module, then use the render() function to convert the MD file content into HTML and add it to the body of the HTML file.
Additionally, I also added some plugins to support MD features such as subscript, superscript, footnotes, definition lists
Future
Now that I have a working prototype of a full MD parser, I created some issues that invites people to add additional plugins that they deem necessary. While adding this feature I noticed that there was still a problem parsing file paths, so that's something that I will continue to work on.
Top comments (0)