docs: prose audit — tradenames + code-fence types#21451
Merged
Conversation
…nce types
Applies §7.1 (Tradenames), §7.3 (Style), §7.4 (Terminology) from the
erigon-documents check routine to `docs/site/docs/`. No content changes —
only writing-quality fixes.
Three rule categories:
- **Tradenames (§7.1)** — `docker`/`linux`/`ethereum`/`caplin`/etc. capitalized
in prose where they were mid-sentence lowercase. Mid-identifier occurrences
(e.g. `go-ethereum`, `linux/amd64`, `docker-compose`) are preserved.
- **Terminology (§7.4)** — two `execution client` → `execution layer client`
on landing pages.
- **Style (§7.3)** —
- 169 Title-Case headings → sentence-case. Proper nouns, acronyms, and
mixed-case branding (Erigon, GitHub, NVIDIA, PeerDAS, TxPool, FCU,
Shutter Network, Docker Compose, …) are preserved.
- Untyped code fences ``` ``` ``` → ``` ```text ``` so Prism doesn't crash
on auto-detection. Tighter language tags (bash/yaml/json) can land in
follow-ups.
Verified via:
- Docusaurus production build (`pnpm run build`) — passes,
`onBrokenAnchors: 'throw'` clean.
- Zabaniya layer-1 review on staged diff — approved.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sentry is an Erigon module — it's a proper noun, not a generic term. The prior sentence-case pass lowercased it and produced the awkward "multiple sentries" plural. Rephrased to "one or more external Sentry instances" to keep the brand and avoid the pluralization entirely. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…uages Catches that the prior pass missed: - 11 `sentry` → `Sentry` (Erigon module name; now in the routine's §7.1 Tradenames table) - 2 untyped indented code fences inside list items (gnosis-with-an-external-cl.md) → `text` - 2 fences in configuring-erigon/nat.md tightened from `text` to their actual languages (`yaml`, `bash`) — the prior pass defaulted any untyped fence to `text` as a safe fallback Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…der, RPC Daemon) Treats the four Erigon component modules as proper nouns in prose, while keeping the binary / CLI / Go-package identifiers lowercase (those live in code fences, inline code, CLI flags, or paths and are unchanged). Module name normalization rules: - `sentry` (prose) → `Sentry` - `txpool` / `Txpool` (prose) → `TxPool` - `downloader` (prose) → `Downloader` - `rpcdaemon` / `RPCdaemon` / `RPCDaemon` / `RPC daemon` (prose) → `RPC Daemon` Notes: - The CLI binary / build target / package identifier (e.g. `./build/bin/rpcdaemon`, `make txpool`, `--txpool.api.addr`) stays lowercase. The audit script masks inline code, fenced blocks, CLI flags (`--foo.bar`), URLs, and paths, so only plain prose is rewritten. - Fixes one broken in-page anchor in fundamentals/tls-authentication.md (`#6-run-erigon-and-rpcdaemon-...` → `#6-run-erigon-and-rpc-daemon-...`) caused by the heading rename. Verified: Docusaurus build green (onBrokenAnchors: throw), Zabaniya approved. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Restore Title Case for all section headings touched by 03cf4d3. Per reviewer feedback we'll keep the existing Title Case convention across the site; the §7.3 sentence-case sweep was disproportionate to its value and a separate concern from the other audit fixes. Preserved (kept from the original PR): - §7.1 tradename casing in prose (Docker, Linux, Sentry, TxPool, …) - §7.4 terminology ("execution client" → "execution layer client") - §7.3 code-fence types (untyped ``` → ```text — Prism auto-detect crashes) - Substantive heading edits that incidentally touch tradenames ("RPCdaemon" → "RPC Daemon" in 3 headings, "Sentry" rephrasing) Reverted: 171 pure-case heading rewrites across 39 files. Filter rule: revert any heading line whose only difference from base is letter case (old.lower() == new.lower()); substantive heading edits preserved automatically. Docusaurus build: passes, onBrokenAnchors: 'throw' clean. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…dings The prior revert commit over-applied the case-folded-equality rule to three headings whose only difference between PR and base was a tradename normalization, not a Title→sentence rewrite. Restore the canonical tradename casing in those three lines: - modules/txpool.md:15 Txpool → TxPool - modules/txpool.md:19 Txpool → TxPool - installation/upgrading.md:73 MacOS → macOS (The namespace heading `# txpool` in interacting-with-erigon/txpool.md is intentionally lowercase — consistent with `# admin`, `# eth`, `# net`, etc. — so left untouched.) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Brings the auto-generated llms-full.txt back in sync with the current docs state after the heading-case revert. Picks up the tradename and terminology fixes that survive in the current PR scope. Generated by: python3 docs/site/scripts/generate-llms.py Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
§7.1 tradename normalization in JSX content (the original audit only touched markdown prose, missing this JSX card descriptor). Caught by Zabaniya pre-push review on the regenerated llms-full.txt. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Repo keeps two copies (root + docs/site/static) for GitHub raw access and Docusaurus serving respectively. Both regenerated from same source. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Erigon v3 has a single staged-sync pipeline — there is no user-facing "sync mode" choice. The user-facing decision is `--prune.mode` with values archive/full/minimal. The previous "Sync Modes" page title was a v1-era hold-over; the page body already used "prune mode" terminology throughout, so this commit aligns the title, URL, and all references across the site. Changes: - Renamed docs/site/docs/fundamentals/sync-modes.md → prune-modes.md (frontmatter title and H1 updated) - Updated all internal links (~16 occurrences) across docs/ and help-center/ (markdown links, JSX <Link> hrefs, inline prose) - Regenerated llms.txt and llms-full.txt (both root + docs/site/static/) Not changed: - versioned_docs/version-v3.3/fundamentals/sync-modes.md — that is a frozen snapshot of the v3.3 release docs and reflects what was published at that time. - Concept names that include the word "sync" but are distinct concepts (Staged Sync, OtterSync, Snapshot Sync) — preserved. Build: `pnpm run build` passes with onBrokenLinks/onBrokenAnchors: 'throw'. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 28, 2026
yperbasis
approved these changes
May 29, 2026
## Summary Two new pages in **Fundamentals**: - **`/fundamentals/architecture`** — staged sync, modular processes, storage split, embedded Caplin, flat-KV state. Mermaid component diagram at the top. - **`/fundamentals/database`** — datadir layout, MDBX engine properties, immutable `.seg` snapshots, per-transaction history granularity, mainnet sizing, tuning flags, safe-to-delete table. ## Stacked on #21451 Rebased on top of `docs/prose-audit-2026-05-27` so links can target the renamed Prune Modes page. GitHub auto-retargets the base to `release/3.4` once #21451 merges. ## Verification - `npm run build` passes with `onBrokenLinks`/`onBrokenAnchors: 'throw'` - `docs-site / build` (incl. llms verification) ✓ pass - llms.txt and llms-full.txt regenerated ## Notes - Sourced from the Improving-public-docs spec and the `README.md` "Datadir structure" / "Erigon3 datadir size" / "Modularity" sections. Once this lands, those README sections become safe to delete per the spec. - Adds `@docusaurus/theme-mermaid@^3.10.0` (used by the architecture diagram). --------- Co-authored-by: Bloxster <gianni.morselli@erigon.tech> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
pull Bot
pushed a commit
to Dustin4444/erigon
that referenced
this pull request
May 29, 2026
…e [main] (erigontech#21496) ## Summary Forward-port of [erigontech#21451](erigontech#21451) (against `release/3.4`) onto `main`. Same content fixes plus the Sync Modes → Prune Modes rename, applied to main's docs/ tree. Squashed into a single commit because the original branch's commit-by-commit history wouldn't cherry-pick cleanly (10 commits on a different base). ## Changes - §7.1 **Tradename casing** in prose — Docker, Linux, Sentry, TxPool, Downloader, RPC Daemon, MacOS → macOS, … - §7.4 **Terminology** — `execution client` → `execution layer client` - §7.3 **Code-fence types** — untyped ` ``` ` → ` ```text ` (Prism crashes on auto-detect on some snippets) - **Rename**: `docs/site/docs/fundamentals/sync-modes.md` → `prune-modes.md` (title + H1 + ~16 internal link updates across `docs/` and `help-center/`) - **llms.txt + llms-full.txt** regenerated (both `static/` and root copies) ## Forward-port nits Main was slightly behind `release/3.4` on two files; the 3-way merge picked up the newer release/3.4 content in addition to the prose-audit changes: - `default-ports.md`: eth/68 + eth/69 row split, `--p2p.allowed-ports` flag entry, reworded "Typically" prose - `multiple-instances.md`: `30303/30304` port range in the port table These are minor content updates that should already be in main, not new content invented by this PR. ## Verification - `npm run build` passes with `onBrokenLinks`/`onBrokenAnchors: 'throw'` - llms regeneration matches the updated docs ## Merge order This is the main-targeted twin of [erigontech#21451](erigontech#21451). Either can merge first; they touch disjoint branches. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Bloxster <gianni.morselli@erigon.tech> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…)" This reverts commit f0b409c.
2 tasks
yperbasis
added a commit
that referenced
this pull request
Jun 1, 2026
Adds the **v3.4.3** section to `ChangeLog.md`, covering the user-facing changes merged to `release/3.4` since v3.4.2, and sets the v3.4.2 header to its release date (2026-05-22). **Bugfixes** - #21538 — second fix for the post-reorg `gas used mismatch` / state-leak still hitting v3.4.2 users - #21507 — `debug_getModifiedAccountsByHash` / `ByNumber` now match Geth semantics - #21389 — `--rpc.logs.maxresults` (documented in 3.4.0) now takes effect via the CLI **Improvements** - #21502 — fail-fast on oversized `engine_newPayload` backward download (less per-slot log spam / wasted fetches) Docs-only / internal PRs (#21451, #21408) are intentionally omitted. Version bump tracked separately in #21547. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
First pass running Step 7 of the docs check routine against
docs/site/docs/. Pure writing-quality fixes — no content changes, no link changes, no behavior changes.Categories (rule references → erigon-docs-check-routine §7.x)
docker/linux/ethereum/caplin/lighthouse/prometheus/MacOSmid-prose lowercase or wrong-case forms. Mid-identifier (e.g.go-ethereum,linux/amd64,docker-compose) preserved.execution client→execution layer clienton landing pages```→```text(Prism crashes on auto-detect on some snippets). Tighter language tags (bash/yaml/json) can land in follow-ups.Verification
cd docs/site && pnpm run build→ passes,onBrokenAnchors: 'throw'clean (no internal anchor link refers to a renamed heading)..mdx(e.g.go('install-docker')) — masked1.,Step 1:,**A.**) — preservedFork Choice Update (FCU)→Fork choice update (FCU)— FCU is a defined Ethereum spec concept; some style guides keep this capitalized).text(safe — disables syntax highlighting).Test plan
pnpm run startindocs/site) and confirm no visual regression.docslabel applied.🤖 Generated with Claude Code