Zilkworm Docusaurus Site

Source for https://zilkworm.erigon.tech — the public documentation for Zilkworm, built with Docusaurus 3.

This repo is the entire site: configuration, theme overrides, the React landing page, and the markdown content under docs/. The Docusaurus build emits a static site that is published via GitHub Pages.

How it works

• Pages: every .md file under docs/ becomes a page. The sidebar is autogenerated from the directory tree; ordering comes from sidebar_position frontmatter and _category_.json in each subfolder.
• Landing page: src/pages/index.tsx is a custom React page served at / (hero, mission pillars, capability cards, CTAs). It bypasses the markdown pipeline.
• Navbar / footer: configured in docusaurus.config.ts and the swizzled src/theme/Footer/index.tsx. The footer cross-links sibling sites (Cocoon, Erigon docs) per the shared design spec.
• Theme tokens: brand colors (Erigon orange #EF7716), Quantify / Montserrat / Nunito Sans fonts, light + dark surfaces, navbar buttons — all in src/css/custom.css. Fonts are self-hosted under static/fonts/.
• Diagrams: Mermaid is enabled (@docusaurus/theme-mermaid); fenced ```mermaid blocks render inline.
• Search: client-side via @easyops-cn/docusaurus-search-local, indexed at build time.
• Analytics: Plausible script is injected via headTags in the config.
• Custom domain: static/CNAME pins the site to zilkworm.erigon.tech when published from GitHub Pages.
• SEO: Each page has title + description frontmatter that becomes <meta name="description"> and og:description. Global og:image, Twitter card, and site metadata are set in docusaurus.config.ts. sitemap.xml is generated at build time by @docusaurus/preset-classic; static/robots.txt references it.
• LLM-friendly: scripts/generate-llms.py walks docs/ and writes static/llms.txt (page index with descriptions) and static/llms-full.txt (full corpus). Regenerate after any docs change:

  python3 scripts/generate-llms.py

Render it locally

Requirements: Node ≥ 20 (Docusaurus 3 requirement).

npm install        # one-time
npm run start      # dev server with hot reload on http://localhost:3000

Other useful scripts (all defined in package.json):

npm run build      # production build into ./build (static HTML/CSS/JS)
npm run serve      # serve the production build locally
npm run typecheck  # tsc — verifies docusaurus.config.ts, sidebars.ts, components
npm run clear      # clear the .docusaurus cache

Authoring content

Add a new doc:

1. Create docs/<section>/<page>.md (or a new section with its own _category_.json).

2. Add Docusaurus frontmatter:

   ---
   title: Page Title
   description: One-line meta description used for SEO + cards.
   sidebar_position: 3
   ---

3. Save — the dev server hot-reloads.

Notes:

• If the title contains a colon, quote it (title: "Foo: Bar") — otherwise YAML parsing fails.
• MDX rejects raw < outside code fences. Use < or rephrase. Email/URL autolinks (<a@b.com>, <https://…>) need to be markdown links.
• Inline JSX is allowed in .md files (Docusaurus treats them as MDX). The Welcome page (docs/index.md) imports the HomeCards component this way.

Layout

zilkworm-docs/
├── docs/                     # markdown content (sidebar autogenerated)
│   ├── index.md              # Welcome — served at /documentation
│   ├── basics/               # _category_.json sets label + sidebar position
│   ├── use-cases/
│   └── testing/
├── src/
│   ├── pages/
│   │   ├── index.tsx         # custom landing at /
│   │   └── index.module.css
│   ├── components/
│   │   ├── HomeCards.tsx     # 3-card grid used on the Welcome page
│   │   └── HomeCards.module.css
│   ├── css/custom.css        # all theme tokens (colors, fonts, buttons, etc.)
│   └── theme/
│       ├── Footer/index.tsx  # swizzled footer (matches sibling sites)
│       └── NotFound/         # swizzled 404
├── static/
│   ├── CNAME                 # zilkworm.erigon.tech
│   ├── fonts/                # self-hosted woff2 — Quantify/Montserrat/NunitoSans
│   └── img/                  # logos, favicon, OG image
├── docusaurus.config.ts      # site identity, plugins, navbar, themeConfig
├── sidebars.ts               # autogenerated sidebar from `docs/`
└── package.json

Design spec

This site has two source-of-truth specs in erigontech/erigon-documents:

• public-docs/docusaurus-design-spec.md — Shared design across all Erigon docs sites (theme, fonts, footer pattern, NotFound shape, broken-link policy, gotchas). Read this first.
• public-docs/zilkworm-docs-spec.md — Zilkworm-specific deltas: site identity, the custom React landing, MDX-conversion map from the GitBook migration, page content goals, tradenames, open questions.

When something visual feels ambiguous or you need to add a new chrome element (navbar button, footer column, color token), check the design spec first — it's the source of truth across all sibling sites. Anything Zilkworm-specific (content structure, page intent, the landing page, the llms generator) belongs in zilkworm-docs-spec.md.