Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 44 additions & 40 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,48 +1,50 @@
# Zilkworm Docusaurus Site

Source for **https://zilkworm.erigon.tech** — the public documentation for Zilkworm, built with [Docusaurus 3](https://docusaurus.io/).
Source for **https://zilkworm.erigon.tech**, the public documentation for Zilkworm, built with [Docusaurus 3](https://docusaurus.io/). Read on to see how the site fits together, how to run it on your machine and how to add a page.

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.
Everything the site needs lives in this repo: configuration, theme overrides, the Overview components, and the markdown content under `docs/`. The Docusaurus build turns it into a static site, which is published through GitHub Pages.

## How it works

- **Pages**: every `.md` file under [`docs/`](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`](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`](docusaurus.config.ts) and the swizzled [`src/theme/Footer/index.tsx`](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`](src/css/custom.css). Fonts are self-hosted under [`static/fonts/`](static/fonts/).
- **Pages**: every `.md` file under [`docs/`](docs/) becomes a page, served from the site root (`routeBasePath: '/'`). The sidebar is explicit in [`sidebars.ts`](sidebars.ts), so a new page needs an entry there. Each `_category_.json` mirrors its category label for the llms generator.
- **Overview**: [`docs/index.md`](docs/index.md) is served at `/`. Its status strip and cards are components in [`src/components/Overview/`](src/components/Overview/); the strip reads [`src/data/status.json`](src/data/status.json).
- **Releases**: update `src/data/status.json` and `docs/reference/releases-and-assets.md` together on each release.
- **Redirects**: `@docusaurus/plugin-client-redirects` maps the old `/documentation/...` URLs and `/collaboration` to their new pages (see `docusaurus.config.ts`).
- **Navbar / footer**: configured in [`docusaurus.config.ts`](docusaurus.config.ts) and the swizzled [`src/theme/Footer/index.tsx`](src/theme/Footer/index.tsx). The footer links GitHub, releases, Ethproofs, the blog and Erigon.
- **Theme tokens**: the brand colour is Zilkworm green `#1F9D3E`, the fonts are Quantify, Montserrat and Nunito Sans, and the tokens also cover light and dark surfaces and navbar buttons. All of them live in [`src/css/custom.css`](src/css/custom.css). Fonts are self-hosted under [`static/fonts/`](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.
- **Analytics**: the Plausible script is injected through `headTags` in the config.
- **Custom domain**: [`static/CNAME`](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.
- **SEO**: each page has `title` and `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`](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:
```bash
python3 scripts/generate-llms.py
```

## Render it locally

Requirements: **Node ≥ 20** (Docusaurus 3 requirement).
You need **Node 24 or newer** (`engines` in `package.json`; CI uses Node 24), plus Python 3 for the llms generator.

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

Other useful scripts (all defined in [`package.json`](package.json)):
A few more scripts, all defined in [`package.json`](package.json):

```bash
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 typecheck # runs tsc over docusaurus.config.ts, sidebars.ts and components
npm run clear # clear the .docusaurus cache
```

## Authoring content

Add a new doc:
To add a new doc:

1. Create `docs/<section>/<page>.md` (or a new section with its own `_category_.json`).
1. Create `docs/<section>/<page>.md` and add its doc id to [`sidebars.ts`](sidebars.ts). A new section also needs a `_category_.json` with its label.
2. Add Docusaurus frontmatter:

```yaml
Expand All @@ -53,48 +55,50 @@ Add a new doc:
---
```

3. Save — the dev server hot-reloads.
3. Save the file, and the dev server hot-reloads it.

Notes:
Keep three things in mind:

- If the title contains a colon, **quote it** (`title: "Foo: Bar"`) — otherwise YAML parsing fails.
- MDX rejects raw `<` outside code fences. Use `&lt;` 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`](src/components/HomeCards.tsx) component this way.
- If the title contains a colon, **quote it** (`title: "Foo: Bar"`), or YAML parsing fails.
- MDX rejects a raw `<` outside code fences, so use `&lt;` or rephrase. Email and URL autolinks (`<a@b.com>`, `<https://…>`) need to be markdown links.
- Inline JSX is allowed in `.md` files (Docusaurus treats them as MDX). The Overview page (`docs/index.md`) imports its components this way. Keep prose outside the components so `llms.txt` picks it up.

## Layout

```
zilkworm-docs/
├── docs/ # markdown content (sidebar autogenerated)
│ ├── index.md # Welcome — served at /documentation
│ ├── getting-started/ # _category_.json sets label + sidebar position
│ ├── fundamentals/
│ └── testing/
├── docs/ # markdown content, served at /
│ ├── index.md # Overview, slug /
│ ├── provers/ # choosing a prover, Airbender, Hypercube, ZisK, Ethproofs posting
│ ├── inside-the-guest/ # execution pipeline, witness formats, precompiles, proof guarantees
│ ├── testing/ # execution spec tests, QEMU, ERE validation
│ └── reference/ # CLI, releases and assets, building, benchmarks and CI
├── 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.)
│ ├── components/Overview/ # status strip, product cards, reader cards
│ ├── data/status.json # release tag, EEST pin, Ethproofs status
│ ├── css/custom.css # all theme tokens (colors, fonts, buttons, etc.)
│ └── theme/
│ ├── Footer/index.tsx # swizzled footer (matches sibling sites)
│ └── NotFound/ # swizzled 404
│ ├── Footer/index.tsx # swizzled footer
│ ├── NotFound/ # swizzled 404
│ └── Root.tsx # canonical link tag
├── scripts/
│ ├── generate-llms.py # writes static/llms.txt and llms-full.txt
│ └── check-tsconfig-drift.mjs
├── 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/`
│ ├── CNAME # zilkworm.erigon.tech
│ ├── fonts/ # self-hosted woff2: Quantify, Montserrat, Nunito Sans
│ ├── img/ # logos, favicon, OG image
│ └── llms.txt, llms-full.txt
├── docusaurus.config.ts # site identity, plugins, redirects, navbar, themeConfig
├── sidebars.ts # explicit sidebar
└── package.json
```

## Design spec

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

- **[public-docs/docusaurus-design-spec.md](https://github.com/erigontech/erigon-documents/blob/master/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](https://github.com/erigontech/erigon-documents/blob/master/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.
- **[public-docs/docusaurus-design-spec.md](https://github.com/erigontech/erigon-documents/blob/master/public-docs/docusaurus-design-spec.md)**: the shared design across all Erigon docs sites (theme, fonts, footer pattern, NotFound shape, broken-link policy, gotchas). Read this one first.
- **[public-docs/zilkworm-docs-spec.md](https://github.com/erigontech/erigon-documents/blob/master/public-docs/zilkworm-docs-spec.md)**: the Zilkworm-specific deltas, such as site identity, the MDX-conversion map from the GitBook migration, page content goals, tradenames and 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`.
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 is the source of truth across all Erigon docs sites. Anything Zilkworm-specific (content structure, page intent, the Overview page, the llms generator) belongs in `zilkworm-docs-spec.md`.
6 changes: 0 additions & 6 deletions docs/fundamentals/_category_.json

This file was deleted.

Loading
Loading