# Erigon Docusaurus — Design & Customization Spec

> **Canonical specification:** https://github.com/erigontech/erigon-documents/tree/master/public-docs
> `docusaurus-design-spec.md` is the authoritative reference for this site's design.
> Always edit and refer to that copy — do not maintain a separate local version.

Complete specification of every customization applied to this site relative to a default Docusaurus 3 install. Use this as a reference when migrating the design to another Docusaurus project (e.g. Cocoon).

---

## 1. Stack & Versions

| Package | Version |
|---|---|
| `@docusaurus/core` | 3.10.0 |
| `@docusaurus/preset-classic` | 3.10.0 |
| `react` / `react-dom` | ^19.0.0 |
| `typescript` | ~6.0.2 |
| `@easyops-cn/docusaurus-search-local` | ^0.55.1 |
| `prism-react-renderer` | ^2.3.0 |
| Node requirement | `>=20.0` |

---

## 2. Site Identity (`docusaurus.config.ts`)

```ts
title:            'Erigon Documentation'
tagline:          'Ethereum execution client'
favicon:          'img/logo-icon-orange.png'
url:              'https://docs.erigon.tech'
baseUrl:          '/'
organizationName: 'erigontech'
projectName:      'docs'
trailingSlash:    false
onBrokenLinks:         'throw'
onBrokenMarkdownLinks: 'throw'
onBrokenAnchors:       'throw'
```

### i18n
Single locale — English only. No additional locales configured.

---

## 3. Plugins

### 3.1 Secondary Docs Instance — Help Center
```ts
{
  id: 'help-center',
  path: 'help-center',
  routeBasePath: 'help-center',
  sidebarPath: './sidebars-help-center.ts',
}
```
Both sidebars use auto-generation:
```ts
// sidebars.ts
docs: [{ type: 'autogenerated', dirName: '.' }]

// sidebars-help-center.ts
helpCenter: [{ type: 'autogenerated', dirName: '.' }]
```

### 3.2 Local Search
```ts
{
  hashed: true,
  language: ['en'],
  docsRouteBasePath: ['/', '/help-center'],
  indexDocs: true,
  indexBlog: false,
  indexPages: false,
  searchBarPosition: 'right',
}
```

---

## 4. Preset / Docs Config

```ts
docs: {
  sidebarPath: './sidebars.ts',
  routeBasePath: '/',    // docs served at root, not /docs/
}
blog: false             // blog completely disabled
theme: {
  customCss: './src/css/custom.css',
}
```

Syntax highlighting:
```ts
prism: {
  theme:     themes.github    // light mode
  darkTheme: themes.dracula   // dark mode
}
```

---

## 5. Navbar

### Logo
```ts
logo: {
  alt: 'Erigon',
  src: 'img/logo-icon-orange.png',
}
```
Logo height overridden in CSS: **28px**

### Title
```
"Erigon Client"
```
Font: **Montserrat**, weight 800, letter-spacing 0.04em (applied via CSS)

### Left Nav Items
| Label | Type |
|---|---|
| Docs | `docsInstanceId` (default instance) |
| Help Center | `docsInstanceId: 'help-center'` |

### Right Nav Items (all HTML type)

**Blog button** (outlined):
```html
<a href="https://erigon.tech/blog/" class="navbar-blog-btn" target="_blank">Blog</a>
```

**Release Notes button** (filled orange):
```html
<a href="https://github.com/erigontech/erigon/releases" class="navbar-release-btn" target="_blank">Release Notes</a>
```

**GitHub icon link**:
```html
<a href="https://github.com/erigontech/erigon" class="navbar-github-icon" target="_blank" aria-label="GitHub">
  <!-- SVG: GitHub mark, 20×20 -->
</a>
```

---

## 6. Footer

Completely swizzled (`src/theme/Footer/index.tsx`) — not using the Docusaurus built-in footer at all.

### Container
- Background: `#000000`
- Font: Nunito Sans, sans-serif
- Color: `#ffffff`

### Logo + Tagline (left column)
- Logo image height: **32px**
- Brand text: **Montserrat** font, weight 800, letter-spacing 0.04em
- Tagline: *"Building the future on the efficient software frontier."*
- Company address: Erigon Technologies AG, Dammstrasse 16, 6300 Zug, Switzerland

### Column Headers (all 4 columns)
- Font: **Montserrat**, weight 800
- Size: 0.8rem
- Letter-spacing: 0.08em
- Text-transform: uppercase
- Color: `rgba(255,255,255,0.4)`

### Column 1 — Products
| Label | URL |
|---|---|
| Erigon Client | `https://erigon.tech/products/erigon-client/` |
| Zilkworm | `https://erigon.tech/products/zilkworm/` |
| Cocoon | `https://erigon.tech/products/cocoon/` |
| R&D | `https://erigon.tech/products/rnd/` |

### Column 2 — Developers
| Label | URL |
|---|---|
| Zilkworm Docs ↗ | `https://zilkworm.erigon.tech` |
| Cocoon Docs ↗ | `https://cocoon.erigon.tech` |
| Erigon Docs ↗ | `https://docs.erigon.tech` |
| Blog | `https://erigon.tech/blog/` |

### Column 3 — Company
| Label | URL |
|---|---|
| About Us | `https://erigon.tech/about/` |
| Services | `https://erigon.tech/services/` |
| Contact | `https://erigon.tech/contact/` |
| Privacy Policy | `https://erigon.tech/privacy/` |
| Cookie Policy | `https://erigon.tech/cookies/` |

### Column 4 — Community (icon + label)

Each entry is an `<a>` with `display:flex`, `alignItems:center`, `gap:0.6rem`. Icons are inline SVG React components, `width/height:18`, `fill:currentColor` so they inherit the link color on hover.

| Platform | URL |
|---|---|
| X / Twitter | `https://x.com/erigoneth` |
| Discord | `https://dsc.gg/erigon` |
| GitHub | `https://github.com/erigontech` |
| LinkedIn | `https://www.linkedin.com/company/erigon/` |

**SVG paths (all `viewBox="0 0 24 24"`, `fill="currentColor"`):**

**X / Twitter** (`18×18`):
```svg
<path d="M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-4.714-6.231-5.401 6.231H2.744l7.73-8.835L1.254 2.25H8.08l4.258 5.632L18.244 2.25zm-1.161 17.52h1.833L7.084 4.126H5.117L17.083 19.77z"/>
```

**Discord** (`18×18`):
```svg
<path d="M20.317 4.37a19.791 19.791 0 0 0-4.885-1.515.074.074 0 0 0-.079.037c-.21.375-.444.864-.608 1.25a18.27 18.27 0 0 0-5.487 0 12.64 12.64 0 0 0-.617-1.25.077.077 0 0 0-.079-.037A19.736 19.736 0 0 0 3.677 4.37a.07.07 0 0 0-.032.027C.533 9.046-.32 13.58.099 18.057c.002.022.014.043.03.058a19.9 19.9 0 0 0 5.993 3.03.078.078 0 0 0 .084-.028c.462-.63.874-1.295 1.226-1.994a.076.076 0 0 0-.041-.106 13.107 13.107 0 0 1-1.872-.892.077.077 0 0 1-.008-.128 10.2 10.2 0 0 0 .372-.292.074.074 0 0 1 .077-.01c3.928 1.793 8.18 1.793 12.062 0a.074.074 0 0 1 .078.01c.12.098.246.198.373.292a.077.077 0 0 1-.006.127 12.299 12.299 0 0 1-1.873.892.077.077 0 0 0-.041.107c.36.698.772 1.362 1.225 1.993a.076.076 0 0 0 .084.028 19.839 19.839 0 0 0 6.002-3.03.077.077 0 0 0 .032-.054c.5-5.177-.838-9.674-3.549-13.66a.061.061 0 0 0-.031-.03zM8.02 15.33c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.956-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.956 2.418-2.157 2.418zm7.975 0c-1.183 0-2.157-1.085-2.157-2.419 0-1.333.955-2.419 2.157-2.419 1.21 0 2.176 1.096 2.157 2.42 0 1.333-.946 2.418-2.157 2.418z"/>
```

**GitHub** (`18×18`):
```svg
<path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/>
```

**LinkedIn** (`18×18`):
```svg
<path d="M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433a2.062 2.062 0 0 1-2.063-2.065 2.064 2.064 0 1 1 2.063 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 23.2 0 22.222 0h.003z"/>
```

**Community column layout (React):**
```tsx
<div style={{display: 'flex', flexDirection: 'column', gap: '0.75rem'}}>
  {[
    {label: 'X / Twitter', href: 'https://x.com/erigoneth',                        Icon: IconX},
    {label: 'Discord',     href: 'https://dsc.gg/erigon',                           Icon: IconDiscord},
    {label: 'GitHub',      href: 'https://github.com/erigontech',                   Icon: IconGitHub},
    {label: 'LinkedIn',    href: 'https://www.linkedin.com/company/erigon/',        Icon: IconLinkedIn},
  ].map(({label, href, Icon}) => (
    <a key={label} href={href} target="_blank" rel="noopener noreferrer"
      style={{
        display: 'flex', alignItems: 'center', gap: '0.6rem',
        color: 'rgba(255,255,255,0.65)',
        textDecoration: 'none', fontSize: '0.9rem', transition: 'color 0.15s',
      }}
      onMouseEnter={e => (e.currentTarget.style.color = '#EF7716')}
      onMouseLeave={e => (e.currentTarget.style.color = 'rgba(255,255,255,0.65)')}>
      <Icon />
      {label}
    </a>
  ))}
</div>
```

### Footer Link Colors
| State | Color |
|---|---|
| Default | `rgba(255,255,255,0.65)` |
| Hover | `#EF7716` |
| Muted / address text | `rgba(255,255,255,0.35)` |

### Bottom Bar
- Copyright: `© {year} Erigon Technologies AG. All rights reserved.`
- Inline links: Privacy Policy · Cookie Policy · Contact · hello@erigon.tech
- Font-size: 0.8rem
- Color: `rgba(255,255,255,0.35)`

---

## 7. Typography

### Font Loading (`src/css/custom.css`)
All fonts are self-hosted via `@font-face` (no CDN). Woff2 files live in `static/fonts/`.
```css
@font-face { font-family: 'Montserrat';   src: url('/fonts/Montserrat-ExtraBold.woff2')  format('woff2'); font-weight: 800; }
@font-face { font-family: 'Nunito Sans';  src: url('/fonts/NunitoSans-Regular.woff2')    format('woff2'); font-weight: 400; }
@font-face { font-family: 'Nunito Sans';  src: url('/fonts/NunitoSans-Bold.woff2')        format('woff2'); font-weight: 700; }
@font-face { font-family: 'Nunito Sans';  src: url('/fonts/NunitoSans-ExtraBold.woff2')  format('woff2'); font-weight: 800; }
```

### Font Roles
| Role | Family | Weight |
|---|---|---|
| Body text | Nunito Sans, sans-serif | 400 |
| Headings (h1–h6) | Montserrat, sans-serif | 800 |
| Navbar title, footer brand | Montserrat | 800 |
| Navbar left items | Montserrat | 800 |
| Code | system monospace | — |

### CSS Variables
```css
--ifm-font-family-base:     'Nunito Sans', sans-serif;
--ifm-heading-font-family:  'Montserrat', sans-serif;
--ifm-heading-font-weight:   800;
--ifm-code-font-size:        95%;
```

---

## 8. Color System

### Primary Brand Color — Erigon Orange

| Token | Hex |
|---|---|
| `--ifm-color-primary` | `#EF7716` |
| `--ifm-color-primary-dark` | `#D4660F` |
| `--ifm-color-primary-darker` | `#C55E0D` |
| `--ifm-color-primary-darkest` | `#A34E0B` |
| `--ifm-color-primary-light` | `#F28A33` |
| `--ifm-color-primary-lighter` | `#F3923F` |
| `--ifm-color-primary-lightest` | `#F6A862` |

Code highlight: `rgba(239,119,22,0.1)` light · `rgba(239,119,22,0.2)` dark

### Light Mode Surface Colors

| Token | Value |
|---|---|
| `--ifm-background-color` | `#FFFFFF` |
| `--ifm-font-color-base` | `#000000` |
| `--ifm-navbar-background-color` | `#FFFFFF` |
| `--ifm-navbar-link-color` | `#111111` |
| `--ifm-navbar-link-hover-color` | `#EF7716` |
| `--ifm-navbar-shadow` | `0 1px 0 rgba(0,0,0,0.08)` |
| `--navbar-btn-color` | `#111111` |
| `--navbar-btn-border` | `rgba(0,0,0,0.25)` |
| `--navbar-btn-color-muted` | `rgba(0,0,0,0.55)` |
| `--ifm-menu-color-active` | `#EF7716` |

### Dark Mode Surface Colors

| Token | Value |
|---|---|
| `--ifm-background-color` | `#0A0A0A` |
| `--ifm-background-surface-color` | `#141414` |
| `--ifm-font-color-base` | `#FFFFFF` |
| `--ifm-navbar-background-color` | `#000000` |
| `--ifm-navbar-link-color` | `#FFFFFF` |
| `--ifm-navbar-link-hover-color` | `#EF7716` |
| `--ifm-navbar-shadow` | `none` |
| `--navbar-btn-color` | `#FFFFFF` |
| `--navbar-btn-border` | `rgba(255,255,255,0.35)` |
| `--navbar-btn-color-muted` | `rgba(255,255,255,0.75)` |
| `--ifm-menu-color-active` | `#EF7716` |

---

## 9. Component CSS Details

### Navbar Buttons

**`.navbar-blog-btn`** (outlined style):
```css
border:        1px solid var(--navbar-btn-border);
color:         var(--navbar-btn-color);
padding:       0.35rem 0.9rem;
border-radius: 6px;
font-weight:   600;
font-size:     0.85rem;
/* hover */
border-color:  #EF7716;
color:         #EF7716;
box-shadow:    0 0 12px rgba(239,119,22,0.45);
```

**`.navbar-release-btn`** (filled orange):
```css
background:    #EF7716;
color:         #FFFFFF;
padding:       0.35rem 0.9rem;
border-radius: 6px;
font-weight:   700;
font-size:     0.85rem;
/* hover */
background:    #D4660F;
box-shadow:    0 0 14px rgba(239,119,22,0.6);
```

**`.navbar-github-icon`**:
```css
color:   var(--navbar-btn-color-muted);
/* hover */
color:   #EF7716;
```

### Landing Page Card (`.lp-card`)
```css
padding:       1.5rem;
border-radius: 8px;
border:        1px solid var(--ifm-color-emphasis-200);
transition:    border-color 0.2s ease, transform 0.2s ease, box-shadow 0.2s ease;
/* hover */
border-color:  #EF7716;
transform:     translateY(-2px);
box-shadow:    0 4px 20px rgba(239,119,22,0.14);
```

Card grid (`.lp-grid`):
```css
display:               grid;
grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
gap:                   1rem;
margin-top:            2rem;
```

### Details / Collapsible Sections
```css
background:      rgba(0,0,0,0.05);          /* light */
background:      rgba(255,255,255,0.04);    /* dark */
border:          1px solid rgba(0,0,0,0.1); /* light */
border:          1px solid rgba(255,255,255,0.1); /* dark */
border-radius:   8px;
text-decoration-color: #EF7716;
summary font-weight:   700;
```

### Pagination Links
Hover effect matches `.lp-card` (border turns orange, slight lift + shadow).

### 404 Page Buttons

**Primary (`.button-404-primary`)**:
```css
background:    #EF7716;
color:         #ffffff;
padding:       0.65rem 1.6rem;
border-radius: 6px;
font-weight:   700;
font-size:     0.95rem;
/* hover → background: #D4660F */
```

**Secondary (`.button-404-secondary`)**:
```css
border:        1px solid var(--ifm-color-emphasis-300);
color:         var(--ifm-font-color-base);
padding:       0.65rem 1.6rem;
font-weight:   600;
/* hover → border-color: #EF7716 */
```

**404 display number**:
```css
font-family:  Montserrat;
font-weight:  800;
font-size:    clamp(5rem, 18vw, 10rem);
color:        #EF7716;
```

---

## 10. Swizzled Components

| Component | Location | What it overrides |
|---|---|---|
| `NotFound` | `src/theme/NotFound/index.tsx` | Full 404 page wrapper (Layout + metadata) |
| `NotFound/Content` | `src/theme/NotFound/Content/index.tsx` | 404 body with branded hero + 6 nav cards |
| `Footer` | `src/theme/Footer/index.tsx` | Entire footer — multi-column layout with icons |

**404 Navigation Cards (6 links):**
1. Get Started → `/get-started/`
2. Easy Nodes → `/get-started/easy-nodes/`
3. Fundamentals → `/fundamentals/`
4. Staking → `/staking/`
5. Help Center → `/help-center/`
6. Release Notes → `https://github.com/erigontech/erigon/releases`

---

## 11. Static Assets

### Logo / Favicon
| File | Size | Usage |
|---|---|---|
| `static/img/logo-icon-orange.png` | 201 KB | Favicon, navbar logo, footer logo |
| `static/img/logo.svg` | 6.4 KB | SVG variant |
| `static/img/favicon.ico` | 3.6 KB | Browser tab icon |

### Chain Icons
| File | Chain |
|---|---|
| `static/img/eth.svg` | Ethereum |
| `static/img/gno.svg` | Gnosis Chain |
| `static/img/pol.svg` | Polygon |

### Brand Illustrations
| File | Usage |
|---|---|
| `static/img/shutter.svg` | Shutter Network card icon (staking landing page) |

### Deployment
`static/.nojekyll` — required for GitHub Pages to serve files beginning with `_`

---

## 12. Docs Content Structure

```
docs/
├── index.mdx               ← landing page
├── about/                  (category position 6)
├── get-started/            (category position 2)
│   ├── easy-nodes/
│   └── installation/
├── fundamentals/
│   ├── modules/
│   └── configuring-erigon/
├── interacting-with-erigon/
└── staking/

help-center/
└── (auto-generated from help-center/ dir)
```

---

## 13. Deployment (GitHub Actions)

**Workflow:** `.github/workflows/docs-deploy.yml`

- Trigger: push to `release/3.4` (or manual via `workflow_dispatch`)
- Node: 20, with npm cache (`docs/site/package-lock.json`)
- Build: `npm ci` → `npm run build` (with `GITHUB_TOKEN` forwarded for authenticated API calls)
- Target: GitHub Pages → `docs.erigon.tech`
- Permissions: `contents:read`, `pages:write`, `id-token:write`
- Concurrency: one deploy at a time (`docs-pages` group)

---

## 14. Not Used / Disabled

| Feature | Status |
|---|---|
| Blog | Disabled |
| i18n (multi-locale) | Not configured |
| Algolia search | Not used — local search only |
| Announcements bar | Not configured |
| Homepage (default) | Replaced by `/docs/index.mdx` at root |

---

## 15. Migration Checklist

When applying this design to a new Docusaurus project:

- [ ] Install non-default packages: `@easyops-cn/docusaurus-search-local`
- [ ] Copy `src/css/custom.css` (Google Fonts imports + all CSS variables)
- [ ] Copy `src/theme/Footer/index.tsx` and update column links/addresses
- [ ] Copy `src/theme/NotFound/index.tsx` + `src/theme/NotFound/Content/index.tsx` and update nav card links
- [ ] Add `img/logo-icon-orange.png` (or replace with project logo) to `static/img/`
- [ ] Configure navbar HTML items (blog btn, release btn, github icon) with correct URLs
- [ ] Set `routeBasePath: '/'` if docs should serve at root
- [ ] Add second docs instance (e.g. integration/help-center) if needed
- [ ] Set `onBrokenLinks: 'throw'`, `onBrokenMarkdownLinks: 'throw'`, `onBrokenAnchors: 'throw'`
- [ ] Copy Prism theme config (github light / dracula dark)
- [ ] Set `trailingSlash: false`
- [ ] Add `.nojekyll` to `static/` if deploying to GitHub Pages
