OSD600 - Learning Docusaurus & using reMarkable to parse markdown
Tags: opensource, beginners, markdown, ssg
Published: 2022-11-02 17:11:27

### Overview
For Lab 6, I had to familiarize myself with [Docusaurus](https://docusaurus.io), copy a feature I  found interesting, and implement it in [my SSG](https://github.com/SerpentBytes/siteit). 

## About Docusaurus
Docusaurus is a static site generator built using [React](https://reactjs.org). It's a tool that eases the creation and deployment of project documentation.

### Installing Docusaurus
The [installation](https://docusaurus.io/docs/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:
```node
npx create-docusaurus@latest testing-docusaurus classic
```

### Configuring Docusaurus
The process required reading the official [documentation](https://docusaurus.io/docs/configuration). I had to modify the `docusaurus.config.js` file generated during the installation as follows:

```node
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](https://serpentbytes.github.io/testing-docusaurus/) appears like:
![sample website](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/i614m3h7k6gxn7i4a4ko.png)

---

## Adding a feature from Docusarus to [Siteit](https://github.com/SerpentBytes/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](https://github.com/jonschlinkert/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`.  

```node
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](https://github.com/SerpentBytes/siteit#markdown-files-handling).

## 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](https://github.com/SerpentBytes/siteit) or create a PR for existing issues, if any.