readme_toc.py generates duplicate fragment links for repeated headings
Maintainers usually reply within 1 day
@akhil9tiet is already working on this.
Since Oct 28, 2026.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 72/100
Research direction
Start with scripts/readme_toc.py and inspect generate_toc_lines, then run the focused regression case described in the issue. Add cases for repeated headings and different titles that normalize to the same fragment. Done means generated anchors are unique and use the expected numeric suffixes for repeated headings.
Written by the indexing model from the issue text.
Description
Summary
scripts/readme_toc.py generates the same fragment for repeated Markdown headings. GitHub assigns unique heading anchors (#setup, #setup-1, ...), so the second and later entries in a generated table of contents navigate to the first heading instead.
Minimal reproduction
On current main (inspected commit e742db9f7ba98e63e502b310857d49d047888518), run the existing helper:
from scripts.readme_toc import generate_toc_lines
print(generate_toc_lines("## Setup\n\n## Setup\n"))
Actual:
['- [Setup](#setup)', '- [Setup](#setup)']
Expected:
['- [Setup](#setup)', '- [Setup](#setup-1)']
Impact
When --fix writes a ToC for a Markdown document with repeated section titles, later entries silently point at the wrong section. The check mode can then accept that incorrect ToC because it compares against the same generator.
Validation
- Reproduced by executing the
generate_toc_linesimplementation from the current source in an isolated Python environment. - A focused
unittestasserting unique links for two## Setupheadings fails: 1 test, 1 failure, with the second generated fragment#setupinstead of#setup-1. - This is a source-level / isolated regression test; no full repository test suite or GitHub renderer integration test was run.
Suggested fix
Track collisions of the normalized fragment, assign numeric suffixes matching GitHub heading-anchor behavior, and add regression cases for two and three repeated headings (including collisions between different raw titles that normalize to the same fragment).
Related reports checked
I checked issue/PR searches for readme_toc.py, toc, and duplicate heading/anchor wording. Existing issue #41077 concerns fenced-code parsing, not duplicate heading IDs. This report is intentionally separate.
Source: https://github.com/openai/codex/blob/e742db9f7ba98e63e502b310857d49d047888518/scripts/readme_toc.py
- Dominant language
- Rust
- Stars
- 131k
- Forks
- 20.7k
- Avg merge
- 1m
- Merged PRs (30d)
- 997
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from openai/codex
-
app bug
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
Maintainers usually reply within 1 day
-
app bug
Difficulty 1/5 Under an hour Newbie friendliness 65/100
Maintainers usually reply within 1 day
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day
-
Package archive builder deletes existing file with unsupported suffix under --forcePossibly taken @akhil9tiet claimed this 2 days ago. Openbug
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
openai/codex#57727 · 2 comments ·
Maintainers usually reply within 1 day
-
CLI enhancement TUI
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
Maintainers usually reply within 1 day
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
compiler P4 perf
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
HerringtonDarkholme/hd-lang#1044 ·
Maintainers usually reply within 1 day
-
good first issue help wanted r-docs
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
servo/rust-smallvec#824 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 90/100
akitaonrails/ai-usagebar#552 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100