handoff pass: vendored sveltia bundle, astro pinned ^7.2.10, root README + refreshed deploy runbook, review fixes (coverless card grid, shared NewsCard/lib, real site origin, nginx security headers, linger step, dead config removed, preview.css sync, tsconfig)

2026-09-03 14:56:53 +02:00
parent c64528a1d3
commit cec8018c18
35 changed files with 4095 additions and 2111 deletions
@@ -0,0 +1,59 @@
+# 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).