docs(help-center): refresh FAQs from support trends, fix consistency - #22696
Merged
Conversation
Mined the Feb–Jul Discord support export for recurring, durable issues and reconciled stale/inconsistent content across the help center. Added (support-driven): - FAQ + Common Errors: node falls behind tip after weeks → wipe datadir/chaindata (not the whole datadir); the chaindata-vs-datadir distinction; "no peers / won't sync" port list (30303/30304, Caplin 4000/4001, torrent 42069, NAT flags); OOM tuning (GOMEMLIMIT/GOGC/ GOMAXPROCS/--batchSize) with rationale; default log path; where to report security vulnerabilities (EF Bug Bounty). - Common Errors: "bad block / invalid block forkchoice loop" recovery. Fixed for consistency: - FAQ #5 stale disk figures (920GB/1.77TB) → defer to Hardware Requirements + Database (figures drift; also contradicted database.md). - FAQ #16 sync-stage prefix [4/8]…[8/8] → [4/6 Execution] with a config-dependent-total caveat (matches real logs). - Glossary MCP "(v3.4 only)" → "(v3.4+)" (present in current v3.5 docs). - troubleshooting.md backslash-escaped code (\-X, eth\_syncing, \[\], net\_peerCount) that rendered literally → clean; add default log path. Verified: npm run build passes with onBrokenLinks: throw; port/flag/NAT claims cross-checked against default-ports.md and nat.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates Help Center documentation to reflect recent support trends and reconcile inconsistencies across operator-facing guidance.
Changes:
- Improves troubleshooting instructions (fixes inline code escaping, updates
eth_syncingcurl example, and documents default log file location). - Refreshes FAQs with drift-resistant storage guidance, updated sync-log-prefix explanation, and new operational FAQs (chaindata recovery, ports, OOM tuning, security reporting, log location).
- Expands “Common Errors and Solutions” with new recovery entries (falls behind tip; bad block/invalid block forkchoice loop) and adds more concrete OOM mitigation guidance.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/site/help-center/troubleshooting.md | Cleans up command formatting and adds a default log path reference in the troubleshooting checklist. |
| docs/site/help-center/glossary-of-key-terms.md | Updates MCP Server availability note to reflect v3.4+ docs. |
| docs/site/help-center/frequently-asked-questions-faqs.md | Removes stale disk figures, revises sync progress explanation, and adds new operational FAQs (chaindata recovery, ports, OOM, security, logs). |
| docs/site/help-center/common-errors-and-solutions.md | Adds new error/recovery sections and expands OOM troubleshooting steps. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
AskAlexSharov
approved these changes
Jul 24, 2026
AskAlexSharov
enabled auto-merge
July 24, 2026 08:15
Improves search-engine and AI-assistant discoverability of docs.erigon.tech. > **Stacked on #22696** (help-center refresh). Base is `docs/help-center-refresh`; GitHub will auto-retarget this to `main` once #22696 merges. Review the 3-file SEO diff here. ## What it adds - **`TechArticle` JSON-LD** on every doc + Help Center page — a wrapper swizzle of `DocItem/Layout` (complements Docusaurus's native `BreadcrumbList`). Pages can opt out with `structured_data: false`. - **`FAQPage` JSON-LD** (31 Q&As) on the FAQ page for Google FAQ rich results and AI citation. Concise plain-text answers curated alongside the human-facing list; the page opts out of `TechArticle` to avoid a duplicate article entity. - **`noindex, follow` on archived versions** (`v3.3`/`v3.4`) so ranking signals consolidate on the current version instead of splitting across near-duplicate versioned pages. - **Sitemap `<lastmod>`** per URL (from git via `showLastUpdateTime`); dropped the client-side `/search` route. - **`showLastUpdateTime`** enabled — freshness dates on pages and in the sitemap. ## Verified in the production build - `TechArticle` on doc pages; **`FAQPage` with 31 questions**; archived pages carry `noindex` and no `TechArticle`; current pages indexed; `BreadcrumbList` preserved; sitemap has `lastmod` and excludes `/search`. - `npm run build` (with `onBrokenLinks: throw`) and `tsc` both pass. ## Why (context) Audit of the live site found only `BreadcrumbList` structured data. `FAQPage`/`TechArticle` are the schema types most associated with rich results and AI citation; `noindex` on old versions is a standard fix for versioned-docs duplication. Why not fully data-drive the FAQ: several answers contain code blocks and nested lists, so the visible answers stay authored Markdown while the schema uses curated concise answers (which is also what FAQ rich results prefer). A build-time remark extractor could unify them later. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Bloxster <gianni.morselli@erigon.tech> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
- Fix sync-log stage prefix example: [4/6 Execution] -> [6/8 Execution] to match the canonical 8-stage order in logs.md / basic-usage.mdx (both the structured-data block and the prose). - Align chaindata-wipe guidance (FAQ 26/27 + common-errors) with the Database doc: it is a chain-tip resync from the consensus layer, not an instant/few-minutes rebuild; keep a backup for fast recovery. - Fix OOM bash snippet so it is copy-paste-safe: export the runtime env vars, then pass --batchSize as an Erigon flag (was a bare shell line). - Reference the standardized log path <datadir>/logs/erigon.log instead of a bare erigon.log. - Regenerate llms-full.txt artifacts to keep the docs-site llms --check in sync. 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.
Refreshes the Help Center from the Feb–Jul community support log and reconciles stale/inconsistent content.
Added (support-driven)
datadir/chaindata(not the wholedatadir); thechaindata-vs-datadirdistinction; "no peers / won't sync" port list (30303/30304, Caplin4000/4001, torrent42069, NAT flags); OOM tuning (GOMEMLIMIT/GOGC/GOMAXPROCS/--batchSize) with rationale; default log path; where to report security vulnerabilities (EF Bug Bounty).Fixed for consistency
920GB/1.77TB, Sept 2025) → defer to Hardware Requirements + Database (figures drift; also contradicteddatabase.md).[4/8]…[8/8]→[4/6 Execution]with a config-dependent-total caveat (matches real logs).\-X,eth\_syncing,\[\],net\_peerCount) that rendered literally → cleaned; added default log path.Verification
npm run buildpasses withonBrokenLinks: throw— all internal links resolve.default-ports.mdandnat.md.Follow-ups (separate PRs): Schema.org (FAQPage/TechArticle) + SEO items; backports to
release/3.5andrelease/3.6for the live deploy.🤖 Generated with Claude Code