repomatic.awesome_toc module

Remove the table-of-contents entries awesome-lint forbids.

Backs the fix-awesome-toc command, which runs on awesome-* repositories right after repomatic run mdformat regenerates the ToC of every readme.

Note

This is the one operation that has no job, PR branch or template of its own, against the rule in claude.md § Naming conventions for automated operations. It corrects what format-markdown just wrote, so it has to share that job’s working tree: given its own job, the two would land in separate PRs and undo each other on every push, format-markdown re-adding the entries this command had removed.

mdformat-toc lists every heading in range and offers no exclusion mechanism of its own, so the entries have to be deleted afterwards.

Todo

Delete this module once mdformat-toc can express the exclusion in the ToC marker itself, through hukkin/mdformat-toc#17 or hukkin/mdformat-toc#20.

repomatic.awesome_toc.FORBIDDEN_HEADINGS: tuple[str, ...] = ('Contents', 'Contributing', 'Footnotes', 'Related Lists')

Headings awesome-lint refuses to see listed in the table of contents.

Mirrors the roster in awesome-lint’s toc.js, plus the heading owning the ToC itself (Contents), whose entry trips remark-lint:awesome-toc:

✖  26:1  ToC item "Contents" does not match corresponding heading "Meta"

These are the English names, the only ones awesome-lint knows. A translated readme names the same sections in its own language, which is why matching on this roster alone is not enough: see forbidden_headings_for().

repomatic.awesome_toc.README_RE = re.compile('^readme(\\.[^.]+)?\\.md$')

Match readme.md and every readme.{lang}.md translation beside it.

Only the repository root is scanned. The find ./ this replaced walked the whole tree, which on a checkout carrying a node_modules/ directory would have reached a few hundred vendored readmes.

repomatic.awesome_toc.REFERENCE_README = 'readme.md'

The English readme, whose heading positions every translation is mapped onto.

repomatic.awesome_toc.HEADING_RE = re.compile('^\\#{1,6}[ \\t]+(?P<text>.+?)[ \\t]*\\#*[ \\t]*$', re.MULTILINE)

Match an ATX heading and capture its text, closing sequence excluded.

repomatic.awesome_toc.TOC_ENTRY_RE = re.compile('^[ \\t]*- \\[(?P<text>.+)\\]\\(#[^)]*\\)$')

Match one mdformat-toc list entry and capture its link text.

repomatic.awesome_toc.TOC_START_RE = re.compile('^<!--\\s*mdformat-toc\\s+start\\b.*-->$', re.IGNORECASE)

Match the opening marker of an mdformat-toc block.

repomatic.awesome_toc.TOC_END_RE = re.compile('^<!--\\s*mdformat-toc\\s+end\\s*-->$', re.IGNORECASE)

Match the closing marker of an mdformat-toc block.

repomatic.awesome_toc.FENCE_RE = re.compile('^[ \\t]*(?P<fence>`{3,}|~{3,})')

Match the delimiter of a fenced code block.

repomatic.awesome_toc.headings(content)[source]

List the ATX heading texts of a Markdown document, in document order.

Parameters:

content (str) – The full Markdown document.

Return type:

list[str]

Returns:

Every heading text, code fences excluded.

repomatic.awesome_toc.forbidden_headings_for(content, reference_headings=None)[source]

Resolve which heading texts must not appear in content’s ToC.

Always includes the English FORBIDDEN_HEADINGS that awesome-lint knows, since a translation routinely leaves some of them untranslated.

On top of that, when reference_headings is given and the document has the same number of headings, the heading occupying each forbidden position in the reference is forbidden here too. That positional mapping is what carries the rule across languages: repomatic cannot know that 贡献 translates Contributing, but it can see that both sit at the same index of a readme and its translation. Headings survive formatting untouched, so the mapping holds even against an already-stripped reference.

Parameters:
Return type:

set[str]

Returns:

The heading texts whose ToC entry must be deleted.

repomatic.awesome_toc.strip_toc_entries(content, forbidden)[source]

Delete the ToC entries of content whose link text is forbidden.

Only the mdformat-toc block is touched: a list item elsewhere in the document that happens to link the same heading is left alone.

Parameters:

  • content (str) – The full Markdown document.

  • forbidden (set[str]) – Heading texts whose entry must go.

Return type:

tuple[str, list[str]]

Returns:

The updated document and the link texts that were deleted.

repomatic.awesome_toc.fix_awesome_toc(root=None)[source]

Strip the forbidden ToC entries from every readme under root.

Reads REFERENCE_README first so its heading positions can be mapped onto each translation, then rewrites every readme that changed. Idempotent: a second run finds nothing left to delete.

Parameters:

root (Path | None) – Directory holding the readmes. Defaults to the current one.

Return type:

dict[Path, list[str]]

Returns:

The deleted entries, keyed by the readme they came from.