Skip to content

fix(toc): indent TOC entries relative to the top heading level - #180

Merged
ekalinin merged 1 commit into
masterfrom
fix/relative-toc-indent
Oct 16, 2026
Merged

ekalinin merged 1 commit into
masterfrom
fix/relative-toc-indent

Conversation

@ekalinin

Copy link
Copy Markdown
Owner

Summary

Fixes #30: the indent of a TOC entry was (level - 1) * indent spaces, counted from
# even when the document has no # heading. When the first entry got 4 or more
spaces, GitHub rendered the whole TOC as a code block:

  • ### / #### with the default indent: 6 spaces before the first entry (also with
    --insert).

  • ## / ### with --indent 4: 4 spaces before the first entry.

  • gh-md-toc: the awk script in gh_toc_grab keeps the entries and prints them in an
    END block with (level - min_level) * indent spaces, where min_level is the
    smallest heading level of the document. The END block is added to both awk
    branches (default and OS/390). Each input of several inputs has its own
    min_level. --depth stays absolute, --numbered needs no changes.

  • tests/: new fixture test_noh1.md without a # heading and three tests: local
    file, stdin with --indent 4, stdin with --depth 2.

  • openspec/changes/fix-relative-toc-indent: proposal, design, tasks, a new
    toc-indent spec and deltas for remote-toc, toc-depth, toc-numbered, which
    stated (level - 1) * indent.

Output for documents with a # heading is byte-for-byte the same, so no existing
assertions changed. For a document without a # heading, a TOC that --insert put
there earlier changes on the next run.

Not covered: a document whose first heading is deeper than a later one (e.g. ###
before ##) with --indent 4 or more still gets a code block.

Testing

  • Without the fix the three new tests fail; with the fix all 25 pass.
  • make lint passes.
  • The three cases above render as <ul> with the GitHub markdown API, not
    <pre><code>.

Without a level 1 heading the first TOC entry got (level-1)*indent spaces,
and with 4 or more spaces GitHub rendered the whole TOC as a code block.
Entries are now indented by (level-min_level)*indent, where min_level is the
smallest heading level of the document. Output for documents with a level 1
heading is unchanged.

Fixes #30
@ekalinin
ekalinin merged commit 7af407a into master Oct 16, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

TOC With No 1st Level Heading is Output as Code

1 participant