DEV Community

Cover image for Open Source: Copy a Cool Feature from Docusaurus
MizuhoOkimoto
MizuhoOkimoto

Posted on • Updated on

Open Source: Copy a Cool Feature from Docusaurus

Has anyone used Docusaurus before? I hadn't until this week!πŸ™‰
I would like to introduce what Docusaurus is, what I learned and implemented from it, and next steps for the future.

What is Docusaurus?

Docusaurus is a Open Source project built by Facebook(Meta?) which provides a great Static Site Generator(SSG). According to the official website, Docusaurus is a "tool designed to make it easy for teams to publish documentation websites without having to worry about the infrastructure and design details."
Those teams would create the document website which is built on the same SSG, so each team does not have to build styles and navigation with different specifications, and makes it consistent and easy to maintain. Docusaurus also has a lot of features, so it's very flexible.

Tried Docusaurus tutorials and features!

It has a walk-through style tutorial that lets you build a website in less than 5 minutes(I took 10 minsπŸ˜‚). Using a classic template, I created a React page easily. The main features are:

  • Create a Document
  • Create a Blog Post
  • Markdown Features
  • Configurable Sidebar
  • Deploy your site

In addition, it has more features such as:

  • Theme
  • Search Engine Optimization (SEO), including meta tags in the HTML head
  • Static Assets for images, stylesheets, favicons etc.
  • Plugins
  • Versioning

The list goes on and on, so I will post a link here again.

Plan my Feature and File Issues

I planned what I would implement to my SSG by copying one of their features. I decided to work on Full Markdown support, changing the theme, static assets for stylesheets, and filed those issues on my repo.

Implementation

I searched "node markdown to html" and I found markdown-it. It said "Markdown parser, done right. 100% CommonMark support, extensions, syntax plugins & high speed(GitHub repo)". It was perfect for mine, so I installed it and implemented their "classic" way on my main js file.

var MarkdownIt = require('markdown-it'),
    md = new MarkdownIt();
...
// when input .md file
lines.forEach((line) => {
    var result = md.render(line);
    text += result;
    template = tempGenerate(argv.s, argv.l, title, titleName, text);
})
Enter fullscreen mode Exit fullscreen mode

Comparing to the previous code, I was able to reduce some code below.

if(line.includes("*")) {
  line = Array.from(new Set(line.split('*'))).toString();
   let get = line.replace(",", ' ')
     text += `\n<i>${get}</i>`;
  } else if(line.includes("#")) {
      line = Array.from(new Set(line.split('#'))).toString();
      let get = line.replace(",", ' ')
      text += `\n<b>${get}</b>`;
  } else if(line.includes("---")) {
      let get = line.replace("---", '<hr>');
      text += `\n${get}`;
     }
  else {
    text += `\n<p>${line}</p>`;
  }
Enter fullscreen mode Exit fullscreen mode

npm has what I'm looking for and it's very interesting. This time it was markdown support, but I thought there might be something else I could use for my SSG.

Deployment

When I deployed my Docusaurus sample page, even though I was following this deployment guide, I got the 404 page. The reasons why it didn't work were:

  • I had < > when I set up GIT_USER, like this: cmd /C "set "GIT_USER=<MizuhoOkimoto>" && yarn deploy". The correct command was cmd /C "set "GIT_USER=MizuhoOkimoto" && yarn deploy"
  • When I run the above command, it created gh-pages branch automatically like below, and I needed to set up the source from that branch instead of the main branch.
Deploy command invoked...
main
organizationName: MizuhoOkimoto
projectName: Docusaurus_sample
deploymentBranch: gh-pages
Remote branch: https://MizuhoOkimoto@github.com/MizuhoOkimoto/Docusaurus_sample.git
https://github.com/MizuhoOkimoto/Docusaurus_sample.git
e088072c3fdc9f7fec6d107c52acdbe7e66fc659
...
Website is live at "https://MizuhoOkimoto.github.io/Docusaurus_sample/".
Done in 70.97s.
Enter fullscreen mode Exit fullscreen mode

This is the Pages setting on my repo:
page setting I appreciate your help again, Anatoliy🌟

Conclusion

I planned implementing another 2 features as well which are adding themes and SEO within 2 weeks, but they were tougher than I thought. For the SEO, I'm working on changing my template(tempGenerator.js). However, I have no clue for the theme since I was going to copy from Docusaurus, but that was for React, so I will try to implement it in a different way.
If you have any good ideas, please message me or you're welcome to Pull Request! πŸ™‹

πŸ‘€LinksπŸ‘€

(Photo by Daniel Cheung on Unsplash)

Top comments (0)