portal/README.md

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).