003. Stable Anchor Contract for Shared Common Documentation¶

Status¶

Accepted

Context¶

The documentation/common guides are being refactored to support shared consumption across Python and Rust projects, and are planned to move into a separate documentation-common repository.

These guides are referenced from templates, project documentation, and downstream repositories using deep links to section anchors.

Generated heading slugs can change when:

heading text changes,
renderer slug rules differ (for example, Sphinx/MyST versus other Markdown toolchains),
renderer implementations evolve.

For shared documentation, anchor stability must be treated similarly to API stability within a major docs tag line (for example, docs-2).

Decision¶

For shared Markdown content that originates from documentation/common:

Every heading must have an explicit anchor immediately before it.
Anchors must use ASCII lowercase kebab-case IDs.
Intra-document and cross-document deep links must target explicit IDs, not renderer-generated heading slugs.
```
<a id="validation-workflow"></a>
## Validation Workflow
```
Anchor IDs are part of the public documentation contract for a docs major line (for example, docs-2).
Removing or renaming an existing anchor ID is a breaking change and requires a new docs major line (for example, docs-3).
Heading text may change without breaking compatibility as long as the anchor ID remains stable.

This contract is primarily a maintainer-facing policy and should be documented in project maintenance/contribution guidance, not emphasized in consumer-facing shared guides.

Alternatives¶

Generated Heading IDs Only¶

Rely on renderer-generated slugs for all headings.
Rejected because heading edits and renderer differences can silently break downstream deep links.

Hybrid Policy (Generated by Default, Explicit for Some Headings)¶

Use generated IDs for most headings and explicit IDs only for selected “stable” sections.
Rejected due to policy ambiguity and review overhead; authors and reviewers must continuously judge which headings are “stable enough.”

Consequences¶

Positive Consequences¶

Anchor stability is explicit and enforceable across docs major lines.
Heading text can evolve without forcing downstream link breakage.
Cross-renderer behavior is deterministic for deep links.

Negative Consequences¶

Authoring overhead increases because every heading requires explicit anchor maintenance.
Reviewers must check anchor changes carefully, especially during refactors.

Neutral Consequences¶

The policy does not require consumer-visible documentation changes; it mainly affects maintainers and contributors who edit shared docs sources.