Problem
When multiple MDX files are imported into the same page (e.g. code_samples/tdf/encrypt_options.mdx imported into docs/sdks/tdf.mdx), headers from both files generate anchor IDs on the same rendered page. If two headers produce the same slug, TOC links jump to the wrong section.
This just bit us — ### Assertions in encrypt_options.mdx collided with ## Assertions in tdf.mdx, along with ### Data Attributes and ### Metadata.
Proposed solution
Add a script (e.g. src/openapi/check-duplicate-anchors.ts or similar) that:
- Parses each docs MDX file for
import statements referencing code_samples/
- Collects all markdown headers from the doc file and its imports
- Slugifies them the same way Docusaurus does
- Fails if any duplicates are found
Run it in CI alongside check-vendored-yaml.
Context
Fixed in #268 by renaming encrypt option headers to use SDK option names (WithAssertions, WithDataAttributes, WithMetadata). Convention documented in AGENTS.md — but a CI check would catch future regressions.
Problem
When multiple MDX files are imported into the same page (e.g.
code_samples/tdf/encrypt_options.mdximported intodocs/sdks/tdf.mdx), headers from both files generate anchor IDs on the same rendered page. If two headers produce the same slug, TOC links jump to the wrong section.This just bit us —
### Assertionsin encrypt_options.mdx collided with## Assertionsin tdf.mdx, along with### Data Attributesand### Metadata.Proposed solution
Add a script (e.g.
src/openapi/check-duplicate-anchors.tsor similar) that:importstatements referencingcode_samples/Run it in CI alongside
check-vendored-yaml.Context
Fixed in #268 by renaming encrypt option headers to use SDK option names (
WithAssertions,WithDataAttributes,WithMetadata). Convention documented in AGENTS.md — but a CI check would catch future regressions.