diff --git a/openspec/changes/add-toc-depth/.openspec.yaml b/openspec/changes/archive/2026-09-28-add-toc-depth/.openspec.yaml similarity index 100% rename from openspec/changes/add-toc-depth/.openspec.yaml rename to openspec/changes/archive/2026-09-28-add-toc-depth/.openspec.yaml diff --git a/openspec/changes/add-toc-depth/design.md b/openspec/changes/archive/2026-09-28-add-toc-depth/design.md similarity index 100% rename from openspec/changes/add-toc-depth/design.md rename to openspec/changes/archive/2026-09-28-add-toc-depth/design.md diff --git a/openspec/changes/add-toc-depth/proposal.md b/openspec/changes/archive/2026-09-28-add-toc-depth/proposal.md similarity index 100% rename from openspec/changes/add-toc-depth/proposal.md rename to openspec/changes/archive/2026-09-28-add-toc-depth/proposal.md diff --git a/openspec/changes/add-toc-depth/specs/toc-depth/spec.md b/openspec/changes/archive/2026-09-28-add-toc-depth/specs/toc-depth/spec.md similarity index 100% rename from openspec/changes/add-toc-depth/specs/toc-depth/spec.md rename to openspec/changes/archive/2026-09-28-add-toc-depth/specs/toc-depth/spec.md diff --git a/openspec/changes/add-toc-depth/tasks.md b/openspec/changes/archive/2026-09-28-add-toc-depth/tasks.md similarity index 100% rename from openspec/changes/add-toc-depth/tasks.md rename to openspec/changes/archive/2026-09-28-add-toc-depth/tasks.md diff --git a/openspec/specs/toc-depth/spec.md b/openspec/specs/toc-depth/spec.md new file mode 100644 index 0000000..f87423f --- /dev/null +++ b/openspec/specs/toc-depth/spec.md @@ -0,0 +1,63 @@ +# toc-depth Specification + +## Purpose + +Lets the user limit the generated TOC to headings up to a given level, e.g. only `#` and +`##`, for any input. + +## Requirements + +### Requirement: TOC limited by heading level + +With `--depth ` where `NUM` is greater than 0, the TOC SHALL contain entries only for +headings whose level is less than or equal to `NUM` (`#` is level 1, `######` is level +6). The level is absolute: it does not depend on the highest level present in the +document. The remaining entries SHALL be the same as without `--depth`: same text, same +anchor, same order, same indentation of `(level - 1) * indent` spaces. This SHALL apply +to every input: stdin, a local file, a remote URL, several inputs, and `--insert`. + +`--depth ` SHALL be accepted after `--indent ` (when given) and before `-`, +`--insert`, `--no-backup`, `--hide-footer`, `--skip-header` and the inputs. + +#### Scenario: Local file + +- **WHEN** the user runs `gh-md-toc --depth 2 "tests/test directory/test_depth.md"`, + where the file has the headings `# Title one`, `## Section`, `### Subsection`, + `#### Deep`, `# Title two` +- **THEN** the TOC entries are `* [Title one](#title-one)`, ` * [Section](#section)`, + `* [Title two](#title-two)`, followed by + `` + +#### Scenario: Stdin + +- **WHEN** the user runs + `cat "tests/test directory/test_depth.md" | gh-md-toc --depth 1 -` +- **THEN** the output is `* [Title one](#title-one)` and `* [Title two](#title-two)` + +### Requirement: No limit by default + +Without `--depth`, or with `--depth 0`, the TOC SHALL contain an entry for every heading +of the document, as before this change. + +#### Scenario: Without the option + +- **WHEN** the user runs `gh-md-toc "tests/test directory/test_depth.md"` +- **THEN** the TOC entries are `* [Title one](#title-one)`, ` * [Section](#section)`, + ` * [Subsection](#subsection)`, ` * [Deep](#deep)`, + `* [Title two](#title-two)` + +#### Scenario: Zero depth + +- **WHEN** the user runs `gh-md-toc --depth 0 "tests/test directory/test_depth.md"` +- **THEN** the TOC entries are the same as without the option + +### Requirement: Help lists the option + +`--help` SHALL list `--depth ` in the "Options" section right after +`--indent `. + +#### Scenario: Help output + +- **WHEN** the user runs `gh-md-toc --help` +- **THEN** the line after ` --indent Set indent size. Default: 3.` is + ` --depth Max heading level to include into TOC. Default: 0 (all levels).`