# Docs Toc Generator

> 自动扫描指定 docs 目录，读取所有文档的 frontmatter 和 _category_.json，生成结构化的总目录页面内容。This skill should be used when the user wants to generate or update a table-of-contents / index page (e.g., 0-learn.md) that lists all documents under a given docs section. Use when this capability is needed.

- Skill: `tomevault-io/docs-toc-generator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/docs-toc-generator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/docs-toc-generator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/docs-toc-generator

---


# Docs TOC Generator - 文档总目录生成器

## Purpose

Scan a docs directory (e.g., `docs/tech/`), read all `_category_.json` and markdown frontmatter, then generate a structured table-of-contents page that links to every document in the section.

## When to Use

- When the user mentions generating, updating, or refreshing a table of contents / index page
- When the user says "生成总目录", "更新目录", "刷新目录索引" or similar phrases
- When the user references an index file like `0-learn.md` and asks to populate it
- When the user adds new documents and wants the TOC updated

## Workflow

### Step 1: Identify Target

Determine:
1. **Scan directory**: The docs section to scan (e.g., `docs/tech/`). Default to the parent directory of the target file.
2. **Target file**: The index/TOC file to update (e.g., `docs/tech/0-learn.md`).

### Step 2: Scan Directory Structure

Recursively scan the target directory:

1. **Read `_category_.json`** files to get:
   - `label`: Display name of the category
   - `position`: Sort order among sibling categories
2. **Read markdown/mdx file frontmatter** to get:
   - `title`: Document title
   - `sidebar_position`: Sort order within the category
3. **Skip** image files, source code files, and the TOC file itself.
4. **Note** subdirectories as nested categories.

### Step 3: Build TOC Structure

Organize the data into a tree:

```
Section (from _category_.json label, sorted by position)
├── Doc 1 (sorted by sidebar_position)
├── Doc 2
└── Subsection (nested _category_.json)
    ├── Doc 3
    └── Doc 4
```

Sort rules:
- Categories sorted by `position` field in `_category_.json`
- Documents sorted by `sidebar_position` in frontmatter
- Documents without `sidebar_position` appear at the end
- Use the `title` from frontmatter as display text
- For documents without frontmatter title, derive from filename

### Step 4: Generate Markdown Content

Generate the TOC content in this format:

```markdown
---
id: index
title: <Section Title>
sidebar_position: 0
---

## 总目录

### <Category 1 Label>

- [Doc Title 1](./relative/path/to/doc1)
- [Doc Title 2](./relative/path/to/doc2)

### <Category 2 Label>

- [Doc Title 3](./relative/path/to/doc3)
  - [Subdoc Title](./relative/path/to/subdoc)
```

Link format rules:
- Use relative paths from the TOC file location
- For `index.md` files, link to the directory (e.g., `./go/` instead of `./go/index.md`)
- For `readme.md` files, treat them the same as `index.md` — link to the directory (e.g., `./devtools/fix/` instead of `./devtools/fix/readme`), because Docusaurus treats `readme.md` as a directory index page
- For filenames with numeric prefixes used for sorting (e.g., `0-openwrt.md`, `1-intro.md`), the link path must **omit the numeric prefix** (e.g., `./network/openwrt` instead of `./network/0-openwrt`), because Docusaurus strips `numberPrefix` from the generated route by default
- Exception: The TOC file itself (e.g., `0-learn.md`) is excluded from scanning, so this rule does not apply to it
- For `.mdx` files, include the extension in the path
- Nested categories use indented sub-lists

### Step 5: Preserve Custom Content

If the target file already has custom content sections (like "技术文章" with external links):
- Keep those sections intact at the bottom of the file
- Only regenerate the "总目录" section
- Identify custom sections as any `## heading` that is NOT "总目录"

### Step 6: Write the File

Update the target file with the generated content, preserving:
- Original frontmatter (if any)
- Custom content sections appended after the generated TOC

## Important Notes

- Always sort categories and documents by their position/sidebar_position values
- Use Chinese display names from `_category_.json` label fields when available
- Generate relative links that work with Docusaurus routing
- **Docusaurus strips numeric prefixes** (e.g., `0-`, `1-`) from filenames when generating routes. Links must use the path **without** the numeric prefix (e.g., `./network/openwrt` not `./network/0-openwrt`)
- **`readme.md` is treated as a directory index** by Docusaurus, so link to the directory path (e.g., `./devtools/fix/`) instead of `./devtools/fix/readme`
- The skill works for any docs section (tech, life, essay), not just tech
- If a category has an `index.md`, link the category heading to it

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/hailaz) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->