Copying a Feature from Docusaurus 🦖 For My Static Site Generator - rwar 🦁

Source of inspiration 🌟

There is so much to learn from Docusaurus. It is a powerful static site generator, packed with amazing features. I envision my own static site generator – rwar - to be as powerful as Docusaurus someday. But then again – I am a one-person team, the sole author of my static site generator getting occasional little help from other teammates in the class, and taking small steps to one day become as feature packed as Docusaurus. But for now, I am taking it slow, learning python as I improve rwar.

What is Docusaurus? Explain like I am five.

Remember that kid that got famous on YouTube for his toy reviews. Let’s imagine we want to do the same thing – talk about toys - but instead of making videos we want to use pictures and words to tell all our friends about what we liked or disliked about our toys. So, we open up our computer, type up our feelings about our toys and then save it as something called a markdown file. But uh oh. We don’t know how to create a website or maybe we do know it, but we are short on time. so, what do we do? We take the help of Docusaurus. Docusaurus has a number of simple steps to follow as stated on its website on how to get started using this amazing tool. We then follow the steps, then hand in the little paragraphs we wrote earlier about our toys. Then Docusaurus turns it into a beautiful website that we can share with anyone in the world.

What is Docusaurus? Explain like I am a junior developer

As stated in their official website:

Docusaurus is a static-site generator. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).

The docusaurus documentation provides all that you need to know to get started with creating your own documentation site without worrying much about its infrastructure. It also comes with powerful features such as search and versioning.

My experience using Docusaurus 🦖

It was very easy for me to set up a quick site using Docusaurus, thanks to its clear and concise documentation. I had some trouble deploying the site to GitHub Pages at first and it was saying I had some problems with the baseURL. I read through their documentation again and was able to fix the issue, and get the site up and running.

The feature I copied

I chose to implement the full markdown support feature for rwar because this just supercharged the markdown support rwar was already providing. I used the library markdown2 for supporting this feature. It was quite easy to get this step done and I did not face any issues. However, I realized that syntax highlights were missing from code blocks, and I filed an issue to tackle this in the future.

• The issue
• The squashed commit

What is markdown2?

From their GitHub repo documentation:

This (markdown2) is a fast and complete Python implementation of Markdown. It was written to closely match the behaviour of the original Perl-implemented Markdown.pl. Markdown2 also comes with a number of extensions (called "extras") for things like syntax coloring, tables, header-ids. See the "Extra Syntax" section below. "markdown2" supports all Python versions 3.5+ (and pypy and jython, though I don't frequently test those).

The documentation was clear enough for me to not run into any major problems while using the library. There were minor issues that I was able to debug along the way.

Going forward 🚀....

I have a lot of work to do moving forward. I realized that syntax highlighting was not being supported for my code blocks and I need to start working on it soon! I want to be able to support all the features listed below as I continue to work on rwar.

• Search Engine Optimization (SEO), including meta tags in the HTML head
• Improved accessibility of generated HTML
• Themes
• Plugins
• Configurable Sidebar (i.e., table of contents)
• Syntax Highlighting for code blocks
• Search
• Static Assets for images, stylesheets, etc.
• Markdown Frontmatter support
• Blog posts in addition to Pages