@gjsify/site 0.64.14 → 0.64.15

package/README.md

@@ -285,6 +285,30 @@ a typo) fails the build, since no Markdown is ever published. Posts are `BlogPos
 `article:*` meta, and the landing page shows the newest three of its language. On a site with
 `support` entries, every post ends with a note linking to the support page.
 
+### Code blocks
+
+A fenced block is rendered plain — `<pre><code class="language-…">` — because the generator
+carries no highlighter. Colours come from a hook the caller supplies, which is what keeps them in
+the HTML instead of in a script on the page:
+
+```typescript
+import { buildSite } from '@gjsify/site';
+import { createHighlighter } from '@gjsify/site-highlight';
+
+const highlighter = await createHighlighter();
+await buildSite({
+    root: process.cwd(),
+    out: 'dist',
+    markdown: { highlight: (code, lang) => highlighter.highlight(code, lang) },
+});
+```
+
+`highlight` receives the block's text and its info string verbatim, and answers either the HTML to
+insert or `undefined` to keep the plain block. The returned HTML is inserted as markup, so the hook
+owns escaping. [`@gjsify/site-highlight`](../site-highlight/README.md) is the ready-made one:
+Shiki on its JavaScript regex engine, the same HTML for light and dark, a Blueprint grammar Shiki
+does not bundle — and a stylesheet that has to be appended after the site's own.
+
 ## Theme
 
 | Key | Meaning |

package/lib/render/blog.d.ts

@@ -1,5 +1,6 @@
 import { type BlogPost, type SiteCommonConfig } from '../site-data/index.js';
 import { type Shell } from './layout.js';
+import { type MarkdownOptions } from './markdown.js';
 type Config = Pick<SiteCommonConfig, 'base'>;
 /** How many posts an app's landing page shows. */
 export declare const LATEST_POSTS = 3;
@@ -59,6 +60,10 @@ export declare function postKey(post: Pick<BlogPost, 'lang' | 'slug'>): string;
 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;
+/**
+ * Renders a post's Markdown with its URLs resolved. `markdown` reaches the renderer untouched,
+ * except for `resolveUrl`, which the post's own URL resolver supplies — that is what makes a
+ * relative image or a link to another post's `.md` file work on the published page.
+ */
+export declare function renderPostBody(config: Config, post: BlogPost, postsDir: string, posts: readonly BlogPost[], markdown?: MarkdownOptions): string;
 export {};

package/lib/render/blog.js

@@ -241,7 +241,11 @@ export function renderBlogFeed(shell, options) {
 export function tagsOf(posts, lang) {
     return [...new Set(posts.filter((post) => post.lang === lang).flatMap((post) => post.tags))];
 }
-/** Renders a post's Markdown with its URLs resolved. */
-export function renderPostBody(config, post, postsDir, posts) {
-    return renderMarkdown(post.body, { resolveUrl: postUrlResolver(config, post, postsDir, posts) });
+/**
+ * Renders a post's Markdown with its URLs resolved. `markdown` reaches the renderer untouched,
+ * except for `resolveUrl`, which the post's own URL resolver supplies — that is what makes a
+ * relative image or a link to another post's `.md` file work on the published page.
+ */
+export function renderPostBody(config, post, postsDir, posts, markdown = {}) {
+    return renderMarkdown(post.body, { ...markdown, resolveUrl: postUrlResolver(config, post, postsDir, posts) });
 }

package/lib/render/markdown.d.ts

@@ -11,5 +11,16 @@
 export interface MarkdownOptions {
     /** Rewrites a link href or image src; absolute and `#` URLs are passed in too. */
     resolveUrl?: (url: string) => string;
+    /**
+     * Renders one fenced code block instead of the plain `<pre><code>` element — a syntax
+     * highlighter, for instance. `lang` is the fence's info string verbatim (empty when the fence
+     * names none), so a hook that only knows a few languages can answer `undefined` and leave the
+     * block as it is.
+     *
+     * Returning `undefined` falls back to the plain block. Returned HTML is inserted AS-IS and is
+     * therefore never escaped again: the hook owns escaping, because only it knows which parts of
+     * its output are markup.
+     */
+    highlight?: (code: string, lang: string) => string | undefined;
 }
 export declare function renderMarkdown(source: string, options?: MarkdownOptions): string;

package/lib/render/markdown.js

@@ -308,6 +308,10 @@ function renderBlock(block, options = {}) {
         case 'hr':
             return '<hr>';
         case 'code': {
+            const highlighted = options.highlight?.(block.content, block.lang ?? '');
+            if (highlighted !== undefined) {
+                return highlighted;
+            }
             if (block.lang) {
                 return `<pre><code class="language-${esc(block.lang)}">${esc(block.content)}</code></pre>`;
             }

package/lib/site.d.ts

@@ -1,4 +1,5 @@
 import { type I18nResult } from './render/i18n.js';
+import type { MarkdownOptions } from './render/markdown.js';
 /** Where a build reads from and writes to. */
 export interface SiteTarget {
     /** Repository root: the root package.json, the metainfo, the screenshots and the icon are read from here. */
@@ -21,6 +22,12 @@ export interface SiteBuildOptions extends SiteTarget {
     githubToken?: string;
     log?: (message: string) => void;
     warn?: (message: string) => void;
+    /**
+     * How a blog post's Markdown body is rendered. `resolveUrl` is supplied by the build; the
+     * useful field here is `highlight`, which lets a consumer colour code blocks without adding
+     * client JavaScript to the page. `undefined` keeps the plain `<pre><code>` output.
+     */
+    markdown?: MarkdownOptions;
     /** This package's install, for a caller whose module URL does not reveal it — a bundle. */
     packageDir?: string;
 }

package/lib/site.js

@@ -127,7 +127,7 @@ async function loadPageCatalogs(config, root, self, warn) {
     return catalogs;
 }
 /** Reads the posts and copies the files next to them to `<out>/blog/`, where the post URLs point. */
-async function loadBlog(config, target, drafts) {
+async function loadBlog(config, target, drafts, markdown) {
     if (!config.blog)
         return undefined;
     const dir = resolve(target.root, config.blog.posts);
@@ -136,7 +136,7 @@ async function loadBlog(config, target, drafts) {
         await mkdir(dirname(join(target.out, 'blog', file)), { recursive: true });
         await copyFile(join(dir, file), join(target.out, 'blog', file));
     }
-    const html = new Map(posts.map((post) => [postKey(post), renderPostBody(config, post, dir, posts)]));
+    const html = new Map(posts.map((post) => [postKey(post), renderPostBody(config, post, dir, posts, markdown)]));
     return { posts, html };
 }
 /** Writes the blog of every language and answers its sitemap entries. */
@@ -200,7 +200,7 @@ export async function buildSite(options) {
     const assets = await stageClientAssets(config.base, target.out, self);
     const catalogs = await loadPageCatalogs(config, target.root, self, options.warn);
     const displayFontUrl = await publishDisplayFont(config, target);
-    const blog = await loadBlog(config, target, options.drafts ?? false);
+    const blog = await loadBlog(config, target, options.drafts ?? false, options.markdown);
     const build = { options, target, cacheDir, assets, catalogs, displayFontUrl, blog };
     return config.kind === 'app' ? buildAppSite(build) : buildDeveloperSite(config, build);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/site",
-    "version": "0.64.14",
+    "version": "0.64.15",
     "description": "Static landing page generator for a GNOME-style app, rendered from its AppStream metainfo — downloads, screenshots, release notes, support links, no JavaScript required.",
     "type": "module",
     "main": "lib/index.js",
@@ -54,21 +54,21 @@
     "license": "MIT",
     "dependencies": {
         "@girs/gdkpixbuf-2.0": "5.4.0",
-        "@gjsify/console": "^0.64.14",
-        "@gjsify/crypto": "^0.64.14",
-        "@gjsify/fs": "^0.64.14",
-        "@gjsify/module": "^0.64.14",
-        "@gjsify/os": "^0.64.14",
-        "@gjsify/path": "^0.64.14",
-        "@gjsify/process": "^0.64.14",
-        "@gjsify/url": "^0.64.14",
+        "@gjsify/console": "^0.64.15",
+        "@gjsify/crypto": "^0.64.15",
+        "@gjsify/fs": "^0.64.15",
+        "@gjsify/module": "^0.64.15",
+        "@gjsify/os": "^0.64.15",
+        "@gjsify/path": "^0.64.15",
+        "@gjsify/process": "^0.64.15",
+        "@gjsify/url": "^0.64.15",
         "fast-xml-parser": "^5.11.2",
         "qrcode-generator": "^2.0.4"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.64.14",
+        "@gjsify/cli": "^0.64.15",
         "@gjsify/node-gi": "file:../../node-gi/node-gi",
-        "@gjsify/unit": "^0.64.14",
+        "@gjsify/unit": "^0.64.15",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },