[Feature] Warn about headings that skip a level

Open
  • Is something wrong?
#97 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
45/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
github, go
Domain
backend, cli

Research direction

Read the TOC generation and filtering paths for --depth and --start-depth, along with the implementation of --numbered outline referenced in the issue. Decide whether to warn for every skipped level or only cases affected by indentation, and what link the warning should use. Done means warnings go to stderr for the retained entries, with each input checked independently and the TOC output and exit code unchanged.

Written by the indexing model from the issue text.

Description

enhancement

Is your feature request related to a problem? Please describe.

When a heading skips a level (# Title followed by ### Skipped), GitHub can render its
TOC entry as text of the parent entry, on one line. The TOC is built without any notice.
The same request for the Bash version is ekalinin/github-markdown-toc#75, and it is
implemented there in ekalinin/github-markdown-toc#187.

Here it depends on the indent. TOCs rendered by the GitHub Markdown API:

Headings Indent Rendered
# Title two, then ### Skipped 2 (default) a nested list, as expected
# Title two, then ### Skipped 3 one item: Title two * Skipped
# Title, then #### Deep 2 (default) one item: Title * Deep

Describe the solution you'd like

The same warning as in the Bash version. For every TOC entry whose heading level is
greater than the level of its parent plus 1, print to stderr:

Warning: heading 'Skipped' (level 3) skips a level after 'Title two' (level 1), see https://github.com/ekalinin/github-markdown-toc/issues/75

Behavior in the Bash version:

  • The TOC does not change: on stdout and in the file with --insert. The warning never
    goes to stdout or into the file, and the exit code stays the same.
  • The parent of an entry is the nearest previous TOC entry with a lower level, as for
    --numbered outline (#92).
  • One line per such entry, in document order. An entry without a parent gets no warning.
  • It applies to every input. With several inputs each document is checked on its own,
    and each line starts with the input as given on the command line, followed by : .
  • With --depth, only the entries kept by --depth are checked, and the parent is taken
    among them.

Additional context

  • Here entries are also dropped by --start-depth. The check should use only the entries
    that stay in the TOC, as with --depth.
  • To decide: warn on every skipped level, as the Bash version does, or only when the
    indent makes GitHub render the entry as text (see the table above).
  • To decide: the link in the message points to the issue of the Bash version.
Dominant language
Go
Stars
525
Forks
89
Avg merge
6m
Merged PRs (30d)
1

Getting set up

  • Ships a Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ekalinin/github-markdown-toc.go

All issues in ekalinin/github-markdown-toc.go

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.