Skip to content

README.md

Latest commit

 

History

History
114 lines (81 loc) · 3.9 KB

README.md

File metadata and controls

114 lines (81 loc) · 3.9 KB

bread-docs

Documentation website for Bread Cooperative, built with Astro Starlight. Deployed at docs.bread.coop.

Stack

  • Astro — static site framework
  • Starlight — documentation theme
  • Keystatic — admin CMS
  • Tailwind CSS v4 — utility-first styling
  • Content via Astro Content Collections (src/content/docs/)

Requirements

  • Node 24.14.0 or higher (see .nvmrc)

Dev Commands

npm install       # install dependencies
npm run dev       # dev server at localhost:4321
npm run build     # build to ./dist/
npm run preview   # preview production build

Project Structure

src/
├── content/docs/       # Markdown documentation (one file = one page)
├── overrides/          # Custom Starlight component overrides
├── plugins/            # Custom Starlight plugins
├── styles/global.css   # Bread design system + Starlight theme overrides
└── content.config.ts   # Content collection schema
astro.config.mjs        # Starlight config: sidebar, plugins, overrides

Content is organized into three sidebar sections:

Section Directory
About src/content/docs/about/
Solidarity Primitives src/content/docs/solidarity-primitives/
Bread Cooperative src/content/docs/bread-cooperative/

Customizations

This project uses several custom plugins and configurations beyond standard Starlight:

Sidebar Configuration (_meta.yml)

Sidebar labels, ordering, and collapsed states are controlled via _meta.yml files in each directory (powered by starlight-auto-sidebar):

# src/content/docs/about/_meta.yml
label: About          # Sidebar label
order: 0              # Position in parent
collapsed: true       # Collapse by default (subdirs only)

Key behaviors:

  • Top-level sections (About, Solidarity Primitives, Bread Cooperative) are expanded by default
  • All nested subdirectories are collapsed by default
  • Files appear before folders in the sidebar (via custom plugin)

Custom Plugins

starlightFilesBeforeFolders (src/plugins/)

  • Custom Starlight plugin that reorders sidebar entries
  • Ensures files (links) appear before folders (groups) at all nesting levels
  • Uses route data middleware with await next() to run after starlight-auto-sidebar

starlight-page-actions

  • Adds share buttons (LinkedIn, X, Threads, Bluesky, etc.) and AI prompt buttons to each page
  • Configured in astro.config.mjs

starlight-markdown-blocks

  • Enables custom admonition blocks like :::draft

URL Redirects

Astro redirects maintain backward compatibility with old short URLs:

Old URL Redirects To
/token /about/bread-token
/marketplace /about/bread-token/marketplace
/solidarity-fund /solidarity-primitives/crowdstaking
/angel-minters /solidarity-primitives/crowdstaking/angel-minters
/member-projects /solidarity-primitives/crowdstaking/member-projects

Custom slug: frontmatter has been removed from index files; URLs now follow the directory structure.

Design System

  • Fonts: Pogaca (Bread Display & Bread Body) — custom WOFF2 files in public/fonts/
  • Colors: Defined in src/styles/global.css with CSS custom properties
  • Dark mode: Fully supported via [data-theme='dark'] selectors

Deployment

Deployed to Netlify.

Setting Value
Build command npm run build
Publish directory dist
Node version 24

The site runs in static mode — Keystatic CMS is disabled in production.

Contributing

See AGENTS.md for a full reference on how this project is structured, how to add content, and the design system conventions.