OSD600 - Adding New Feature From Docusaurus

1. Lab6 requirement

In this lab, I have a chance to explore Docusaurus - 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 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 - 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, 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

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, 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!