ctao/portal
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Simple conetent + restyled

Browse Source
This commit is contained in:
kuba
2026-09-21 17:59:29 +02:00
parent 0772462742
commit 467bf77d34
55 changed files with 2162 additions and 2070 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+96 -86
View File
@@ -1,100 +1,110 @@
# CTAO Science Portal: static site + git-based CMS
# CTAO Science Portal — simple proof of concept
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.
The `simple` branch uses the sibling `mockup` project's layout, assets, CSS,
and header interactions. Astro generates a static site. Sveltia CMS edits
exactly four Markdown pages in the separate `ctao/content` repository.
Live demo: <https://astro.isl-dev.grid.cyfronet.pl> ·
Gitea on the demo machine: <https://astro-git.isl-dev.grid.cyfronet.pl>
## Scope
## Repository layout & deployment
| Example submenu | URL | Content file |
|---|---|---|
| Lorem ipsum | `/example/lorem-ipsum/` | `pages/lorem-ipsum.md` |
| Dolor sit amet | `/example/dolor-sit-amet/` | `pages/dolor-sit-amet.md` |
| Consectetur adipiscing | `/example/consectetur-adipiscing/` | `pages/consectetur-adipiscing.md` |
| Sed do eiusmod | `/example/sed-do-eiusmod/` | `pages/sed-do-eiusmod.md` |
Code and content are SEPARATE repositories, so editorial commits never mix
with development:
Home, News, Data, Proposals, Dashboard, Sign in, Search, Support, Privacy,
Disclaimer, and Contact have the shared header/footer, a title, and an empty
body. Search submits to its placeholder. Only English is available; the
other language options are inactive. There are no news articles, news
pagination, RSS feeds, search index, service integrations, or public sign-in.
`/admin/` remains the working CMS entry point.
| Repo | Holds | Source of truth | Who commits |
|---|---|---|---|
| `ctao-portal` (this one, Bitbucket) | Templates, CSS, deploy | development | the team |
| `ctao/content` (Gitea on the demo machine) | `news/`, `pages/`, `uploads/` | editorial | Sveltia CMS / editors |
## Run locally
The demo machine polls ITS Gitea (`ctao/portal` mirror + `ctao/content`) and
republishes on a push to either, so a push to Bitbucket does NOT deploy;
deploying code = pushing it to the machine's Gitea (a deliberate step). The
build overlays content onto code (`deploy/build.sh`); the content paths are
gitignored here.
Use Node 22.19 or newer (deployment uses Node 24).
## 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
Prerequisites: Node 22.19 or newer (the machine builds on Node 24), and
network access to the demo machine's Gitea (Cyfronet network / VPN) for the
content clone below. Without content the site still builds, but with no
articles and `npm run check` reports the footer's page links as broken.
```
```sh
npm ci
git clone https://astro-git.isl-dev.grid.cyfronet.pl/ctao/content.git ../ctao-content
./scripts/link-content.sh # copies news/pages/uploads into the dev tree
npm run dev # http://localhost:4321
npm run build # static output in dist/
npm run check # deterministic gate: astro check (types) + build + internal-link check
npm run dev
```
`tsconfig.json` excludes `public/` on purpose: the vendored CMS bundle there is
2 MB of minified JS and would make `astro check` run out of memory.
Open `http://localhost:4321/example/lorem-ipsum/` for the full mockup example.
The first run copies bundled `sample-content/pages/` and `uploads/` into the
ignored runtime directories. Existing content is preserved. An incomplete
existing set fails with a missing-file error instead of silently mixing
sample content with editorial content.
## Layout
```sh
npm run content:setup # explicitly restore the four sample pages
npm run content:sync -- ../ctao-content # copy from a separate content checkout
npm run check # types, static build, internal links
npm run build
npm run preview # inspect the built site
```
| Path | What |
`content:setup` and `content:sync` replace the four runtime Markdown files and
copy uploads, overwriting same-named media. They do not modify the source
content checkout. Only the four allowlisted pages are loaded and rendered;
unrelated Markdown files never create public routes.
## Edit with Sveltia locally, without Gitea
```sh
npm run content:local
npm run dev
```
In Chrome or Edge, open `/admin/`, select **Work with Local Repository**, and
choose this project's `.tmp/content` directory. The setup command creates a
local Git repository there, seeded from the bundled content. Re-running it
preserves edits in that directory.
Save an Example page, then run this in another terminal to refresh the site:
```sh
npm run content:sync -- .tmp/content
```
The local editor writes files without committing them. This follows
[Sveltia's local workflow](https://sveltiacms.app/en/docs/workflows/local).
Choose the content repository root, not the portal code repository root:
the CMS expects `pages/` and `uploads/` directly beneath it.
## Content and publishing
The CMS uses a [fixed file collection](https://sveltiacms.app/en/docs/collections/files).
Editors can change title, introduction, optional image/alternative text/caption,
Markdown body, and optional button label/destination. Both button fields are
needed to display the button. A Markdown blockquote receives the mockup's
highlight styling. Images without alternative text are treated as decorative.
Menu labels, ordering, URLs, and the shared site layout remain code-controlled.
Remote editing uses Gitea OAuth and saves to **`ctao/content`, branch `simple`**.
That branch must contain the four files from `sample-content/pages/` and the
sample upload before publishing this version. The code mirror is
**`ctao/portal`, branch `simple`**. Deployment independently selects
`CODE_BRANCH` and `CONTENT_BRANCH`, overlays content, runs checks, and publishes
atomically. `CONTENT_BRANCH` must match `backend.branch` in the CMS config.
See [deploy/README.md](deploy/README.md) for migration and publishing steps.
A push to Bitbucket alone does not deploy the site.
## Where things live
| Path | Purpose |
|---|---|
| `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 (from the content repo, gitignored here; schema in `src/content.config.ts`) |
| `src/styles/global.css` | All CSS: tokens + components + prose |
| `DESIGN.md` | Design handoff: where the tokens live, brand basics, practical notes |
| `public/admin/` | CMS config (`config.yml`) + editor preview styles (`preview.css`) |
| `public/uploads/` | Editor-uploaded media (from the content repo, gitignored here) |
| `deploy/` | Runbook + container/systemd units for the demo machine, see `deploy/README.md` |
| `src/layouts/Base.astro` | Mockup header, navigation, footer, page shell |
| `src/components/PageHero.astro` | Breadcrumb, title, introduction, nebula |
| `src/pages/example/[slug].astro` | One reusable editable-page template |
| `src/data/examples.json` | Fixed submenu labels, order, and slugs |
| `src/data/placeholders.json` | Empty destinations |
| `src/styles/global.css` | Mockup styles plus Markdown/placeholder variants |
| `public/assets/`, `public/header.js` | Mockup assets and menu behavior |
| `sample-content/` | Versioned seed content for local use and Gitea setup |
| `src/content/pages/`, `public/uploads/` | Ignored runtime content overlay |
| `public/admin/config.yml` | Four fixed CMS files and Gitea configuration |
| `scripts/preview-styles.mjs` | Generates CMS body preview styles from site CSS |
## 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).
## Upgrading
Versions are pinned exactly; an upgrade is a deliberate change, never a side
effect of `npm install`. Astro ships security fixes only for the current and
one previous major, so plan one upgrade per major rather than skipping several.
```
npx @astrojs/upgrade # moves astro and official integrations together
npm run check # types + build + links must pass
npm run preview # verify the real dist/ output, not the dev server
```
No experimental flags in `astro.config.mjs`: they can change in minor releases.
The vendored CMS bundle remains in `public/vendor/sveltia-cms.js`. Dependencies
remain pinned; this simplification adds no application dependencies.