Polaris Astro documentation

Project structure

Where everything lives in Polaris, and which files you'll edit.

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

polaris-astro/
├── astro.config.mjs        Your domain (site), sitemap and the heading font
├── wrangler.jsonc          Settings for Cloudflare Workers (ignore it on other hosts)
├── public/                 Files served as they are: favicon.svg, apple-touch-icon.png
├── scripts/
│   ├── placeholders.mjs    Draws stand-ins for missing demo photos
│   └── palette.mjs         Regenerates the colour scales
└── src/
    ├── site.config.ts      Name, URL, currency, menus, footer, contact, demo bar, enquiry settings
    ├── content.config.ts   The rules each content file is checked against
    ├── content/
    │   ├── pages/          One file per page, built from blocks
    │   ├── destinations/   Places you run trips in
    │   ├── trips/          One file per trip
    │   ├── stays/          Lodges, homestays and campsites
    │   ├── posts/          Journal articles
    │   ├── team/           Guides and hosts
    │   └── reviews/        Guest reviews
    ├── assets/images/      Your photos, referred to by file name
    ├── blocks/             Every block: its settings (defs/), its markup and the /blocks/ examples
    ├── components/         Header, footer, enquiry form, booking box, search and small parts
    ├── i18n/ui.ts          Every word the theme prints itself
    ├── layouts/            The page shell: head tags, header and footer
    ├── lib/                Helpers, including details.ts (detail page layouts) and seo.ts (structured data)
    ├── 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 finder or a list of trips, and Polaris draws them in order. The file name is the address: about.md is published at /about/, and index.md is the home page.

Trips, stays, destinations and journal posts don’t need a page file. Polaris builds a page for each one from the files in their folders:

Folder	Address
`src/content/destinations/`	`/destinations/<file-name>/`
`src/content/trips/`	`/trips/<file-name>/`
`src/content/stays/`	`/stays/<file-name>/`
`src/content/posts/`	`/journal/<file-name>/`

The lists at /destinations/, /trips/, /stays/ and /journal/ are ordinary page files (destinations.md, trips.md, stays.md, journal.md). Guides and reviews have no pages of their own: they appear inside blocks.

The layout of each detail page is a list of blocks too, in src/lib/details.ts. See Pages and blocks.

Content files are checked

src/content.config.ts and the files in src/blocks/defs/ describe every field. If a page has a typo, such as varient: instead of variant:, or a trip is missing its price, 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 are left out of the sitemap and robots.txt disallows them. Keep them while you build, then delete src/pages/blocks.astro and src/pages/style-guide.astro if you don’t want them online.