Manage TOC

Overview

Use this skill when the request changes how navigation trees or heading TOCs are generated, filtered, or consumed. In this repo, TOC behavior spans build-time Gatsby code and runtime filtering helpers.

Workflow

1) Locate the TOC layer being changed

Common files:

• gatsby/toc.ts
• gatsby/toc-filter.ts
• gatsby/toc-ignore.ts
• gatsby/create-types/create-navs.ts
• src/shared/filterTOC.ts
• src/shared/filterRightToc.ts

Choose the layer deliberately:

• Build-time extraction and nav construction in gatsby/
• Runtime hiding or conditional filtering in src/shared/

2) Keep TOC membership and nav generation coherent

Current repo behavior includes:

• Parsing TOC MDX into nav structures
• Filtering build output based on TOC references
• Mapping docs to TOC names
• Special starter and essential nav handling for TiDB Cloud

If you change one of these, check whether the others must also change.

3) Prefer existing helper paths

Examples to follow:

• getFilesFromTocs() and filterNodesByToc() in gatsby/toc-filter.ts
• createNavs() in gatsby/create-types/create-navs.ts
• filterTOC() and filterRightToc() in src/shared/

Avoid duplicating TOC parsing rules in templates or components.

4) Update tests

TOC logic in this repo already has Jest coverage under gatsby/__tests__/. When changing build-time TOC behavior, add or adjust tests near the affected code.

Typical areas:

• TOC whitelist or ignore behavior
• file inclusion/exclusion from TOCs
• right TOC filtering conditions
• nav generation for starter or essential plans

5) Validate

At minimum:

• Confirm the changed TOC layer is the right one
• Confirm runtime consumers still receive the expected shape
• Run targeted Jest tests when applicable
• Run yarn test or at least the relevant test file when feasible

Output Checklist

Report:

• Which TOC build-time or runtime files changed
• Whether Jest tests were updated
• What navigation or filtering behavior changed
• Whether yarn test or targeted tests were run