OpenZeppelin / OpenZeppelin/docs
Docs cleanup: broken anchors, onchain spelling, and link checking
Nobody has claimed this yet.
- Dominant language
- MDX
- Stars
- 6
- Forks
- 23
- Avg merge
- 1d 13h
- Merged PRs (30d)
- 4
Description
Why this exists
Reviewing #233 turned up a batch of problems that are older than that PR. They are present in 2.x and 3.x too, so they were deliberately left out of that review rather than used to block a version bring-up. This issue tracks them.
1. Turn on link checking (do this first)
We already have a link checker: scripts/link-validation.ts. It already reports missing anchors. Two things stop it being useful:
- It only recognises anchors written as
<a id="..."></a>. Our MDX pages write them as<APIItem id="...">and## Heading [#Anchor], so it cannot see most of our anchors. - It only runs inside the three Solidity API-generation workflows. It is not in
lint.yml, so it never runs on a normal pull request.
Fix those two things and most of section 2 finds itself, permanently. Roughly 20 lines of change. Land it in report-only mode first, so it does not start failing builds on day one.
2. Broken anchor links
About 50 internal links in contracts-cairo point at anchors that do not exist. The same links are broken in 3.x, so this is not new — #233, the 4.x bring-up, introduces no new ones and actually fixes two. Three causes:
api/introspection.mdxnames its anchorsSRC5Component-SRC5Impl, while every other API page uses theX-Embeddable-Impls-Yform. Nine links break on this mismatch.- Nine more links point at
*-Embeddable-Mixin-Impl, a form no page actually defines. - Leftover AsciiDoc anchors from the original port:
#customizing_decimals,#ERC721-mint,#ERC20,#IAccessControl-hasRole,#VestingComponent-Vesting-Schedule.
One case is worse than a dead link. DefaultAdminDelayChangeCanceled is referenced 7 times in api/access.mdx but has no entry anywhere in the file, so the event is undocumented. Its description looks like it was merged into the DefaultAdminDelayChangeScheduled entry by mistake.
These pages come from cairo-contracts. Fixing them here works, but the next sync will undo it. Fix them upstream.
3. "on-chain" vs "onchain" — needs a decision, not a pull request
The writing guidelines say "onchain", one word. The docs say "on-chain" nearly everywhere:
| Area | on-chain | onchain |
|---|---|---|
| relayer | 99 | 26 |
| contracts-cairo | 87 | 0 |
| contracts | 75 | 11 |
| impact | 21 | 1 |
| everything else | 115 | 27 |
| total | 397 | 65 |
At that ratio this is the house style, not a slip. Some of it is EIP-4626 text quoted verbatim, which we should not reword at all.
It is also not something recent versions introduced: within contracts-cairo, 3.x and 4.x each contain 29 hyphenated instances, in the same places. Version bring-ups are carrying the existing spelling forward, not adding to it.
So this needs someone who owns the writing guidelines to decide whether docs follow the rule and what the exceptions are. Once that is settled it becomes a find-and-replace.
Unrelated but safe to fix now: 31 places write a Markdown link inside backticks, so the reader sees the raw [text](url) instead of a link. contracts-cairo 18, substrate-runtimes 10, contracts 2, defender 1.
4. Left over from the #233 review
Small things, none worth holding that PR for:
- MetaTransactionV0 appears in the presets table with a deployable class hash but has no page anywhere. See the comment on #233.
- Flash minting and
ERC20WrapperComponentare described in prose with no worked example.4.x/erc20.mdx:121and:129. - "the numeric limit" in
4.x/erc20.mdx:124is never defined, so the reader cannot work out the defaultmax_flash_loan. 4.x/macros/with_components.mdx:30puts six separate diagnostics in one sentence. Make it a list.4.x/erc1155.mdx:6says "StarkNet"; it should be "Starknet". Do not touch the two'StarkNet Message'strings in4.x/api/account.mdx— those are SNIP-12 signature data and changing them breaks verification.4.x/api/erc721.mdx:1305says "off-chain".- ERC-3156 has three names across the docs: flash minting, flash loans, flash lending. The library's own names are split the same way (
ERC20FlashMintComponent,max_flash_loan,IERC3156FlashLender), so this needs acairo-contractsdecision before the docs can settle on one.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with scripts/link-validation.ts and lint.yml to understand the existing checker and workflow entry points. Review the affected contracts-cairo and 4.x pages, including api/introspection.mdx, api/access.mdx, erc20.mdx, macros/with_components.mdx, and erc1155.mdx. Done means report-only link checking runs on normal pull requests, documented links and wording issues are addressed upstream, and the unresolved terminology choices have an explicit decision.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown, typescript
- Domain
- ci-cd, documentation, tooling
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 28/100