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.
Top comments (0)