OSD600 - Adding New Feature From Docusaurus
Tags: opensource
Published: 2021-10-30 02:16:53

#1. Lab6 requirement
In this lab, I have a chance to  explore [Docusaurus](https://docusaurus.io/) - a helpful tool providing users with a lot of cool features for project documentation. The documentation of Docusaurus is very clear and easy to understand, you can take a look at [Docusaurus Docs](https://docusaurus.io/docs) for more information.

This week, I am asked to copy a Docusaurus's feature which I feel interesting in. There are several choices open to me but my final choices are:

* Add full markdown support
* Add static assets for images

#2. Modification process

* Add full markdown support

Currently, my ssg does support some markdown features such as `h1`, `h2`, link, inline code block and horizontal rule using `replace()` with regex.  `replace(regex)` is a good solution however if I want to provide support for all markdown features, there will be a bunch of `replace(regex)` lines of code with comments representing its purpose. That will make my code a bit too lengthy. 

Thanks for the existence of [markdown-it](https://github.com/markdown-it/markdown-it) - a help full Markdown parser which provides me with full Markdown support just in 2-3 lines of code.

To make use of [markdown-it](https://github.com/markdown-it/markdown-it), first of all, I need to run the install command `npm install markdown-it --save`.

Then requires the module and using it `render()` to parse the data.

```
let markdown = require('markdown-it')({
    html: true 
  });

const data = fs.readFileSync(pathToFile, "utf8");
body = markdown.render(data);

```

* Add static assets for images
I think this feature is important since it will provide images which make the website become more attractive. So I decided to implement this feature. Here are steps I did:

- Create new option `-a` or `--assets` allowing users to specify the path to the assets folder using command
```
option("a", {
    alias: "assets",
    describe: "path to assets folder",
    default: "",
    type: "array",
    demandOption: false,
  })
```
- Create an assets folder under `./dist` folder
```
  try {
    await fsPromise.mkdir("./dist/assets");
    console.log(chalk.bold.green("--- assets folder is created under ./dist successfully! ---"));
  } catch (err) {
    console.log(chalk.bold.red("***Cannot create assets folder!***"));
    return process.exit(-1);
  }
```

- Add new arg to the `checkInput()` and copy content in the specified assets folder to the ./dist/assets folder if the `-a` or `--assets` is specified.
```
module.exports.checkInput= async function (pathToFile, stylesheet, language, assets, isFromJSON = false) {
...

// using fs-extra 
if(assets !== ""){
   let copyFolder = require("fs-extra");
    try{
        await copyFolder.copy(assets, "./dist/assets");
        console.log(chalk.bold.green("--- assets folder is copied successfully! ---"));
    } catch(err){
        console.log(chalk.bold.red("***Cannot copy assets folder!***"));
        return process.exit(-1);
    }
 }

...

}
```

- Replace all images' source before parsing them to `markdown.render()`
```
    const data = fs.readFileSync(pathToFile, "utf8");
    body = markdown.render(data.replace(/!\[(.*?)\]\(.*\/assets\/(.*?)\)/gim, `![$1](./assets/$2)`));
 
```
- Modify readJson.js allowing user to specify assets option in config.json
```
const assets = data.assets || "";

    check.checkInput(data.input, stylesheet, language, assets, true);
```
View my commit at [fbdf8e4](https://github.com/hlavu/my-ssg/commit/fbdf8e4866787c48425fab5a1303c25004f286ae)

#3. Overall
Docusaurus is a good reference for me to come up with new features for my ssg. Configurable Sidebar, Markdown Frontmatter support and Themes are some features I want to add to my ssg later. They will definitely make the tool become more helpful and user-friendly. 

If you would like to give me a hand, here is my [repo](https://github.com/hlavu/my-ssg), please feel free to file an issue with a short description about what you would like to do and start working on it. I really appreciate your contribution.

All in all, thank you for reading the post.

Happy coding!