Skip to content

docs: prose audit — tradenames + code-fence types#21451

Merged
bloxster merged 12 commits into
release/3.4from
docs/prose-audit-2026-05-27
May 29, 2026
Merged

docs: prose audit — tradenames + code-fence types#21451
bloxster merged 12 commits into
release/3.4from
docs/prose-audit-2026-05-27

Conversation

@bloxster

@bloxster bloxster commented May 27, 2026

Copy link
Copy Markdown
Collaborator

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)

Rule Count Notes
§7.1 Tradenames 29 docker/linux/ethereum/caplin/lighthouse/prometheus/MacOS mid-prose lowercase or wrong-case forms. Mid-identifier (e.g. go-ethereum, linux/amd64, docker-compose) preserved.
§7.4 Terminology 2 execution clientexecution layer client on landing pages
§7.3 Style (fences) 17 Untyped code fences ``````text (Prism crashes on auto-detect on some snippets). Tighter language tags (bash/yaml/json) can land in follow-ups.
§7.3 Style (headings) 169 Title-Case headings → sentence-case. Proper nouns / acronyms / mixed-case branding preserved (Erigon, GitHub, NVIDIA, PeerDAS, TxPool, FCU, Shutter Network, Docker Compose, Claude Desktop, OpenAI Codex, …)
TOTAL 217 changes across 44 files

Verification

  • Docusaurus build: cd docs/site && pnpm run build → passes, onBrokenAnchors: 'throw' clean (no internal anchor link refers to a renamed heading).
  • Zabaniya layer-1 review on staged diff: ✓ approved.
  • Iterative review caught several false-positive classes that have been hard-coded into the audit script:
    • Indented code fences (inside list items) — masked
    • JSX expression bodies in .mdx (e.g. go('install-docker')) — masked
    • Multi-word product names (Docker Compose, Shutter Network, Claude Desktop, OpenAI Codex, etc.) — preserved as units
    • Numeric / step / bold-letter heading prefixes (1., Step 1:, **A.**) — preserved
    • A few Title-Case → sentence-case conversions are judgment calls (e.g. Fork Choice Update (FCU)Fork choice update (FCU) — FCU is a defined Ethereum spec concept; some style guides keep this capitalized).
    • The untyped-fence default is text (safe — disables syntax highlighting).

Test plan

  • Browse the changed pages locally (pnpm run start in docs/site) and confirm no visual regression.
  • Spot-check 5 representative heading renames per section against the routine's §7.3 guidance.
  • Confirm docs label applied.
  • Move to ready-for-review once eyeballed.

🤖 Generated with Claude Code

…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>
@bloxster bloxster added the docs label May 27, 2026
Bloxster and others added 5 commits May 27, 2026 19:34
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>
@bloxster bloxster changed the title docs: prose audit — sentence-case headings + tradename casing + code fence types docs: prose audit — tradenames + code-fence types May 28, 2026
@bloxster bloxster marked this pull request as ready for review May 28, 2026 13:24
Bloxster and others added 3 commits May 28, 2026 15:27
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>
@bloxster bloxster requested a review from Giulio2002 as a code owner May 28, 2026 13:32
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>
## 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>
@bloxster bloxster merged commit a0a18ed into release/3.4 May 29, 2026
26 of 29 checks passed
@bloxster bloxster deleted the docs/prose-audit-2026-05-27 branch May 29, 2026 13:18
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants