Skip to main content

Creating a Topic Directory Workflow

This document defines the standard way to add a new topic directory in this repo going forward.

The target behavior is:

  • Clicking a topic in the left sidebar takes you to a topic index page first, not directly to the first article
  • The topic page automatically lists all articles under that directory, matching the behavior of docs/DataStructer/sorting-algorithms
  • The frontend displays Chinese names, but directory names, filenames, and browser URLs remain in stable English

If you continue adding new topic directories to sections like docs/SuperComputer, docs/DataStructer, or docs/Python, default to this document.

Two Existing Examples First​

  • docs/DataStructer/sorting-algorithms in Data Structures
  • docs/SuperComputer/slurm-scheduler-system in Super Computing

Both currently satisfy the same behavior:

  • The sidebar displays the Chinese topic name
  • Clicking the topic takes you to an auto-generated topic index page
  • The topic index page lists the articles under that topic

Core Principles​

1. Use generated-index to Get a Topic Index Page on Click​

The topic directory's _category_.json must use:

  • link.type: "generated-index"

Do not use:

  • link.type: "doc"

doc binds the topic click to a specific document, which is not what we want.

2. Do Not Hand-Write an index.mdx for Topic Directories​

If the goal is "auto-display the article list like sorting algorithms," do not create an index.mdx in the topic directory as a homepage.

The reason is straightforward:

  • generated-index already generates the topic page
  • A hand-written index.mdx easily occupies the same route
  • Once the route is occupied, clicking the topic takes you to your hand-written doc instead of the auto-generated index page

3. English Directory and File Names, Chinese Display Names​

When creating a new topic directory, follow this convention by default:

  • Directory name: English kebab-case
  • File name: English kebab-case
  • Topic display name: Chinese in _category_.json label
  • Article title: Chinese in the document's # H1

For example:

docs/SuperComputer/slurm-scheduler-system/
docs/SuperComputer/slurm-scheduler-system/slurm-basic-usage.mdx

The display can be:

  • Slurm Scheduler System
  • Basic Usage of SLURM

But the browser URL stays in English.

4. Keep Front Matter Minimal​

For regular articles under these topics, do not write redundant front matter by default.

Keep at minimum:

  • sidebar_position

Keep as needed:

  • slug: only when the path must decouple from the filename
  • sidebar_label: only when the sidebar name must differ from H1
  • title / description: only when you truly need to override the auto-derived values

If the H1, filename, and path are already reasonable, do not duplicate the same information.

Standard Process​

Step 1: Create the Topic Directory​

Place the directory under the corresponding section:

docs/<Section>/<topic-dir>/

For example:

docs/SuperComputer/slurm-scheduler-system/
docs/DataStructer/sorting-algorithms/

Step 2: Create _category_.json​

Every topic directory must have a _category_.json.

Standard template:

{
  "label": "Chinese Topic Name",
  "position": 0,
  "link": {
    "type": "generated-index",
    "slug": "/category/topic-slug",
    "description": "A short description of this topic."
  }
}

Each field's purpose:

  • label: the topic name displayed in the frontend, in Chinese
  • position: the topic's sort order within its parent directory
  • link.type: must be generated-index
  • link.slug: English URL for the "All Articles" auto-generated category page
  • description: short description on the topic index page

Step 3: Place Articles Under the Topic​

Topic articles go directly in this directory.

For example:

docs/SuperComputer/slurm-scheduler-system/scheduler-system-overview.mdx
docs/SuperComputer/slurm-scheduler-system/slurm-basic-usage.mdx
docs/SuperComputer/slurm-scheduler-system/slurm-advanced-usage.mdx
docs/SuperComputer/slurm-scheduler-system/slurm-common-issues-and-solutions.mdx

A minimal template for a regular article:

---
sidebar_position: 1
---

# Article Chinese Title

Write the article intro here.

For PDF preview pages, continue reusing:

When _category_.json Alone Is Enough​

If the section fully relies on the file system to auto-generate the sidebar and you only care about the topic page under "All Articles," then writing _category_.json alone is usually sufficient.

When You Must Also Modify sidebars.js​

If the section has its own dedicated sidebar in the navbar, and that sidebar is not a pure file-system auto-expand but is explicitly organized like:

  • DataStructerSidebar
  • SuperComputerSidebar
  • PythonSidebar

Then you cannot just create the directory and _category_.json. You must also update sidebars.js.

Otherwise, common outcomes include:

  • The topic appears under "All Articles"
  • But the click behavior in the section's own sidebar is wrong
  • Or the topic entry you want does not appear at all
  • Or clicking goes directly to the first article instead of the topic index page

Step 4: Register the Topic in sidebars.js​

For sections with a dedicated sidebar, topics should use:

  • createTopLevelAutogeneratedCategoryWithLink

and be placed in the corresponding section's items.

Reference template:

createTopLevelCategoryWithLink({
  label: 'SuperComputer',
  slug: '/SuperComputer',
  description: 'HPC environments, cluster tools, and parallel computing practice.',
  items: [
    createTopLevelAutogeneratedCategoryWithLink({
      label: 'Slurm Scheduler System',
      dirName: 'SuperComputer/slurm-scheduler-system',
      slug: '/SuperComputer/slurm-scheduler-system',
      description: 'Resources organized around the Slurm scheduler.',
    }),
    ...SUPER_COMPUTER_ROOT_DOC_IDS,
  ],
})

Two things to pay special attention to here.

1. The Topic slug Should Follow the Section Path​

For example:

/SuperComputer/slurm-scheduler-system
/DataStructer/sorting-algorithms

This way, clicking the topic in the section's own sidebar navigates to:

/docs/SuperComputer/slurm-scheduler-system
/docs/DataStructer/sorting-algorithms

Which is exactly the topic index page URL you want.

2. Article Order at the Section Root Must Be Explicitly Maintained​

If you switch a section like SuperComputerSidebar from "pure auto-generated" to "explicitly organized," you must also list the order of root-level articles that are not inside any topic subdirectory.

The current repo does this with:

const SUPER_COMPUTER_ROOT_DOC_IDS = [
  'SuperComputer/mcc24-review',
  'SuperComputer/diy-docker-image',
  // ...
];

Then in the sidebar:

items: [
  createTopLevelAutogeneratedCategoryWithLink(...),
  ...SUPER_COMPUTER_ROOT_DOC_IDS,
]

The sole purpose of this is:

  • Keep the order of articles outside topics stable

Step 5: Do Not Hand-Write the Topic Homepage​

Once sidebars.js and _category_.json are both configured, the topic index page should be entirely auto-generated by Docusaurus.

In other words, do not additionally create:

docs/<Section>/<topic-dir>/index.mdx

Unless your goal is no longer an "auto-generated topic index page" and you explicitly want a hand-written homepage.

How to Understand Routes​

When adding new topics in the future, use these rules to understand routes.

1. slug in _category_.json​

This is typically used for "All Articles" or auto-generated category pages, for example:

/category/slurm-scheduler-system

The final access path is usually:

/docs/category/slurm-scheduler-system

2. slug of the Topic Entry in sidebars.js​

This is used by the section's own sidebar, for example:

/SuperComputer/slurm-scheduler-system

The final access path is usually:

/docs/SuperComputer/slurm-scheduler-system

This is the route for "clicking the topic index in the Super Computing sidebar to enter the topic page."

Do Not Do This​

When adding new topic directories going forward, avoid these mistakes by default.

Mistake 1: Setting _category_.json to link.type: "doc"​

Consequence:

  • Clicking the topic takes you to a specific document
  • Not the auto-generated topic index page

Mistake 2: Hand-Writing index.mdx as a Topic Homepage​

Consequence:

  • Occupies the topic route
  • Displaces generated-index
  • Clicking the topic becomes "enter the hand-written document"

Mistake 3: Creating Only Directory and Articles Without Updating the Explicit Sidebar​

Consequence:

  • The topic might appear under "All Articles"
  • But the click behavior in the section sidebar is wrong
  • Or you do not get the /docs/<Section>/<topic-dir> route at all

Mistake 4: Using Chinese Characters in Directory and File Names​

Consequence:

  • Reduced path readability and stability
  • Manual referencing, searching, and migration become more painful

This repo now uniformly follows "English paths + Chinese display names."

_category_.json​

{
  "label": "Chinese Topic Name",
  "position": 0,
  "link": {
    "type": "generated-index",
    "slug": "/category/topic-slug",
    "description": "Short topic description."
  }
}

Article Template​

---
sidebar_position: 1
---

# Article Chinese Title

Write the intro here.

sidebars.js Topic Template​

createTopLevelAutogeneratedCategoryWithLink({
  label: 'Chinese Topic Name',
  dirName: 'Section/topic-dir',
  slug: '/Section/topic-dir',
  description: 'Short topic description.',
})

Verify After Every Creation​

At least run once:

npm run build

Then check:

  1. No duplicate routes in the build
  2. No broken links in the build
  3. Clicking the topic in the left sidebar takes you to the topic index page
  4. The topic index page auto-lists the articles under the topic
  5. Article order within the topic is correct
  6. Browser URLs stay in English

Default Rule Going Forward​

When someone says "create a new topic directory" in this repo, default to this process:

  1. Create the directory with English directory and file names
  2. Configure generated-index in _category_.json
  3. Articles keep only essential front matter
  4. If the section has a dedicated sidebar, update sidebars.js accordingly
  5. Do not hand-write index.mdx
  6. Run npm run build at the end

Only then will the click behavior be stable and consistent with the current Sorting Algorithms and Slurm Scheduler System.