Skip to main content

Notes Intro

Hello and welcome to notes.SREboy.com!

Why I am doing this​

Here I will host my study notes, which will be a collection of notes from various sources, including books, articles, and videos. I will also include my own thoughts and ideas on the topics I study.

Markdown Docusaurus Tips​

As you may have noticed, I am using Docusaurus to build this documentation. Here are some tips I have learned along the way.

Example Code Blocks​

In JavaScript, trying to access properties on null will error.

const name = null;
console.log(name.toUpperCase());
// Uncaught TypeError: Cannot read properties of null (reading 'toUpperCase')
import React from 'react';

function MyComponent(props) {
  if (props.isBar) {
    return <div>Bar</div>;
  }

  return <div>Foo</div>;
}

export default MyComponent;
docs/tutorials/_category_.json
{
  "position": 2.5,
  "label": "Tutorial",
  "collapsible": true,
  "collapsed": false,
  "className": "red",
  "link": {
    "type": "generated-index",
    "title": "Tutorial overview"
  },
  "customProps": {
    "description": "This description can be used in the swizzled DocCard"
  }
}
sidebars.js
export default {
  myAutogeneratedSidebar: [
    {
      type: 'autogenerated',
      dirName: '.', // '.' means the current docs folder
    },
  ],
};
docs/tutorials/tutorial-easy.md
---
sidebar_position: 2
sidebar_label: Easy
sidebar_class_name: green
---

# Easy Tutorial

This is the easy tutorial!

Collapsible Blocks​

A real-world example

Consider this file structure:

docs
├── api
│   ├── product1-api
│   │   └── api.md
│   └── product2-api
│       ├── basic-api.md
│       └── pro-api.md
├── intro.md
└── tutorials
    ├── advanced
    │   ├── advanced1.md
    │   ├── advanced2.md
    │   └── read-more
    │       ├── resource1.md
    │       └── resource2.md
    ├── easy
    │   ├── easy1.md
    │   └── easy2.md
    ├── tutorial-end.md
    ├── tutorial-intro.md
    └── tutorial-medium.md

And assume every doc's ID is just its file name. If you define an autogenerated sidebar like this:

sidebars.js
export default {
  mySidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorials',
    },
    {
      type: 'autogenerated',
      dirName: 'api', // Generate sidebar slice from docs/api
    },
    {
      type: 'category',
      label: 'Community',
      items: ['team', 'chat'],
    },
  ],
};

It would be resolved as:

sidebars.js
export default {
  mySidebar: [
    'intro',
    {
      items: [
        'tutorial-intro',
        // Two files in docs/tutorials/easy
        'easy1',
        'easy2',
        'tutorial-medium',
        // Two files and a folder in docs/tutorials/advanced
        'advanced1',
        'advanced2',
        {
          type: 'category',
          label: 'read-more',
          items: ['resource1', 'resource2'],
        },
        'tutorial-end',
      ],
    },
  ],
};

Note how the autogenerate source directories themselves don't become categories: only the items they contain do. This is what we mean by "sidebar slice".

Tips​

archive older versions

If you deploy your site on a Jamstack provider (e.g. Netlify), the provider will save each production build as a snapshot under an immutable URL. You can include archived versions that will never be rebuilt as external links to these immutable URLs. The Jest website and the Docusaurus website both use such pattern to keep the number of actively built versions low.

danger

Some content with Markdown syntax. Check this api.

MUST READ

Some content with Markdown syntax. Check this api.

note

Pages do not have sidebars, only docs do.

Meta-Only

If you are setting up a new Docusaurus website for a Meta open source project, run this command inside an internal repository, which comes with some useful Meta-specific defaults:

scarf static-docs-bootstrap
tip

If a folder only has one index page, it will be turned into a link instead of a category. This is useful for asset collocation:

some-doc
├── index.md
├── img1.png
└── img2.png
info

If the link is explicitly specified, Docusaurus will not apply any default conventions.

The doc links can be specified relatively, e.g. if the category is generated with the guides directory, "link": {"type": "doc", "id": "intro"} will be resolved to the ID guides/intro, only falling back to intro if a doc with the former ID doesn't exist.

You can also use link: null to opt out of default conventions and not generate any category index page.

warning

Prefer using additional metadata.

Updating a number prefix can be annoying, as it can require updating multiple existing Markdown links:

docs/02-Tutorial Easy/01-First Part.md
- Check the [Tutorial End](../04-End.mdx);
+ Check the [Tutorial End](../05-End.mdx);
Parent

Parent content

Child

Child content

Deep Child

Deep child content

Use tabs in admonitions
This is an apple 🍎
💡Did you know...

Use plugins to introduce shorter syntax for the most commonly used JSX elements in your project.

Tables​

PathVersionURL
versioned_docs/version-1.0.0/hello.md1.0.0/docs/1.0.0/hello
versioned_docs/version-1.1.0/hello.md1.1.0 (latest)/docs/hello
docs/hello.mdcurrent/docs/next/hello