Project structure

You’ll spend almost all your time in src/site.config.ts and src/content/. Everything else is the theme itself.

lyra-astro/
├── astro.config.mjs        Your domain, languages and heading font
├── wrangler.jsonc          Settings for Cloudflare Workers (ignore it on other hosts)
├── public/                 Files served as they are: favicon, reports (PDFs), video
├── scripts/
│   ├── placeholders.mjs    Draws stand-ins for missing demo photos
│   └── palette.mjs         Regenerates the colour scales
└── src/
    ├── site.config.ts      Your name, menus, footer, donation and form settings
    ├── content.config.ts   The rules each content file is checked against
    ├── content/
    │   ├── pages/en/       One file per page, built from blocks
    │   ├── pages/es/       The same pages in Spanish, served under /es/
    │   ├── causes/<lang>/  Programmes, at /causes/<file-name>/
    │   ├── campaigns/<lang>/ Fundraising campaigns with goals and deadlines
    │   ├── events/<lang>/  Events, with calendar files
    │   ├── stories/<lang>/ News and stories, with tags and RSS
    │   └── team/           Staff, board and ambassadors, one file per person
    ├── assets/images/      Your photos, referred to by file name
    ├── blocks/             Every block, its rules and the /blocks/ examples
    ├── components/         Header, footer, cards, donate form and small parts
    ├── i18n/               Languages, and every word the theme itself prints
    ├── layouts/            The page shell: head tags, header and footer
    ├── lib/                Helpers for content, campaigns, calendars and RSS
    ├── pages/              Routes. You rarely need to touch these.
    └── styles/             Design tokens, base styles and one CSS file per block

How a page is made

Every page file in src/content/pages/ has a sections: list. Each item is a block, such as a hero, a donate form or a list of stories, and Lyra draws them in order. The file name is the address: about.md is published at /about/, and index.md is the home page.

Causes, campaigns, events and stories don’t need a page file. Lyra builds a page for each one, plus the tag pages for stories, from the files in their folders.

Content files are checked

src/content.config.ts and src/blocks/schema.ts describe every field. If a page has a typo, such as varient: instead of variant: or a missing title, npm run dev shows an error naming the file and the field, rather than building a broken page.

Demo-only pages

/blocks/ (the block library) and /style-guide/ show every block and token. They’re left out of the sitemap and search. Keep them while you build, then delete src/pages/blocks.astro and src/pages/style-guide.astro if you don’t want them online.