DEV Community

WangGithub0
WangGithub0

Posted on

Learn about Docusaurus

Image description

Docusaurus is a React-based static site generator built and maintained by Facebook. It helps projects document their technology for users and developers, without having to put a lot of effort into creating a full website. Lots of projects use Docusaurus for their project documentation, for example Jest, Redis, creact-react-app, Home Assistant, React Native, and many more.

In order to learn how to do a large open source project, I learned Docusaurus project this week.

First, I tried run it on my computer according to the Installation. It's quite simple to run it, I just run two commands:
npx create-docusaurus@latest my-website classic
npx docusaurus start

then a browser window opened at http://localhost:3000. It's really cool!

Then I played around it according to the tutorial showed on my page to create a page, document, blog post:

Image description

Docusaurus has many cool features, among these I was more interested in Sidebar and code block.

At first, I tried to search "sidebar" on github, but I got 448 code files. Luckily I found the sidebars folder at the top:
Image description

So I went to the sidebars folder which has a README and gives the basic steps, but the sidebar is complicated and hard to navigate, also hard for to add in my java project.

Image description

So I tried to search code block and get two main files:
packages/docusaurus-theme-common/src/utils/codeBlockUtils.ts
packages/docusaurus-theme-classic/src/theme/CodeBlock/Content/String.tsx

I read these two files and get the detail information:

  1. Docusaurus using codeBlockUtils.ts to get commentPattern.
    It has the basic structure:
    type CommentType
    type MagicCommentConfig
    func getCommentPattern
    func getAllMagicCommentDirectiveStyles
    func parseCodeBlockTitle
    func containsLineNumbers
    func parseLanguage
    func parseLines
    func getPrismCssVariables

    It is a collection of utility functions and regular expressions for handling and processing code blocks in Markdown. It allows to parse code blocks, extract metadata, and apply syntax highlighting based on language-specific comment patterns.

  2. Docusaurus using function CodeBlockString(in String.tsx to create the code part). It only has two function:
    func normalizeLanguage
    func CodeBlockString

    It is a React component used for rendering code blocks in a documentation website. It leverages the prism-react-renderer library to apply syntax highlighting to the code and provides various features like line numbering, copying code to the clipboard, and word wrapping.

CodeBlockString using parseLines to get clean code, then output

Top comments (0)