@gjsify/site 0.64.11 → 0.64.12-next.280

package/README.md

@@ -1,7 +1,8 @@
 # @gjsify/site
 
-Static landing page generator for a GNOME-style app. Everything on the page comes from files the
-project already has — the AppStream metainfo, the root `package.json`, the app's gettext
+Static landing page generator for a GNOME-style app — and, with the same look, for the developer
+behind it: a hub, a CV and a blog (see [Developer sites](#developer-sites)). Everything on the page
+comes from files the project already has — the AppStream metainfo, the root `package.json`, the app's gettext
 catalogues, a screenshot directory — plus, at build time, the GitHub release and Flathub APIs.
 Nothing about any particular app is compiled in: all app-specific values come from a
 `gjsify.site` block.
@@ -39,10 +40,10 @@ gjsify site build --runtime node        # build and run on a specific runtime
 
 | Option | Meaning |
 | --- | --- |
-| `--overview <file>` | `build`: render the support overview listed in this JSON file instead of one app (see below). |
 | `--root <path>` | Repository to work on — a checkout whose root `package.json` has `gjsify.site`. Default: the working directory. |
 | `--out <dir>` | Output directory, emptied first. Default: `<root>/dist`. |
 | `--offline` | Skip every network call. The page then links to the releases page and omits the counts. |
+| `--drafts` | `build`: include blog posts marked `draft: true`. |
 | `--no-cache` | Ignore the one-hour HTTP response cache. |
 | `--cache-dir <dir>` | Where the response cache and the image renditions live. Default: `<root>/node_modules/.cache/gjsify-site`. |
 | `--check` | `i18n`: report what is out of date instead of writing it. |
@@ -60,7 +61,8 @@ Every build also writes a 1200×630 link-preview card per language (`og-<lang>.p
 and rasterised by GdkPixbuf), `SoftwareApplication` JSON-LD, `hreflang` alternates with an
 `x-default` that points at the default-language page, a valid `og:locale` (`de_DE`), and a
 `sitemap.xml`. `robots.txt` is written only when `gjsify.site.base` is `/`; below a path the host
-root owns it and must list this sitemap. A page title or meta description that is too short
+root owns it and must list this sitemap. A site at `/` does that for every related app (or
+developer app) given as a site address on the same host. A page title or meta description that is too short
 (or only the app name) is reported as a build warning.
 
 A metainfo URL that points into the site's own `/<lang>/…` pages (it starts with `gjsify.site.url`)
@@ -118,21 +120,6 @@ this package does not assume or enforce that: each consumer supplies its own fil
 `privacy` does, because what counts as identical is a fact about the publisher, not something a
 shared package can derive.
 
-`gjsify site build --overview <file> --out <dir>` renders one page that lists several apps, each
-linking to its own support page, for a host such as `jumplink.eu/support/`:
-
-```json
-{
-  "url": "https://jumplink.eu/",
-  "base": "/support/",
-  "languages": ["en", "de"],
-  "apps": ["../learn6502", "../beifahrer"]
-}
-```
-
-Each `apps` entry is a repository root (relative to the file) with its own `gjsify.site` block;
-its name and published address are read from there.
-
 `GITHUB_TOKEN` is optional and only raises the API rate limit. When a lookup fails the build
 warns rather than failing: a release API outage is not a reason to have no page.
 
@@ -166,6 +153,9 @@ Lives in the root `package.json`, next to `ship` and `flatpak`.
 | `support`, `legal` | `support`: `{kind, url}` links, or `{kind: "sepa", name, iban, bic?, reference?}`, a bank transfer shown as IBAN plus an EPC QR code. `legal`: `{label, url}` links. Both empty by default: nothing is invented. |
 | `privacy` | `{statements: {<lang>: <path>}, hostingPolicyUrl?}`: a privacy page at `/<lang>/privacy/`, see below. Absent: no such page. |
 | `legalNotice` | `{statements: {<lang>: <path>}}`: a Legal Notice/Impressum page at `/<lang>/legal-notice/`, see below. Absent: no such page. |
+| `blog` | `{posts: <dir>}`: Markdown posts rendered at `/<lang>/blog/`, see [Blog](#blog). Absent: no blog. |
+| `theme` | `{accent?, displayFont?, imageRendering?}`: how the site departs from the default look, see [Theme](#theme). |
+| `developer` | Instead of `metainfo`: makes this a developer site, see [Developer sites](#developer-sites). |
 
 A `sepa` entry carries no amount, and its IBAN is checked when the config loads — length per
 country, alphabet, and the mod-97 checksum — so a typo fails the build instead of printing a QR
@@ -256,6 +246,82 @@ relative luminance and writes near-black or white into `--band-fg`, whichever th
 Everything below the masthead keeps the site's own neutral palette, so a pale brand colour cannot
 make the description unreadable. An app without `<branding>` gets the default blue.
 
+## Blog
+
+`"blog": { "posts": "blog" }` turns every `*.md` below that directory into a post. The language
+comes from the file name (`hello.en.md`, `hello.de.md`) or the frontmatter; files sharing a slug
+are translations of each other and link to each other through `hreflang`.
+
+```markdown
+---
+title: Hello
+date: 2026-10-20
+updated: 2026-10-22
+summary: One sentence for the index, the feed and the link preview.
+tags: [GNOME, gjsify]
+---
+
+First paragraph — the description when there is no `summary`.
+```
+
+| Key | Meaning |
+| --- | --- |
+| `title`, `date` | Required. `date`/`updated` are `YYYY-MM-DD` or an ISO 8601 date-time. |
+| `slug`, `lang` | Override what the file name says. |
+| `updated`, `summary`, `tags` | Optional. |
+| `draft` | `true` leaves the post out unless the build runs with `--drafts`. |
+
+| Page | URL |
+| --- | --- |
+| Index + Atom feed, per language | `/<lang>/blog/`, `/<lang>/blog/feed.xml` |
+| Post + its link-preview card | `/<lang>/blog/<slug>/`, `/<lang>/blog/<slug>/og.png` |
+| Tag, only in the languages that use it | `/<lang>/blog/tags/<tag>/`, `…/feed.xml` |
+
+Everything else in the directory — images, downloads — is published under `/blog/` at the same
+relative path, so `![shot](shot.png)` works in the editor and on the page. A link to another post's
+`.md` file becomes a link to that post's page; one to a post the build does not render (a draft,
+a typo) fails the build, since no Markdown is ever published. Posts are `BlogPosting` JSON-LD with
+`article:*` meta, and the landing page shows the newest three of its language.
+
+## Theme
+
+| Key | Meaning |
+| --- | --- |
+| `accent` | `"#rrggbb"` or `{light, dark}`: links, buttons, focus rings. The text on it is measured like the brand colour. |
+| `displayFont` | Repo-relative `.woff2` used for headings. The package ships and fetches no font itself. |
+| `imageRendering` | `"pixelated"` keeps pixel art crisp: CSS `image-rendering` plus nearest-neighbour renditions. Default `"auto"`. |
+
+The theme is written into each page as a short inline style, so a site without one gets exactly
+the default stylesheet.
+
+## Developer sites
+
+`developer` instead of `metainfo` makes the site about a person rather than one app — the same
+layout, support, privacy and legal pages, plus a hub and a CV:
+
+```json
+"gjsify": { "site": {
+  "url": "https://example.org",
+  "languages": ["en", "de"],
+  "developer": {
+    "resume": { "en": "content/resume.en.json", "de": "content/resume.de.json" },
+    "apps": ["https://example.org/notes/"]
+  },
+  "blog": { "posts": "blog" }
+} }
+```
+
+- `resume` names a [JSON Resume](https://jsonresume.org/schema) file for **every** configured
+  language — no page of a CV falls back to another language. `basics.image` of the default
+  language's résumé is the avatar; `basics.summary` is Markdown.
+- `apps` has the format of `relatedApps`; `relatedApps` itself is rejected here.
+- `base` defaults to `/` and `repository` is optional (it links the site's source).
+- With no metainfo `<branding>` to read, `theme.accent` also paints the masthead and the bar.
+
+The hub `/<lang>/` shows the person, their apps, the newest posts and a link to the CV
+`/<lang>/cv/`, which prints as a plain document. Both carry `ProfilePage` JSON-LD with the
+résumé's profiles as `sameAs`.
+
 ## Translations
 
 Two catalogue sets meet on the page, and they have different owners.

package/lib/cli.js

@@ -5,18 +5,17 @@
 // the CLI itself is on, and runs it — so there is no `gjsify-site` bin bound to
 // one runtime. See `packages/infra/cli/src/commands/site.ts`.
 import { join, resolve } from 'node:path';
-import { buildOverview, buildSite, syncSiteI18n } from './site.js';
+import { buildSite, syncSiteI18n } from './site.js';
 const USAGE = `Usage: gjsify site <command> [options]
 
   build [options]    Render the static pages of a repository
   i18n [options]     Update the page catalogues from the strings the build can emit
 
 Options:
-  --overview <file>  build: render the support overview listed in this JSON file
-                     instead of one app (url, languages, apps)
   --root <path>      Repository to work on (default: the working directory)
   --out <dir>        Output directory, emptied first (default: <root>/dist)
   --offline          Skip every network call
+  --drafts           build: include blog posts marked \`draft: true\`
   --no-cache         Ignore the one-hour HTTP response cache
   --cache-dir <dir>  Where to keep the response cache and image renditions
                      (default: <root>/node_modules/.cache/gjsify-site)
@@ -44,27 +43,18 @@ function cacheOption(flags) {
     return flagValue(flags, '--cache-dir');
 }
 async function build(flags) {
-    const overview = flagValue(flags, '--overview');
-    if (overview) {
-        const result = await buildOverview({
-            config: overview,
-            out: resolve(flagValue(flags, '--out') ?? join(process.cwd(), 'dist')),
-            packageDir: flagValue(flags, '--package-dir'),
-        });
-        console.log(`Built ${result.languages.length} overview pages for ${result.apps} apps`);
-        return 0;
-    }
     const root = resolve(flagValue(flags, '--root') ?? process.cwd());
     const result = await buildSite({
         root,
         out: resolve(flagValue(flags, '--out') ?? join(root, 'dist')),
         offline: flags.includes('--offline'),
+        drafts: flags.includes('--drafts'),
         cacheDir: cacheOption(flags),
         packageDir: flagValue(flags, '--package-dir'),
         githubToken: process.env.GITHUB_TOKEN || undefined,
         warn: (message) => console.warn(`warning: ${message}`),
     });
-    console.log(`Built ${result.languages.length} pages and ${result.screenshots} screenshots`);
+    console.log(`Built the pages in ${result.languages.length} languages and ${result.screenshots} screenshots`);
     return 0;
 }
 async function i18n(flags) {

package/lib/client/site.css

@@ -21,8 +21,8 @@
   --fg: #1d1d20;
   --muted: #5e5c64;
   --line: rgb(0 0 0 / 0.1);
-  --accent: #1c71d8;
-  --accent-fg: #fff;
+  --accent: var(--accent-light, #1c71d8);
+  --accent-fg: var(--accent-fg-light, #fff);
   --shadow: 0 8px 24px rgb(0 0 0 / 0.14);
   /* Lifts the screenshot off the brand band without drawing a card around it. */
   --shot-shadow: 0 0.75rem 2rem rgb(0 0 0 / 0.25);
@@ -46,7 +46,8 @@
     --fg: #f6f5f4;
     --muted: #b6b4b1;
     --line: rgb(255 255 255 / 0.11);
-    --accent: #3584e4;
+    --accent: var(--accent-dark, #3584e4);
+    --accent-fg: var(--accent-fg-dark, #fff);
     --shadow: 0 8px 24px rgb(0 0 0 / 0.5);
     --shot-shadow: 0 0.75rem 2rem rgb(0 0 0 / 0.45);
   }
@@ -78,6 +79,7 @@ picture {
 h1,
 h2,
 h3 {
+  font-family: var(--display-font, inherit);
   line-height: 1.2;
 }
 
@@ -1422,3 +1424,281 @@ app-support {
   color: var(--muted);
   font-size: 0.78rem;
 }
+
+/* Blog */
+
+.bar-link[aria-current="page"] {
+  opacity: 1;
+  text-decoration: underline;
+  text-underline-offset: 0.3em;
+}
+
+.post-list {
+  display: grid;
+  gap: 1rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.post-card {
+  padding: 1.25rem 1.5rem;
+  border: 1px solid var(--line);
+  border-radius: var(--radius-lg);
+  background: var(--surface);
+}
+
+.post-card h2,
+.post-card h3 {
+  margin: 0;
+  font-size: 1.25rem;
+}
+
+.post-card h2 a,
+.post-card h3 a {
+  color: var(--fg);
+  text-decoration: none;
+}
+
+.post-card h2 a:hover,
+.post-card h3 a:hover {
+  color: var(--accent);
+}
+
+.post-card > p:last-child {
+  margin-block-end: 0;
+}
+
+.post-meta {
+  margin: 0.25rem 0 0;
+  color: var(--muted);
+  font-size: 0.9rem;
+}
+
+.post-tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.4rem;
+  margin: 0.5rem 0 0;
+  padding: 0;
+  list-style: none;
+}
+
+.tag {
+  display: inline-block;
+  padding: 0.05rem 0.6rem;
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  background: var(--bg);
+  color: var(--muted);
+  font-size: 0.8rem;
+  text-decoration: none;
+}
+
+.tag:hover {
+  color: var(--accent);
+}
+
+.post-feed a,
+.post-back a {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.4rem;
+}
+
+.post-feed {
+  margin-block: 1.5rem 0;
+}
+
+.post-empty {
+  color: var(--muted);
+}
+
+.blog,
+.post,
+.cv {
+  max-width: var(--text);
+}
+
+.post-head {
+  margin-block-end: 2rem;
+}
+
+.post-back {
+  margin: 0 0 1rem;
+  font-size: 0.9rem;
+}
+
+.post-body img {
+  max-width: 100%;
+  height: auto;
+  border-radius: var(--radius);
+}
+
+.post-body pre {
+  overflow-x: auto;
+  padding: 1rem;
+  border-radius: var(--radius);
+  background: var(--surface);
+}
+
+.post-body blockquote {
+  margin-inline: 0;
+  padding-inline-start: 1rem;
+  border-inline-start: 3px solid var(--line);
+  color: var(--muted);
+}
+
+.latest-posts {
+  margin-block: 2.5rem;
+}
+
+.latest-posts h2 {
+  margin: 0 0 0.75rem;
+  font-size: 1.5rem;
+}
+
+/* Developer site */
+
+.developer-avatar img {
+  border-radius: var(--radius-lg);
+}
+
+.developer-cv {
+  margin-block-start: 1.5rem;
+}
+
+.developer-apps {
+  margin-block: 2.5rem;
+}
+
+/* CV */
+
+.cv-head {
+  display: flex;
+  align-items: center;
+  gap: 1.5rem;
+  margin-block-end: 2rem;
+}
+
+.cv-avatar {
+  flex: none;
+  border-radius: var(--radius-lg);
+}
+
+.cv-label {
+  margin: 0.25rem 0 0;
+  color: var(--muted);
+  font-size: 1.1rem;
+}
+
+.cv-contact {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.25rem 1.25rem;
+  margin: 0.75rem 0 0;
+  padding: 0;
+  list-style: none;
+  font-size: 0.9rem;
+}
+
+.cv-contact li {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+}
+
+.cv-section {
+  margin-block: 2rem;
+}
+
+.cv-section h2 {
+  margin: 0 0 0.75rem;
+  padding-block-end: 0.25rem;
+  border-bottom: 1px solid var(--line);
+  font-size: 1.35rem;
+}
+
+.cv-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.cv-entry + .cv-entry {
+  margin-block-start: 1.25rem;
+}
+
+.cv-entry h3 {
+  margin: 0;
+  font-size: 1.05rem;
+}
+
+.cv-entry p {
+  margin: 0.25rem 0 0;
+}
+
+.cv-period {
+  color: var(--muted);
+  font-size: 0.85rem;
+}
+
+.cv-highlights {
+  margin: 0.4rem 0 0;
+  padding-inline-start: 1.25rem;
+}
+
+.cv-entry .tags {
+  margin-block-start: 0.5rem;
+}
+
+@media (max-width: 600px) {
+  .cv-head {
+    flex-direction: column;
+    align-items: flex-start;
+  }
+}
+
+/* On paper the CV is the page: no bar, no footer, no colour, links spelled out where it matters. */
+@media print {
+  :root {
+    color-scheme: light;
+  }
+
+  .topbar,
+  .footer,
+  .post-feed,
+  .post-back {
+    display: none;
+  }
+
+  body {
+    background: #fff;
+    color: #000;
+  }
+
+  main {
+    padding: 0;
+  }
+
+  .column {
+    width: auto;
+    max-width: none;
+  }
+
+  .cv a {
+    color: inherit;
+    text-decoration: none;
+  }
+
+  .cv-section,
+  .cv-entry {
+    break-inside: avoid;
+  }
+
+  .tags li,
+  .tag {
+    border-color: #999;
+    background: none;
+  }
+}

package/lib/index.d.ts

@@ -1,8 +1,13 @@
+export * from './render/blog.js';
+export * from './render/developer.js';
+export * from './render/feed.js';
 export * from './render/html.js';
 export * from './cli.js';
 export * from './render/i18n.js';
 export * from './render/icons.js';
 export * from './render/images.js';
+export * from './render/layout.js';
+export * from './render/markdown.js';
 export * from './render/pages.js';
 export * from './render/qr.js';
 export * from './site-data/index.js';

package/lib/index.js

@@ -1,8 +1,13 @@
+export * from './render/blog.js';
+export * from './render/developer.js';
+export * from './render/feed.js';
 export * from './render/html.js';
 export * from './cli.js';
 export * from './render/i18n.js';
 export * from './render/icons.js';
 export * from './render/images.js';
+export * from './render/layout.js';
+export * from './render/markdown.js';
 export * from './render/pages.js';
 export * from './render/qr.js';
 export * from './site-data/index.js';

package/lib/render/blog.d.ts

@@ -0,0 +1,62 @@
+import { type BlogPost, type SiteCommonConfig } from '../site-data/index.js';
+import { type Shell } from './layout.js';
+type Config = Pick<SiteCommonConfig, 'base'>;
+/** How many posts an app's landing page shows. */
+export declare const LATEST_POSTS = 3;
+export declare function blogIndexUrl(config: Config, lang: string): string;
+export declare function blogFeedUrl(config: Config, lang: string, tag?: string): string;
+export declare function postUrl(config: Config, post: Pick<BlogPost, 'lang' | 'slug'>): string;
+export declare function tagUrl(config: Config, lang: string, tag: string): string;
+/** The post's own link-preview card, written next to its page. */
+export declare function postOgImage(config: Config, post: Pick<BlogPost, 'lang' | 'slug'>): string;
+/**
+ * Rewrites the URLs a post's Markdown names. A relative image or file resolves against the post's
+ * own directory below `<base>blog/` — where the build copies the asset files. A relative link to
+ * another post's `.md` file becomes that post's page, so a writer links files the way the editor
+ * shows them and the published page links pages.
+ */
+export declare function postUrlResolver(config: Config, post: BlogPost, postsDir: string, posts: readonly BlogPost[]): (url: string) => string;
+export declare function formatPostDate(date: string, lang: string): string;
+/** `summary`, or the start of the body when the post has none. */
+export declare function postDescription(post: BlogPost): string;
+export interface BlogIndexOptions {
+    /** Every post of the site, all languages: which other languages have a blog decides the switch. */
+    posts: readonly BlogPost[];
+    /** Renders the page of one tag instead of the whole index. */
+    tag?: string;
+    ogImage?: string;
+}
+/** `/<lang>/blog/` or `/<lang>/blog/tags/<tag>/`. */
+export declare function renderBlogIndex(shell: Shell, options: BlogIndexOptions): string;
+export interface BlogPostOptions {
+    posts: readonly BlogPost[];
+    /** The post's body, rendered — with `postUrlResolver` applied. */
+    html: string;
+    author: {
+        name: string;
+        url?: string;
+    };
+}
+/** `/<lang>/blog/<slug>/`. */
+export declare function renderBlogPost(shell: Shell, post: BlogPost, options: BlogPostOptions): string;
+/** The newest posts as a landing-page section; empty when the language has none. */
+export declare function latestPostsSection(shell: Shell, posts: readonly BlogPost[], count?: number): string;
+export interface BlogFeedOptions {
+    posts: readonly BlogPost[];
+    tag?: string;
+    author: {
+        name: string;
+        uri?: string;
+    };
+    /** Rendered body per post, keyed `<lang>/<slug>`. */
+    html: ReadonlyMap<string, string>;
+    iconUrl?: string;
+}
+export declare function postKey(post: Pick<BlogPost, 'lang' | 'slug'>): string;
+/** The Atom feed of one language, or of one tag in it. Relative URLs in the content are made absolute. */
+export declare function renderBlogFeed(shell: Shell, options: BlogFeedOptions): string;
+/** Every tag in one language, in first-use order. */
+export declare function tagsOf(posts: readonly BlogPost[], lang: string): string[];
+/** Renders a post's Markdown with its URLs resolved. */
+export declare function renderPostBody(config: Config, post: BlogPost, postsDir: string, posts: readonly BlogPost[]): string;
+export {};