Start with the renderer, not a guessed anchor

Markdown is source text that a renderer turns into a document. Different tools can support different extensions, so the same file may not render identically in a repository, a static-site generator, a note app, and a publishing platform. CommonMark defines a core syntax; GitHub Flavored Markdown adds extensions such as tables and task lists. A table of contents and heading-fragment links still need to be checked in the renderer that will publish the document.

This distinction matters because heading text can become a fragment identifier through renderer-specific rules. Punctuation, accents, emoji, repeated headings, and inline formatting can all affect the final identifier. Do not infer that an anchor is correct because its spelling looks reasonable. Render the page, inspect the generated heading target, and click each table-of-contents link in the final output.

Use headings as a document outline

Choose heading levels to reflect the structure of the argument. A page title is usually the top-level heading, with major sections below it and subsections nested under those. Do not select a heading level because it gives a desired font size; presentation belongs in styling. If a section appears to need an H4 directly beneath an H2, ask whether an H3 grouping is missing or whether the hierarchy is accidental.

A skipped level is a useful review signal, not an automatic accessibility verdict. Some documents have valid structures that a simple sequential checker cannot understand. Read the outline from top to bottom and confirm that headings describe the content that follows. A heading such as “More” may be technically present but still tell a reader little about the section.

Benchlight's Markdown QA tool lists heading levels and produces an approximate table of contents. It warns about a jump from one level to a deeper level and repeated generated anchors. Its slugger is intentionally small, so punctuation or Unicode handling can differ from a real renderer. The preview is a way to find candidates; the published document is the evidence.

Keep fragment links tied to real headings

When writing an internal link, test it after rendering. Confirm that the fragment exists, that capitalization and punctuation are handled as expected, and that duplicate heading labels resolve to the intended occurrence. A link copied from another platform may use a different anchor algorithm. If a document moves between renderers, regenerate or verify its table of contents.

For pages that need durable links, consider writing distinctive section headings. A unique heading is easier to link to and easier to scan. Changing a heading can change its generated identifier, so a well-used document may need a redirect, alias, or compatibility anchor depending on the publishing system. Keep the current and prior fragment behavior in mind when editing reference material.

Check link forms and destinations

Markdown supports inline links and reference-style links. A reference link separates the visible use from its destination definition, which can make a long document easier to maintain. Each use still needs a matching definition. A source checker can catch some unresolved references, but only a link checker or rendered inspection can confirm that the destination exists and makes sense.

Read link text without the surrounding sentence. “Click here” or “this page” can be unclear when encountered in a link list or assistive-technology navigation. Describe the destination or action, and make the link label fit the sentence. If the link opens another site, name it when the context would otherwise be surprising. Do not fabricate a source link merely to make a reference list look complete.

Verify tables in context

Tables are useful for compact comparisons with a small number of columns. They can become difficult on narrow screens or when cells contain long paragraphs, nested lists, or complex content. If a table is wide, consider whether the reader's task would be clearer as a sequence of headings or a short list. If the renderer supports tables as an extension, verify that extension is enabled.

Review the header row and alignment markers in the actual rendered table. Make sure each column has a clear label and that repeated values do not make row relationships ambiguous. A plain-text preview cannot determine whether the table has horizontal overflow or whether its semantics are announced as intended. Test the page at its real content width.

Separate source checks from rendered checks

An authoring linter can find patterns such as skipped headings, malformed references, and repeated source labels. It cannot prove that the page has good hierarchy, that every link is useful, or that the final HTML works for keyboard and assistive-technology users. A renderer may add heading IDs, wrap elements, or apply plugins that the source checker cannot see.

Use two passes. First inspect the source for structure and unresolved references. Then inspect the generated page for heading outline, target IDs, link destinations, table layout, and focus behavior. If the Markdown is rendered by more than one system, keep a small fixture with the syntax features the document relies on and verify each output.

Follow a repeated heading and an unresolved reference

Enter this invented document into Markdown QA:

## Setup
Install the example package.

## Setup
Read the [build instructions][build].

The preview assigns setup to the first heading and setup-1 to the second. It also flags the repeated generated anchor and the unresolved build reference. Those are separate findings. The repeated heading is not automatically an invalid HTML identifier: the tool has added a suffix. The problem for an author is ambiguity about which Setup a reader needs, along with dependence on the renderer's duplicate-heading policy.

Rename the second heading to Build instructions and add a matching reference definition with a real destination appropriate to the document. Re-run the source check, then render the document where readers will use it. Inspect the actual heading IDs and click the resulting fragment links. A different renderer may omit IDs entirely or generate another spelling. CommonMark defines heading syntax, but does not require this particular automatic slug algorithm.

Do not treat the QA preview as a complete CommonMark parser. For example, the current scanner reads physical lines and can interpret a heading-looking line inside a fenced code example as a heading. It also checks only a subset of reference-link forms; the absence of a warning does not certify every shortcut reference. Run the intended renderer when either case matters. The fixture above avoids a fence around its headings when pasted into the tool; the fence on this article only presents the source as a readable example.

For durable documentation, make the destination labels distinct enough that the outline still makes sense in a link list. Record existing public fragments before changing headings that others may already cite. This is a practical maintenance task: resolve the missing destination, disambiguate the heading, and verify the published target. A source-only table of contents cannot complete the last step.