# CTAO Science Portal — static site + git-based CMS

Public portal for CTAO news, built as a fully static site. Editors get a
browser WYSIWYG editor (Sveltia CMS) that commits Markdown to a Gitea repo;
a build job turns commits into static HTML. No application or database runs
on the public path.

Live demo: <https://astro.isl-dev.grid.cyfronet.pl> ·
content repo (Gitea): <https://astro-git.isl-dev.grid.cyfronet.pl/ctao/portal>

## Stack

- **Astro** (static output). Pages are `.astro` templates (plain HTML with a
  JS frontmatter block). No React/Vue/Svelte components, no client-side
  framework.
- **Plain CSS** — everything lives in `src/styles/global.css` as design
  tokens (custom properties) + rules. No Tailwind, no preprocessor.
  The design system (tokens, type scale, spacing, motion policy) is
  documented in `DESIGN.md` — read it before touching styles.
- **Sveltia CMS** — a single prebuilt JS bundle, vendored in
  `public/vendor/sveltia-cms.js` and loaded on `/admin/`
  (`src/pages/admin/index.astro`), configured by `public/admin/config.yml`.
  It runs entirely in the editor's browser and talks to the Gitea API
  (OAuth PKCE). There is no CMS server. To update it:
  `curl -sL https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js -o public/vendor/sveltia-cms.js`
- Runtime dependencies: none beyond Astro. This is deliberate — keep it
  that way.

## Develop

```
npm ci
npm run dev        # http://localhost:4321
npm run build      # static output in dist/
```

## Layout

| Path | What |
|---|---|
| `src/pages/` | Routes (`.astro` templates), incl. `news/`, `search`, RSS/sitemap |
| `src/layouts/Base.astro` | HTML shell: head, header/nav, footer |
| `src/content/news/*.md` | Articles — Markdown + frontmatter (schema in `src/content.config.ts`) |
| `src/styles/global.css` | All CSS: tokens + components + prose |
| `DESIGN.md` | Design-system rules the CSS implements |
| `public/admin/` | CMS config (`config.yml`) + editor preview styles (`preview.css`) |
| `public/uploads/` | Editor-uploaded media (committed as WebP by the CMS) |
| `deploy/` | Runbook + container/systemd units for the demo machine — see `deploy/README.md` |

## Editing content

Editors use `/admin/` (link in the footer) and sign in with a Gitea account.
Saving commits to `main`; the machine polls and republishes automatically
(seconds). Full history/rollback = git history in Gitea. Articles with
`draft: true` are excluded from the build.

Note for styling work: `public/admin/preview.css` mirrors the `.prose` rules
from `global.css` so the editor preview matches the site 1:1 — keep them in
sync (both files carry a KEEP IN SYNC comment).