Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Docs cleanup: broken anchors, onchain spelling, and link checking

Aperta
  • Qualcosa non va?
#236 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
28/100
Tipo di issue
Documentazione
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
markdown, typescript
Ambito
ci-cd, documentation, tooling

Direzione di ricerca

Inizia da scripts/link-validation.ts e lint.yml per comprendere i punti di ingresso esistenti del checker e del workflow. Esamina le pagine interessate di contracts-cairo e 4.x, incluse api/introspection.mdx, api/access.mdx, erc20.mdx, macros/with_components.mdx ed erc1155.mdx. Il lavoro è completato quando il controllo dei link in modalità report-only viene eseguito sulle normali pull request, i link documentati e i problemi di formulazione sono stati risolti upstream ed è stata presa una decisione esplicita sulle scelte terminologiche irrisolte.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation

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.mdx names its anchors SRC5Component-SRC5Impl, while every other API page uses the X-Embeddable-Impls-Y form. 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 ERC20WrapperComponent are described in prose with no worked example. 4.x/erc20.mdx:121 and :129.
  • "the numeric limit" in 4.x/erc20.mdx:124 is never defined, so the reader cannot work out the default max_flash_loan.
  • 4.x/macros/with_components.mdx:30 puts six separate diagnostics in one sentence. Make it a list.
  • 4.x/erc1155.mdx:6 says "StarkNet"; it should be "Starknet". Do not touch the two 'StarkNet Message' strings in 4.x/api/account.mdx — those are SNIP-12 signature data and changing them breaks verification.
  • 4.x/api/erc721.mdx:1305 says "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 a cairo-contracts decision before the docs can settle on one.
Lingua principale
MDX
Stelle
6
Fork
23
Merge medio
39m
PR unite (30g)
1

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di OpenZeppelin/docs

Tutte le issue di OpenZeppelin/docs

Issue simili

Altre issue su DevOps

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.