Olympos ry — Website + Docs

The club's public website (home page + news/blog) and technical documentation (hardware manuals, imaging trains, software setup, service history), in one Astro project. Public pages are plain Astro; the docs section is Astro Starlight, mounted under /docs/.

Current status: deployed publicly to GitHub Pages, /docs included. The docs section doesn't contain real secrets (see Backups on the site for where those actually live), but it was originally scoped as members-only content (network layout, access codes) — if that changes back, it'll need real access control again, since GitHub Pages has no way to gate content.

Requirements

Node.js 24 (LTS) — see .nvmrc. With nvm: nvm use (or nvm install first time).

Local development

npm install
npm run dev

Then open the printed localhost URL. Local dev runs without the GitHub Pages /website base path (see Deployment below) — everything serves from /.

Adding a page

• Blog post: add a .md file under src/content/blog/. See any existing post for the frontmatter shape (title, date, image, imageAlt, excerpt).
• Docs page: add a .md/.mdx file under src/content/docs/docs/, then add it to the sidebar array in astro.config.mjs or it won't be navigable. If you touched a piece of hardware, add an entry to that instrument's service-log.md (newest entry on top).
• Other public page: add a .astro file under src/pages/.

Deployment

Pushing to main triggers .github/workflows/deploy-pages.yml, which builds the site and deploys it to GitHub Pages.

GitHub Pages serves this repo at olympos-ry.github.io/website/, not at a domain root, so the build sets BASE_PATH=/website (see the comment in astro.config.mjs). Astro's own generated asset paths handle this automatically, but the site also has hand-written absolute paths (/blog/, /images/...) across many blog posts and docs pages — scripts/fix-base-path.mjs rewrites those in dist/ after the build. Once a custom domain (CNAME) is configured, Pages serves from the domain root instead: at that point, remove BASE_PATH from the workflow, drop the base field and the BASE_PATH logic in astro.config.mjs, and delete scripts/fix-base-path.mjs and its step in the workflow.

Structure

src/
  pages/
    index.astro          # home page
    blog/
      index.astro        # blog listing
      [...id].astro      # individual post
  layouts/
    PublicLayout.astro   # shared header/footer/starfield for public pages
  styles/
    site.css             # public pages' styles
    theme.css            # Starlight (docs) theme override
  content/
    blog/                # blog posts (.md)
    docs/
      docs/               # the actual Starlight docs, mounted at /docs/
        index.mdx
        hardware.md
        hardware/
          c11/            # one folder per instrument
            index.md
            imaging-train.md
            software.md
            operations.md
            service-log.md
          azt8/
            index.md
            service-log.md
        general/
          network.mdx
          access.md
          backups.mdx

To document a new instrument, copy the c11/ folder (or, for simpler standalone equipment without an imaging train, just index.md + service-log.md like the allsky camera) and add the new pages to the sidebar in astro.config.mjs.