Learning About Docusaurus

Hi everyone, today I'm going to be talking about Docusaurus. Docusaurus is an open source project backed by Meta, which allows developers to build a documentation website, portfolio or blog website entirely from Markdown and/or React JS. It can be really handy for those who aren't fans of web development (like me), or those who just want to push out a quick and simple website. There are several other features that it provides, but I'll be talking about one of those features that I would like to implement in my txt to html convertor project and how I tried to examine the code implementation of the feature on Docusaurus.

What's the Feature I want to Implement?

Docusaurus has the ability to generate a sidebar for your site, which can act like a table of contents to help the user navigate through the pages of your site. To create a sidebar with Docusaurus you must make sidebars.js file in the root of your website folder. In the sidebars.js file, you must make a dictionary that links to the pages of your website. Docusaurus makes one by default, however you can also make your own or remove it if you'd like. To make you own, you can do something like this;

const sidebars = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Getting Started',
      items: ['tutorial-basics/create-a-document', 'tutorial-basics/create-a-blog-post'],
    },
    'hello',
    'tutorial-basics/create-a-page'
  ],
};

Words in the dictionary like intro and hello link to Markdown files in the root of the docs folder. Doing something like 'tutorial-basics/create-a-page' also links a file that is in the docs directory, but gets the file from the tutorial-basics directory that is within the docs directory. You can also make a nested part of the side bar with the

{
      type: 'category',
      label: 'Getting Started',
      items: ['tutorial-basics/create-a-document', 'tutorial-basics/create-a-blog-post'],
    },

part. You can assign a label like "Getting Started" and then inside of the label, you can have several different links to other pages within the items tag. I also forgot to mention, that in the markdown files, you can assign a position of the file to the sidebar. For example, in my intro.md file I could do something like this

---
sidebar_position: 1
---

to say that I want this file to appear first in the sidebar. If I wanted to change the position, I can give it a value of 2 or more.

Strategies used to Find the Official Implementation

With that out of the way, we can get to the strategies I used to try to find the official implementation of the feature. I did a couple of ideas on how the developers could have made it, based on the sidebars.js file that needs to be created. But they were more of vague ideas and I needed a better idea of what was done. I used a few strategies, so I'll list them out below.

1. I first tried using git grep on my repo to try to find any sign of how sidebars are handled within the files of the website. I found out that the sidebar file must be mentioned in the docusaurus.config.js file, this was a good start. Since I then followed the sidebarPath key from the dictionary which brought me to a new file called plugin-content-docs.js. The file contained a lot about side bars, so I search the file for instances of where the word "sidebar" is mentioned and found a function called SidebarItemsGeneratorOption that links to a file called types in a sidebars folder. This was a good I was able to find what might be the folder containing most of the sidebar logic. I followed the path to the folder that Visual Studio provided. I ended up finding a file called generator.ts which included a generateSidebar function. Reading through the file was a little confusing for me (since JavaScript isn't my strong suit), but from my understanding the way the sidebar is generated is split into 4 steps based on comments provided by the developers;

• Step 1: The code extracts docs in the autogenerated directory.
• Step 2: The code then turns the extracted files into a tree structure.
• Step 3: The code then recursively transforms the tree to sidebar items, which is where the generateSidebar function comes in. It looks like the function handles the naming of the items in the sidebar, the creation of the category and assigning a position and id.
• Step 4: The code finally recursively sorts through the categories/docs and removed the position attribute from the final output, as it is only used for the sorting. It then returns the generated and sorted sidebar to be displayed.

1. I also tried to use GitHub's code search feature, but perhaps I was using it incorrectly, as searching for the feature implementation only brought me to other people's websites on my first search. I did one more search, which was this time formatted to look specifically at repos owned by Meta that include the works "Docusaurus" and "sidebars" which brought me to the code I found with git grep in my first step. So I basically found the same thing.

2. I finally used ChatGPT to try to help me. I already had the idea that everything relevant to the sidebar was being handled in the sidebar folder, so I can always look there for help. But I did kind of want a simplified idea and I could also use it in case I needed an explanation of the code written by the developers. The simplified idea was more of just making a basic table of contents, since that's basically what the sidebar is, I could maybe make the actually sidebar with some CSS. It helped me refine the idea of making an optional argument for a table of contents (sidebar) that takes in an additional python file that includes a dictionary keys and values that link to other pages in the website.

Based off of the 3 methods that I used to help me understand the way sidebars are handled. Using git grep probably helped me the most, as I was able to find out how the feature is implemented. It also helped a little with figuring out how to make proper comments. Most of the variables and functions names are somewhat self explanatory, but the comments left within the files mainly provide a walk through of everything that was done, while also explaining what values certain variables contain. I already do the latter, but not the former when I make comments. I find that I make too many comments some times, as I find myself occasionally making comments on most variables names. However, making comments in a walkthrough type of way can be very helpful to me and the person reading my code. ChatGPT also helped me, as I used it to help simplify some of the ideas I had in my head for the implementation. Although, I can also use it for explaining the dev's code, which may prove useful in the future when I work on the feature.

That's it for now. Thank you all for reading! I'm going to get to work and see if I can make a prototype for a table of contents to be generated in my project.