Bulk URL and text substitution pass over the docs: it applies every rule in a renames table (by default renames-table.json) to the pages under pages/, the site pages under src/pages/ (*.md, *.mdx, *.tsx) and README.md.
/docs/topics/<old slug> link must point at /docs/topics/<parent slug>#<anchor>: write a table for the batch and pass it with --table.check-topic-links.py or verify-docs.py instead.python3 scripts/apply-renames.py --dry-run python3 scripts/apply-renames.py python3 scripts/apply-renames.py --table /path/to/fold-renames.json --dry-run
Without --dry-run it edits files in place, so review the dry-run list first and the diff afterwards.
| Option | Argument | Default | Meaning |
|---|---|---|---|
--table | file | renames-table.json beside the script | The rules file to apply. |
--dry-run | off | Report which files would change and how many substitutions each gets; write nothing. | |
--docs-dir | directory | parent of the scripts/ folder | The docs checkout to rewrite. |
load_rules). Each rule has pattern, replacement and is_regex; regex patterns are compiled, others are literal. The optional comment is ignored at run time.*.md under pages/, every *.md, *.mdx and *.tsx under src/pages/ (the about, downloads, security, home and 404 pages link /docs/topics/...), and README.md (when it exists), sorted by path (target_files).pages/release-notes/ whose name does not start with 10. (older release notes are historical).process_file), masks fenced code blocks and inline code spans (mask_code) so rules cannot touch code. The one exception is an inline-code span that is the whole label of a Markdown link ([`Name`](url)); those are left unmasked so the label is rewritten along with the URL.apply_rules_to_text), restores the masked code, and writes the file back only if the text changed (never with --dry-run).A fold rule pair keeps an existing anchor and adds one to a bare link, with a lookahead so a longer slug that starts with the old one is not touched:
[ {"comment": "fold OldSlug, anchored", "pattern": "/docs/topics/OldSlug#", "replacement": "/docs/topics/Parent#", "is_regex": true}, {"comment": "fold OldSlug, bare", "pattern": "/docs/topics/OldSlug(?![\\w#-])", "replacement": "/docs/topics/Parent#old-slug", "is_regex": true} ]
Stdout only: Loaded N substitution rules from ..., then the SUBSTITUTION SUMMARY block (marked (dry run, nothing written) with --dry-run). Changed files are rewritten in place; nothing else is written.
| Code | Meaning |
|---|---|
| 0 | Completed, whether or not any file changed. |
| 1 | Python traceback: the table is malformed, or a rule lacks a required key. |
| 2 | The table file or the pages/ directory is missing. |
A file that is not valid UTF-8 prints a warning on stderr and is skipped.
~~~ fence is rewritten.check-topic-links.py reports them.renumber-topics.py does.check-topic-links.py, verify-docs.py, renumber-topics.py