Skip to content

fix: require name key in each toc.yaml entry #1965

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kings9527 wants to merge 2 commits into
base: master
Choose a base branch
from
Open

fix: require name key in each toc.yaml entry #1965

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cec0037
fix: require name key in each toc.yaml entry
kings9527 May 31, 2026
12a0fda
fix: adapt tests and generic-includer for required toc item name vali…
kings9527 Jun 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions schemas/toc-schema.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ definitions:

TocItem:
type: object
required: ['name']
properties:
name:
type: string
Expand Down
54 changes: 36 additions & 18 deletions src/commands/build/features/watch/index.spec.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -329,14 +329,16 @@ describe('Build watch feature', () => {
'./toc-i.yaml',
dedent`
items:
- href: index.md
- name: Item
href: index.md
`,
);
await create(
'./toc.yaml',
dedent`
items:
- include:
- name: Item
include:
path: toc-i.yaml
mode: link
`,
Expand All @@ -354,8 +356,10 @@ describe('Build watch feature', () => {
'./toc-i.yaml',
dedent`
items:
- href: index.md
- href: about.md
- name: Item
href: index.md
- name: Item
href: about.md
`,
);

Expand All @@ -371,7 +375,8 @@ describe('Build watch feature', () => {
'./toc-i.yaml',
dedent`
items:
- href: index.md
- name: Item
href: index.md
`,
);

Expand Down Expand Up @@ -410,14 +415,16 @@ describe('Build watch feature', () => {
'./openapi-spec.yaml',
dedent`
items:
- href: methodA.md
- name: Item
href: methodA.md
`,
);
await create(
'./toc.yaml',
dedent`
items:
- include:
- name: Item
include:
path: openapi
includers:
- name: mock-openapi
Expand All @@ -437,8 +444,10 @@ describe('Build watch feature', () => {
'./openapi-spec.yaml',
dedent`
items:
- href: methodA.md
- href: methodB.md
- name: Item
href: methodA.md
- name: Item
href: methodB.md
`,
);

Expand All @@ -454,7 +463,8 @@ describe('Build watch feature', () => {
'./openapi-spec.yaml',
dedent`
items:
- href: methodB.md
- name: Item
href: methodB.md
`,
);

Expand All @@ -481,15 +491,18 @@ describe('Build watch feature', () => {
'./inner/toc.yaml',
dedent`
items:
- href: index.md
- name: Item
href: index.md
`,
);
await create(
'./toc.yaml',
dedent`
items:
- href: about.md
- include:
- name: Item
href: about.md
- name: Item
include:
path: inner/toc.yaml
mode: link
`,
Expand Down Expand Up @@ -527,8 +540,10 @@ describe('Build watch feature', () => {
'./toc.yaml',
dedent`
items:
- href: index.md
- href: about.md
- name: Item
href: index.md
- name: Item
href: about.md
`,
);

Expand Down Expand Up @@ -565,15 +580,18 @@ describe('Build watch feature', () => {
'./inner/toc.yaml',
dedent`
items:
- href: about.md
- name: Item
href: about.md
`,
);
await create(
'./toc.yaml',
dedent`
items:
- href: index.md
- include: {mode: 'link', path: './inner/toc.yaml'}
- name: Item
href: index.md
- name: Item
include: {mode: 'link', path: './inner/toc.yaml'}
`,
);

Expand Down
29 changes: 22 additions & 7 deletions src/core/toc/__snapshots__/index.spec.ts.snap
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,28 +3,36 @@
exports[`toc-loader > includers > should fix include path 1`] = `
"items:
- name: Common item
- name: Include Entry
items: []
path: toc.yaml
"
`;

exports[`toc-loader > includers > should handle registered includer 1`] = `
"items:
- name: Common item
- name: Include Entry
items: []
path: toc.yaml
"
`;

exports[`toc-loader > includers > should merge includer toc to parent 1`] = `
"items:
- name: Common item
- name: Includer item 1
- name: Include Entry
items:
- name: Includer item 1
path: toc.yaml
"
`;

exports[`toc-loader > includers > should pass extra params to includer 1`] = `
"items:
- name: Common item
- name: Include Entry
items: []
path: toc.yaml
"
`;
Expand Down Expand Up @@ -53,17 +61,23 @@ exports[`toc-loader > includes > should merge deep includes in merge mode 1`] =
items:
- name: Inner Merge Item 1
href: _includes/core/merge-item-1.md
- name: Inner Deep Merge Item 1
href: _includes/core/deep-merge-item-1.md
- name: Inner Sub Item 1
href: _includes/core/sub-item-1.md
- name: Deep Merge Include
items:
- name: Inner Deep Merge Item 1
href: _includes/core/deep-merge-item-1.md
- name: Sub Include
items:
- name: Inner Sub Item 1
href: _includes/core/sub-item-1.md
path: toc.yaml
"
`;

exports[`toc-loader > includes > should merge includes in flat link mode 1`] = `
"items:
- name: Inner Item 1
- name: Outer Item
items:
- name: Inner Item 1
path: toc.yaml
"
`;
Expand Down Expand Up @@ -473,7 +487,8 @@ path: toc.yaml

exports[`toc-loader > should interpolate item href 1`] = `
"items:
- href: file.md
- name: Item with href
href: file.md
path: toc.yaml
"
`;
Expand Down
79 changes: 66 additions & 13 deletions src/core/toc/index.spec.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -256,7 +256,8 @@ describe('toc-loader', () => {
test(
dedent`
items:
- href: "{{file}}"
- name: Item with href
href: "{{file}}"
`,
{},
{file: './file.md'},
Expand Down Expand Up @@ -407,7 +408,8 @@ describe('toc-loader', () => {
test(
dedent`
items:
- include:
- name: Outer Item
include:
path: _includes/core/i-toc.yaml
mode: link
`,
Expand Down Expand Up @@ -484,10 +486,12 @@ describe('toc-loader', () => {
items:
- name: Inner Merge Item 1
href: merge-item-1.md
- include:
- name: Deep Merge Include
include:
path: ../deep-merge/i-toc.yaml
mode: merge
- include:
- name: Sub Include
include:
path: ./sub/toc.yaml
mode: merge
`,
Expand All @@ -513,7 +517,8 @@ describe('toc-loader', () => {
dedent`
items:
- name: Common item
- include:
- name: Include Entry
include:
path: _includes/core/i-toc.yaml
mode: link
includers:
Expand All @@ -536,7 +541,8 @@ describe('toc-loader', () => {
const content = dedent`
items:
- name: Common item
- include:
- name: Include Entry
include:
path: _includes/core/i-toc.yaml
mode: link
includers:
Expand Down Expand Up @@ -572,7 +578,8 @@ describe('toc-loader', () => {
const content = dedent`
items:
- name: Common item
- include:
- name: Include Entry
include:
path: _includes/core
mode: link
includers:
Expand Down Expand Up @@ -609,7 +616,8 @@ describe('toc-loader', () => {
const content = dedent`
items:
- name: Common item
- include:
- name: Include Entry
include:
path: _includes/core
mode: link
includers:
Expand Down Expand Up @@ -646,7 +654,8 @@ describe('toc-loader', () => {
const content = dedent`
items:
- name: Common item
- include:
- name: Include Entry
include:
path: _includes/core
mode: link
includers:
Expand Down Expand Up @@ -1174,6 +1183,46 @@ describe('toc-loader', () => {
);
});

it('should log and throw for toc item missing name key', async () => {
const content = dedent`
items:
- href: page.md
`;
const {run, toc} = setupService({});
const loggerError = vi.spyOn(run.logger, 'error');

mockData(run, content, {}, {}, []);

await expect(toc.init(['toc.yaml'] as NormalizedPath[])).rejects.toMatchObject({
message:
"Invalid toc structure in toc.yaml: 1 toc item(s) missing required 'name' key",
});
expect(loggerError).toHaveBeenCalledWith(
"Invalid toc structure in toc.yaml at items[0]: missing required 'name' key",
);
});

it('should log and throw for nested toc item missing name key', async () => {
const content = dedent`
items:
- name: Parent
items:
- href: child.md
`;
const {run, toc} = setupService({});
const loggerError = vi.spyOn(run.logger, 'error');

mockData(run, content, {}, {}, []);

await expect(toc.init(['toc.yaml'] as NormalizedPath[])).rejects.toMatchObject({
message:
"Invalid toc structure in toc.yaml: 1 toc item(s) missing required 'name' key",
});
expect(loggerError).toHaveBeenCalledWith(
"Invalid toc structure in toc.yaml at items[0].items[0]: missing required 'name' key",
);
});

it('should log and throw for invalid toc entry href', async () => {
const {run, toc} = setupService({});
const loggerError = vi.spyOn(run.logger, 'error');
Expand Down Expand Up @@ -1330,7 +1379,8 @@ describe('entries filtering logic', () => {
items:
- name: Root Item
href: root-page.md
- include:
- name: Sub TOC Include
include:
path: sub/toc.yaml
mode: link
`);
Expand Down Expand Up @@ -1419,7 +1469,8 @@ describe('entries filtering logic', () => {
.thenResolve(dedent`
title: Root TOC
items:
- include:
- name: Level 1 Include
include:
path: level1/toc.yaml
mode: link
`);
Expand All @@ -1431,7 +1482,8 @@ describe('entries filtering logic', () => {
items:
- name: Level 1 Item
href: level1-page.md
- include:
- name: Level 2 Include
include:
path: level2/toc.yaml
mode: link
`);
Expand Down Expand Up @@ -1495,7 +1547,8 @@ describe('include dependency handling', () => {
when(run.read).calledWith(normalizePath(join(run.input, './toc.yaml')) as AbsolutePath)
.thenResolve(dedent`
items:
- include:
- name: Include Entry
include:
path: included/toc.yaml
mode: link
`);
Expand Down
Loading