How do you translate Markdown documentation and keep a generated table of contents accurate when headings change language? This DocToc CLI localization guide explains the doctoc tool maintained by the thlorenz project, heading anchors, GitHub and other renderer modes, generated-region markers, update-only behavior, dry-run checks, Unicode titles and safe continuous integration. It helps translators, maintainers, technical editors and worldwide documentation teams keep readers on the correct section of a long guide.
DocToc generates and updates Markdown tables of contents based on document headings. It does not translate the document, understand whether a section’s claims are true or guarantee that every website will interpret a fragment link the same way. A table of contents can look perfect in the Markdown source and still direct readers to incorrect destinations after a heading translation or platform migration.
Translate the human-facing heading and navigation text, but preserve the command interface and the boundaries of generated content. Choose the anchor rules for the actual publishing platform, protect code and manually maintained cross-references, and test the finished links in their rendered environment. A professional multilingual table of contents does more than mirror headings: it allows people using different languages, scripts and devices to navigate safely to the information they came to find.
Quick reference: safe table-of-contents localization
- This guide covers the Node.js thlorenz/doctoc CLI, not similarly named utilities.
- Treat headings as the source of truth and generated navigation as derived content.
- Preserve literal CLI flags and DocToc region markers; translate visible labels naturally.
- Choose renderer-specific anchors and verify links on the actual hosting platform.
- Use dry-run checks in CI and update-only behavior where that matches editorial policy.
- Test CJK, accents, RTL headings, duplicate labels and high-value external deep links.
A practical start-to-finish sequence
- Identify source files, translated editions, source revisions and the intended renderer.
- Establish a clear table-of-contents policy and protected marker format.
- Translate headings and check the logical outline before generation.
- Generate on a representative file set, review the diff and keep source changes traceable.
- Run CI consistency checks and test each rendered anchor, including Unicode cases.
- Obtain linguistic and technical approvals for navigation and consequential sections.
Quick reference: the reader’s navigation contract
A table of contents is an agreement between the page’s visible headings and its link destinations. Each entry should describe a useful section in the reader’s language, appear in a sensible order and lead to the appropriate heading. DocToc helps maintain the generated links, but the author and translator remain responsible for meaningful wording, a coherent outline and a safe release process.
For a guide with English, German and Arabic editions, each edition may have different heading lengths, punctuation and generated fragments. The page paths may differ too. The translator should not paste the English table of contents into all three editions and call the work complete. Nor should they simply run a generator and assume that every platform uses the same anchor algorithm.
Start by choosing the publication target, identifying its heading-fragment rules and making a small sample with non-Latin characters and repeated headings. Protect all manually maintained deep links and test both the table of contents and in-body references. A successful generated list is a useful intermediate result, not a final acceptance certificate.
Identify the specific DocToc project
The name DocToc appears in more than one software ecosystem. This guide concerns the JavaScript/Node.js doctoc project associated with thlorenz and its documented Markdown table-of-contents CLI. It is important to identify the repository and installed package because another tool with a similar name may expose different flags, insertion markers or failure behavior.
A team might encounter an npm command in a README and a Python package of the same name in a separate environment. Copying options between them can produce confusing errors, while assuming their outputs are interchangeable can damage generated regions. Product identity is therefore part of accurate technical localization, not an incidental implementation detail.
Record the exact package source, installed version and tool invocation in the translation repository. When an instruction quotes a flag, verify it against the selected project’s current help or documentation. This simple habit prevents readers from following a beautifully translated guide that points to the wrong executable.
What DocToc changes in a file
DocToc scans Markdown headings and generates a list of links that usually lives inside a marked region. Its output reflects headings and chosen renderer rules. The generated lines are navigation artifacts, not independent source prose. Editing their text manually without changing the corresponding headings is likely to create maintenance drift when the generator runs again.
Imagine an English guide whose first heading is ‘Prepare the environment.’ A French translator updates the heading but leaves the old table-of-contents text. A later generation should rebuild that entry in French, subject to the selected anchor rules. If the translator directly edits only the generated list, the next run may overwrite that change because the source heading still carries the old wording.
Treat headings as the authoritative content and the table of contents as derived output. Where a custom entry label is required, choose an explicit project-supported approach rather than patching the generated region unpredictably. Review the generated list with the heading outline after every material translation change.
Install and run a reproducible toolchain
The project documentation provides npm-based installation and doctoc command examples. A team can use a local project dependency or another approved installation method. Reproducibility matters: a collaborator and CI runner should use compatible versions and operate on the same files with the same options. A changing global environment can produce unexplained differences in generated Markdown.
For a simple document, doctoc README.md demonstrates the central operation. The command should be treated as executable syntax, not translated prose. It may change the file by inserting or updating the generated contents. A translator who expected only a diagnostic should be warned before running it in a working tree with uncommitted edits.
Use version control before broad file operations, and keep the dependency lockfile where the repository convention supports it. A local sample can establish expected behavior and reveal whether headings, special characters or insertion markers are handled as the team assumes.
Command flags versus explanation
Flags such as --github, --gitlab, --dryrun, --update-only, --minlevel and --maxlevel are technical identifiers. The project documents how they influence generation. Translate the surrounding explanation, but preserve the literal option names. A locale-specific tutorial can explain what a flag means in natural language without pretending that the program accepts translated flag names.
For example, a Spanish guide might say to run doctoc README.md --github for the selected rendering convention. The word GitHub remains the platform name, and --github remains the exact flag. Translating the surrounding instruction is appropriate; replacing the option with a Spanish adjective would produce an incorrect command.
Copy and test commands from the final page. Technical typography should remain plain enough for terminals: avoid curly replacement quotes, long dashes and invisible directional marks inside options. A copy button should preserve the command’s logical character order even when it appears within Arabic or Hebrew prose.
Choose the correct renderer mode
Markdown platforms do not necessarily agree on fragment IDs for headings. DocToc documents mode flags for several targets, including GitHub, GitLab, Bitbucket, Node.js and Ghost. The right mode depends on where the document is actually rendered, not on which website an editor prefers. A link that works on one platform may fail on another.
A README maintained in a Git repository could be displayed on GitHub, while the same source is reused in a documentation website with a different Markdown renderer. If the team generates links using one platform’s conventions and publishes to the other, punctuation or repeated heading behavior may diverge. The issue becomes more visible with diacritics, non-Latin scripts and heading text containing inline code.
Choose a primary publishing target or maintain separately tested outputs for each. Where multiple destinations matter, document the trade-off and consider whether stable explicit anchors are possible in the actual renderer. Never assert universal compatibility from a single successful local preview.
Understand how heading text becomes a fragment
A fragment identifies a location in an HTML document. Many Markdown platforms derive a heading ID by transforming its visible text, often normalizing case or punctuation and dealing with duplicate headings. The exact algorithm is platform-specific. Translation may change the generated fragment even when heading level and Markdown formatting remain correct.
Suppose an English page links to #install-the-agent. After translating the heading, the generated fragment may be different. A regenerated table of contents can reflect the new language, but an email or support ticket linking to the old English fragment will not automatically update. Manually written links in other files may also become stale.
Keep an inventory of high-value deep links, especially those used in troubleshooting, course materials and published release notes. Test them in the live renderer after translating headings. When stability matters, adopt intentional explicit IDs or redirects where the publishing platform supports them.
Repeated headings and disambiguation
Long documentation frequently repeats simple headings such as ‘Examples,’ ‘Notes’ and ‘Troubleshooting.’ Renderers may add suffixes to distinguish duplicate IDs. A translator can accidentally introduce new duplicates by translating several distinct source headings into the same target phrase. A generated table of contents must be checked for where each entry actually goes.
Imagine three English headings: ‘Quick examples,’ ‘Sample commands’ and ‘Worked examples.’ They might all become the same short translated heading. The resulting fragments may receive disambiguators, and links might depend on section order. If editors later move one section, generated IDs or suffixes can change again and break references.
Prefer headings that communicate each section’s distinct purpose. Run DocToc after structural edits and test duplicate destinations. A tool can produce a list of links, but it cannot decide whether a repeated heading is useful to a reader or an accidental consequence of over-condensed translation.
Unicode headings and normalization
Multilingual headings can contain accents, combining marks, Chinese characters, Arabic letters and other Unicode sequences. Some visually equivalent strings have different underlying code points. Fragment-generation rules may handle them differently across platforms. An editor who only compares screenshots can miss a mismatch between generated URLs and rendered IDs.
A French title containing a composed accented letter may look the same as one with a combining accent; an Arabic heading may include punctuation whose visual position differs from storage order. Depending on the renderer, fragments may contain encoded characters or remove certain punctuation. This variability makes byte-level assumptions risky.
Test Unicode headings in the actual destination site, including copied browser URLs, keyboard navigation and links shared in messaging applications. Use a consistent source encoding and normalization policy without stripping legitimate characters. Most importantly, verify whether the generated link reaches the target rather than trying to guess the slug from its appearance.
CJK text without spaces
Chinese, Japanese and Korean headings may not separate words with ASCII spaces. A generic English-oriented slugging intuition can therefore fail. The renderer may preserve many Unicode characters, encode them in a URL or apply its own normalization. Translators should not insert arbitrary spaces purely to satisfy a guessed fragment algorithm.
A Japanese page might include a short heading with Kanji and kana. Its displayed wording should follow Japanese editorial conventions. If the documentation platform generates an encoded fragment, that is not inherently an error; what matters is whether the browser and table of contents navigate correctly. Replacing a meaningful heading with romanization solely to simplify an anchor could harm search and comprehension.
Include a CJK heading in the test fixture and click its generated link on desktop and mobile. Copy the resulting URL into a fresh browser tab. If the platform behaves differently from the generator, solve the compatibility problem in the publishing workflow rather than forcing unnatural language choices.
Right-to-left headings and links
Arabic and Hebrew headings introduce another complication: the visible order of punctuation and link characters can differ from the stored sequence. A Markdown table of contents is text containing a destination fragment, and a browser may display that fragment differently from its underlying value. The link must remain logically correct even when the page reads right to left.
Suppose an Arabic heading includes a Latin software name and a version number. A generated anchor may combine scripts and punctuation. The table-of-contents label should read naturally in Arabic, but the destination should not be manually reversed to match the visual display. That would create a different URL rather than fixing bidirectional rendering.
Test navigation from the rendered right-to-left page and copied links in the browser address bar. Inspect how lists, inline code and parentheses display. Where possible, use correct document language and direction semantics in the site rather than injecting invisible directional controls into every Markdown link.
Generated-region markers matter
DocToc uses comments to mark the generated table-of-contents region. The project documents compact markers such as <!-- START doctoc --> and <!-- END doctoc -->, as well as the generated forms it can maintain. Those comments are processing boundaries; they should not be translated into ordinary prose or removed because they look like leftover editorial notes.
An editor may see an English comment telling humans not to edit a generated section and decide to translate or delete the entire comment group. If the marker no longer matches what the tool expects, a subsequent run might insert a second table of contents or fail to update the intended region. The result creates confusing navigation and noisy diffs.
Treat delimiters as protected source syntax. Translate a visible heading such as ‘Contents’ through supported options or editorial structure, but preserve recognized marker strings unless the tool explicitly supports a different format. Review the generated region in version control to confirm that only the intended lines changed.
Choose where the contents list belongs
A generated table of contents usually appears near the top of a long Markdown page, but project documentation shows that insertion markers can designate another location. The ideal position depends on how readers use the page: a long introduction may warrant a contents list before detailed procedures, while a short README may not need one at all.
A tutorial might begin with a two-paragraph overview, a prerequisite warning and then the contents. That may be more helpful than placing a long list before the reader understands what the document covers. Conversely, hiding navigation beneath many promotional paragraphs can frustrate someone returning for one specific instruction. Translation may increase the length of those sections and change the practical balance.
Set the insertion point intentionally and keep the marker pair together. Test the final reading order with keyboard navigation and on a narrow screen. A table of contents should shorten the reader’s route to an answer, not become a barrier occupying the entire first screen.
Custom visible TOC titles
The project documents options for changing the generated table-of-contents title, including a custom title and a no-title mode. Those options affect reader-visible text while leaving the command option names exact. This is a useful distinction: a localized ‘Table of contents’ heading is a legitimate translation, but a localized CLI flag is not.
A Spanish README could use a short, familiar title for the generated list while preserving the project’s command syntax. Another team might deliberately omit a title because the surrounding page already labels its navigation. Either choice is editorial; the generator should not force one English phrase into every locale.
Test whether changing a title is preserved through repeated runs and whether it creates a duplicate heading or unintended anchor. Maintain the selected title in a reproducible command or documented source convention rather than relying on someone to fix the generated output manually after each build.
Heading minimum and maximum levels
DocToc documents heading-depth controls, including --minlevel and --maxlevel, for selecting which Markdown headings appear. These settings affect the density of navigation. Different documents have different needs: a long technical manual may benefit from several levels, while a short quick-start may become cluttered if every minor note is listed.
A reference page might have a top-level title, several feature sections and many low-level examples. Showing every example heading can produce an unwieldy table of contents. Excluding too many levels can make it hard to reach the exact answer. The best threshold should correspond to the document’s conceptual structure rather than merely shortening the generated list.
Before changing levels for a localized edition, compare the source and target heading hierarchy. If a translation has changed section levels unexpectedly, fix the outline rather than hiding the problem with a different maximum depth. The settings should filter a sound structure, not conceal a broken one.
Dry-run checks in continuous integration
The documented --dryrun option allows checking whether a table of contents needs updating without writing the changes. This is useful in CI because a failure can identify files whose generated navigation is out of date. The project’s README describes an exit status signaling an outdated table of contents in dry-run mode.
A contributor translates a heading and forgets to regenerate the navigation block. A check in CI can detect that the generated list does not match the headings. The contributor can then run the writer locally, review the diff and commit the updated result. This makes a repeatable task easy to enforce without having CI silently rewrite submitted source.
Configure the check for the intended file set and make its error output understandable. A failing exit code should lead the editor to a specific action. Do not misclassify every failure as bad translation: an invalid option or execution-environment problem is different from a stale table of contents.
Update only when a TOC already exists
DocToc offers an --update-only or -u option to update existing generated tables of contents without inserting new ones into every Markdown file. This can be useful in large repositories where some documents intentionally omit navigation, or in staged-file workflows that should touch only the documents already using DocToc.
Imagine a repository with short code examples, legal notices, long manuals and changelogs. Running an unbounded generator across the entire tree could insert unnecessary contents lists into tiny files. Update-only behavior gives the team a way to maintain existing navigation while respecting editorial decisions about where it belongs.
Test this mode on a mixed sample of files with and without markers. Document the policy for introducing a new table of contents, because update-only checks will not create one automatically. This separates the editorial decision to add navigation from the mechanical obligation to keep it current.
Choose file and folder scope carefully
The DocToc CLI can process individual files and folders according to its documented behavior. Large repositories may contain vendored dependencies, generated artifacts, example Markdown or translations that are not supposed to be edited by the same command. A broad invocation can create thousands of noisy changes and make a small localization correction difficult to review.
For instance, a monorepo may have docs/en, docs/fr, archived versions and a generated website output directory. Running a command from the repository root without a file-selection policy could touch old pages or generated copies. A safer workflow targets the active source directories and intentionally excludes archival or read-only material.
Before a large run, inspect the selected paths, commit or back up the working tree and perform a narrow trial. Review the resulting diff. Keeping the scope focused is not merely a performance optimization; it prevents unintentional edits to canonical documents and protected release artifacts.
Update staged files with care
Teams sometimes integrate DocToc into a Git hook or a staged-file workflow. This can keep navigation synchronized with heading changes, but it also changes the moment at which files are rewritten. A translator should know whether saving, staging or committing will regenerate a table of contents, because otherwise a diff may appear unexpectedly during review.
Consider a contributor who updates one French heading and stages the file. The hook regenerates navigation and modifies the file after staging. The contributor must check whether the generated change was also staged and whether the commit includes both pieces. A process that quietly changes files but fails to include them in the reviewed patch creates avoidable inconsistencies.
Prefer explicit documentation about hooks, their write behavior and how to inspect changes. A CI check remains useful even when hooks exist, because contributors can bypass hooks or use different environments. The two layers should complement each other rather than conceal what has changed.
Why `–stdout` is different
The project documents an option to print generated output to standard output for an individual file, with scope limitations. This can be useful for inspecting output without relying on a broad rewrite. Do not assume that it behaves identically for a folder or multiple files; consult the specific documentation and installed help before building automation around it.
A reviewer might want to compare the proposed contents list with the source headings during a translation audit. A single-file stdout workflow can make that comparison easier to capture. For an entire documentation tree, a dry-run check and version-controlled diffs may be more appropriate than trying to assemble unrelated outputs on one stream.
Choose the mode that makes the intended effect explicit. An editor seeking a preview should not accidentally overwrite sources, and an automated writer should not merely print generated text that never reaches the published Markdown file.
Minimum document length and editorial usefulness
The project documents a minimum-line option for controlling when a table of contents is generated. This can help avoid inserting a large navigation block into documents too short to benefit from one. Yet line count is only a rough proxy for reader need. A brief procedure with many headings can still deserve navigation, and a long narrative with only two sections may not.
A Markdown page containing numerous images may have few source lines while being visually long. Another file may have hundreds of short wrapped lines but little conceptual depth. The minimum-line setting should therefore be treated as a maintenance heuristic rather than a universal usability standard.
Review the impact on representative page types and languages, since translated text may wrap differently in source files. A rule that switches navigation on and off when wording length changes can create unnecessary instability. Prefer a clear repository policy for pages that should carry a table of contents.
Generated content is not a translation memory
A contents list reflects current headings, but it does not preserve the editorial reasoning behind translated terminology. If translators produce inconsistent headings, regenerating the list faithfully reproduces that inconsistency. A terminology glossary and information architecture still matter, especially across versioned manuals and different contributors.
Suppose one team translates ‘Configuration’ using a short technical term while another uses a more explanatory phrase. Each generated table of contents might be internally correct, yet readers moving between related guides have to relearn the navigation vocabulary. The problem is linguistic consistency, not generator failure.
Maintain a shared glossary for recurrent section concepts such as installation, permissions, troubleshooting and rollback. Review heading outlines across related pages, then regenerate navigation. The generator should carry a good editorial decision into output, not replace the decision.
Avoid cannibalizing related documentation pages
A documentation site benefits from pages that solve different problems clearly. One page may explain DocToc and heading anchors, another may explain general Markdown linting, and another may verify the external links inside a generated table of contents. These purposes can coexist, but repeating the same generic introduction across pages does not help readers.
A person searching for a broken #fragment after translating a heading needs a concrete anchor-compatibility explanation. Someone searching for a stale table of contents in CI needs dry-run behavior and a remedy. Someone searching for a website’s unavailable target needs link checking. The article title and opening should reflect those distinct intents.
Use naturally phrased headings and helpful examples rather than stuffing product names into every paragraph. Cross-link adjacent topics when they provide the next troubleshooting step. Search discoverability follows relevance and clear structure more reliably than unsupported claims about which keyword has the highest traffic.
Unicode URL encoding and copied fragments
A browser may display non-ASCII fragments using percent-encoded characters. Encoding is not itself a mistake, but manual editing of percent signs or partial sequences can change the target. A translator should not decode and rewrite a URL solely to make it look visually familiar. The right question is whether clicking it reaches the intended heading.
For example, a Chinese heading may generate a fragment that appears encoded when copied from the address bar. The link can still work correctly. A hand-edited version that drops encoded bytes could fail. Mixed English and Arabic headings can introduce additional confusion when visual order changes but the stored sequence remains the same.
Check generated links through the normal click path and with copy-and-paste into a new tab. Test browsers and platforms representative of the audience. When a fragment genuinely fails, capture the source heading, generated destination and actual rendered heading ID as evidence.
Manual links outside the generated TOC
DocToc updates its designated table-of-contents region; it is not a general repository-wide link migration service. Hand-written links in the body, another chapter, an external support page or a training document may still point to old heading fragments. This limitation is particularly important during translation, when many heading names change at once.
A support team might have a troubleshooting template linking directly to the ‘Reset credentials’ section of a manual. After translation, the generated table of contents on the new page works, but the template’s older fragment fails. Regenerating the table again will not repair the external document.
Maintain a deep-link audit for high-value references and run a suitable link or anchor check after generation. Check semantic equivalence too: a link can land on a valid heading that now describes a different topic after a structural rewrite.
Link reachability is not link correctness
Even when a URL loads and its fragment exists, the destination may not contain the intended instruction. A table-of-contents tool cannot assess factual meaning. An automated link checker may confirm technical reachability but still miss a mislabeled destination, outdated version or unsafe advice. Navigation quality needs a semantic review layer.
Imagine a translated TOC entry labeled ‘Backup recovery’ that lands on ‘Delete backups.’ The link works, but the label is dangerous. A technically valid generated anchor can result from a heading that was translated inaccurately. Conversely, a correct heading may lead to a valid section whose body is outdated.
Ask a target-language reviewer to follow representative entries and summarize the instruction they find. Compare high-impact sections with the authoritative source. This simple exercise catches semantic navigation errors that neither DocToc nor a basic HTTP checker is designed to detect.
Versioned documentation and old anchors
Documentation libraries often maintain several product versions. A heading change can affect historical links, even when the newest translation is accurate. Preserve or deliberately migrate links used by archived manuals, old release notes and support tickets. Do not assume that updating the current branch means every published version should receive the same regenerated contents list.
An older release may document a flag that no longer exists. Its translated heading and anchor might be intentionally different from the current manual. A script that rewrites both versions based on the latest vocabulary can make historical instructions misleading. The source revision, target language and product version should identify each page unambiguously.
Generate navigation within the correct versioned source tree and test its published URL. When a redirect or stable anchor is needed for a migrated section, implement it through the site’s routing policy, not by pretending the generator can preserve historical link semantics automatically.
Accessibility and mobile navigation
A long generated list is only useful when people can navigate it. On a phone, dozens of links may occupy more screen space than the introduction. Screen-reader users need descriptive entries, logical heading levels and a way to reach the main content. The table of contents is one layer in that experience, while the website template supplies broader navigation landmarks.
A heading called ‘More’ produces a vague entry even if DocToc links it perfectly. A heading that begins with an unpronounceable technical abbreviation can be difficult in a different language. Multiple identical labels can also frustrate readers using a links list. Improving the underlying headings benefits both the table of contents and the document itself.
Inspect the rendered page at mobile widths and through keyboard navigation. Test whether links move focus and scroll to the intended section, and whether the target remains visible below any sticky header. Verify that language direction and heading semantics are appropriate for the intended audience.
Review command security and repository scope
Documentation tooling should operate on trusted inputs within an approved repository process. A localization contributor may not have permission to edit every source file, and a broad command can modify documents they did not intend to touch. Limit write scope, review diffs and avoid using elevated permissions merely to make a generator succeed.
A CI job that automatically commits generated navigation into a protected branch might bypass normal review. It may also conflict with another job or run with more repository privileges than necessary. A safer approach is often to check the output and require the contributor to commit a reviewed change, subject to the team’s security model.
Do not accept file-modifying command snippets from arbitrary documentation without understanding their scope. The goal is deterministic navigation maintenance, not hidden changes to unrelated content. A short command can have a wide impact when it runs recursively over an entire repository.
Troubleshoot unexpected duplicated contents
If a page gains a second table of contents, first inspect the generated-region markers and source history. A marker may have been translated, removed or altered. Another possibility is that a copied section already contains generated content not recognized by the current tool. Determine the precise cause before deleting material so that the defect does not recur.
A team might manually paste a contents list into a translated copy and then run DocToc. The program may generate its managed list while the handmade one remains. Both can contain working links yet confuse readers. Simply deleting one list is not sufficient unless the source has a clearly defined region to maintain going forward.
Keep exactly one intentional contents policy per file, preserve recognized markers and test a second run. Idempotence is a useful expectation: after updating a correct generated list, a subsequent run should not produce another unrelated change under the same configuration.
Troubleshoot wrong or broken anchor links
Begin by identifying the publishing renderer, the DocToc mode, the original heading text and the actual ID in the rendered HTML. Do not guess at what the slug should be. Compare repeated headings and Unicode punctuation, and check whether the destination page uses a custom heading component or explicit anchor policy.
If a GitHub README link works but the same Markdown fails inside a documentation portal, the sites may use different heading-ID rules. If an Arabic link looks reversed, distinguish visual bidi presentation from actual URL characters. If a heading was renamed, verify whether only the generated list changed or whether manual references also require migration.
Fix the configuration or the source structure, then regenerate and click the result. Add a regression test for the specific heading pattern, especially when it involves diacritics, duplicate names or non-Latin scripts. A repaired link should stay repaired when future translations modify nearby headings.
A complete multilingual example
Imagine a software project with README.md, CONTRIBUTING.md and a documentation tree in English, French and Japanese. The team wants consistent tables of contents without overwriting unrelated pages. First identify the active source files, target renderers, protected markers, current deep links and heading style conventions for each language. Save a clean baseline in version control.
Next translate the headings and prose, keeping commands and source syntax intact. Run DocToc with the selected renderer mode on a small sample and inspect the diffs. Choose whether to update only existing tables or generate new ones according to the repository’s editorial policy. Then run a dry-run CI check so future heading changes cannot leave navigation stale.
Finally render the pages on their actual host, click translated entries, inspect duplicate headings, test Japanese Unicode fragments and review accessibility on mobile. Check manual links outside the generated blocks and record the tool version and configuration. A complete release allows a reader to find the intended section without guessing how a heading was slugged.
Editorial sign-off: what to measure
A good release process separates mechanical synchronization from meaningful reader outcomes. The generated block should match the current headings, but the headings should also be accurate, distinct, appropriately nested and relevant to user tasks. Links should reach the intended section across real publishing destinations, and translated code examples should remain executable.
Assign technical verification to a maintainer familiar with the renderer and repository. Ask a native-language editor to judge headings, labels and information hierarchy. Have a domain expert confirm that critical sections such as credential rotation or data recovery are accurately named. These roles can overlap, but the questions should not be collapsed into a single ‘looks fine’ approval.
Record evidence rather than just a pass badge: command version, checked file set, output diff, actual link results and any approved exceptions. That record turns a routine table-of-contents update into trustworthy multilingual documentation maintenance.
Frequently asked questions
Does DocToc translate headings?
No. It reads Markdown headings and generates navigation entries and links. The translator or editor must supply correct, natural headings, while DocToc can help keep the generated contents synchronized with them.
Why did my table-of-contents link break after translation?
Heading translations can change generated fragments, and different platforms use different rules. Regenerate with the right renderer mode, then inspect the actual heading ID and test in the published environment.
Should I translate the START and END doctoc comments?
No. They are recognized processing markers, not reader-facing prose. Changing their literal form can stop the tool from updating the intended region or cause duplicate lists.
What does `–dryrun` help with?
It can detect whether generated contents need updating without rewriting files, making it useful as a CI consistency check. Interpret failures using the installed tool’s documented exit codes.
What is `–update-only` for?
It maintains existing tables of contents without inserting new ones into documents that do not already have managed navigation. It helps preserve editorial decisions in large repositories.
Will the same generated links work on every Markdown website?
Not necessarily. Heading-fragment conventions vary among platforms. Choose the target renderer mode, test Unicode and duplicate headings, and verify on the final host.
Why are my links percent-encoded?
Non-ASCII characters may be encoded in URLs. Encoding alone is not a failure. Confirm that the link reaches the intended heading and do not manually alter encoded bytes without understanding the destination.
Can I rely on a generator for semantic navigation quality?
No. It can match links to headings but cannot decide whether a translated heading accurately names the section, whether the section is current or whether the linked instruction is safe.
Final publication checklist
- All translated headings accurately describe their sections and preserve the intended hierarchy.
- The package and CLI flags match the specific maintained DocToc project.
- Generated-region markers remain intact and no duplicate contents list appears.
- The output is reproducible from a documented version and command.
- The renderer mode matches the actual publication destination.
- CJK, accented and right-to-left headings are tested in the published page.
- Manual deep links and external references are reviewed separately from the generated block.
- The document remains usable on mobile and through keyboard or assistive navigation.
Primary sources and further reading
For exact CLI syntax and current behavior, consult the thlorenz/doctoc repository and README, including its documented renderer flags, dry-run mode, update-only option and generated-region markers. For neighboring quality-assurance tasks, read eduKateSG’s lychee link checking guide and markdownlint-cli2 guide. Check option availability against your installed release.