OSD600 - Learning Docusaurus & using reMarkable to parse markdown

Overview

For Lab 6, I had to familiarize myself with Docusaurus, copy a feature I found interesting, and implement it in my SSG.

About Docusaurus

Docusaurus is a static site generator built using React. It's a tool that eases the creation and deployment of project documentation.

Installing Docusaurus

The installation process for Docusaurus is pretty straightforward. There is more than one way of doing it. I used the npx script without the typescript option to generate my sample site as follows:

npx create-docusaurus@latest testing-docusaurus classic

Configuring Docusaurus

The process required reading the official documentation. I had to modify the docusaurus.config.js file generated during the installation as follows:

const config = {
  title: 'Testing Docosaurus',
  url: 'https://SerpentBytes.github.io',
  baseUrl: '/testing-docusaurus/',
  organizationName: 'SerpentBytes',
  projectName: 'testing-docusaurus',
  },
};

I omitted the properties I did not have to modify in the above code.

Deployment

I faced some problems in the deployment process. The main problem was incorrectly setting the value for baseUrl. Docusaurus was smart enough to point that out clearly.

Here is what my sample Docusaurus website appears like:

Adding a feature from Docusarus to Siteit

Siteit had an initial markdown support for the following:

• Bolded text
• Italicized text
• Horizontal rule
• Code block

With this Lab, my goal was to replace existing markdown handling logic with full-fledged support from a markdown parsing library. I used reMarkable to enhance Siteit's markdown parsing capabilities.

About reMarkable

reMarkable is a markdown parser library which is fast and easily extensible. reMarkable allows you to add or replace rules if you are unhappy with the default syntax. Famous users of reMarkable include Facebook.

Integrating reMarkable in my code

I removed the existing logic for parsing markdown in html-generator and created a new Javascript file named md-parser.

import { Remarkable } from 'remarkable'
import hljs from 'highlight.js'

export const mdParser = (content = '') => {
    let md = new Remarkable('full')

    md.set({
        html: true,
        xhtmlOut: false,
        breaks: false,
        typographer: true,
        langPrefix: 'language-',
        quotes: '“”‘’',
        linkify: true,
        linkTarget: '',
        highlight: function (str, lang) {
            if (lang && hljs.getLanguage(lang)) {
                try {
                    return hljs.highlight(lang, str).value
                } catch (__) {}
            }

            try {
                return hljs.highlightAuto(str).value
            } catch (__) {}

            return '' // use external default escaping
        },
    })
    return md.render(content)
}

export default mdParser

In the above code, I am configuring reMarkable to support all features. Also, we are explicitly disabling features.

I am disabling auto-closing single tags by setting xhtmlOut to false.

Also, I do not want to treat every \n instance to be replaced with <br> tag.

I have enabled linkify, which parses texts that appear like a URL to links. Setting typography to true helps with language-neutral replacements and beautifies quotes.

I am also using the highlight property to highlight code syntax based on language prefixes, which is done with the help of another library called highlight.js.

Supported Features

Siteit will be able to fully support an array of markdown features, through parsing support from reMarkable, in upcoming commits. For now, users can use the following markdown syntax.

Instances of a line of text of texts within a pair of ** or __ will yield bolded text in the rendered HTML.output.

Instances of a line of text of texts within a pair of * or _ will yield italicized text in the rendered HTML.

Instances of ___ will be replaced with a horizontal rule in rendered HTML.

To read more about the currently supported markdown features and usage instructions, navigate here.

Next Steps

In subsequent commits, I will update the CSS file to support HTML tags generated by markdown syntax for creating tables, order lists, unordered lists, and more. I will also work on enhancing Siteit's .txt to HTML parsing capabilities.

Getting Involved

We need to update our CSS to support all the possible HTML tags generated using markdown syntax supported by the reMarkable library. It makes sense to manually extend Siteit's HTML parsing capabilities or through a parsing library. To get involved, you need to file an issue in Siteit's Github repository or create a PR for existing issues, if any.