feat(blog): blog core — unified remark-rehype pipeline, App Router pages, post scripts

The one render chain: remark-gfm, remark-directive (mapped-tag escape
hatch for future embed islands), rehype-figure, rehype-pretty-code with
vesper highlighting at build time. Shipped pages are flat HTML with
inline token colors and zero client JS.

- lib/markdown.ts mints all /blog HTML; lib/blog.js binds the section
- app/blog + app/blog/[slug] on the App Router (SSG, generateMetadata);
  app/post/[id] and lib/posts.js removed with the route
- content/posts moved to content/blog; the 2021 entries are draft:true,
  hello-world-again is the one published post (engine fixture: figure
  captioning, shiki, GFM table) with its edge.png image
- yarn post / yarn post:image scaffold posts and stage images
- e2e smoke routes follow the rename

app/blog/[slug]/page.js

+import Layout from "@/components/layout";
+import Date from "@/components/date";
+import utilStyles from "@/styles/utils.module.css";
+import styles from "../blog.module.css";
+import { getAllBlogSlugs, getBlogPost } from "@/lib/blog";
+
+export function generateStaticParams() {
+  return getAllBlogSlugs().map((slug) => ({ slug }));
+}
+
+export async function generateMetadata({ params }) {
+  const { slug } = await params;
+  const post = await getBlogPost(slug);
+  return {
+    title: post.title,
+    description: post.description,
+    openGraph: {
+      title: post.title,
+      description: post.description,
+      type: 'article',
+      url: `/blog/${post.slug}`,
+      publishedTime: post.date,
+      images: ['/images/profile.png'],
+    },
+  };
+}
+
+export default async function BlogPost({ params }) {
+  const { slug } = await params;
+  const post = await getBlogPost(slug);
+
+  return (
+    <Layout>
+      <article className={styles.article}>
+        <h1 className={utilStyles.headingXl}>{post.title}</h1>
+        <div className={`${styles.meta} ${utilStyles.lightText}`}>
+          <Date dateString={post.date} />
+          {post.tags && post.tags.length > 0 && (
+            <ul className={styles.tags}>
+              {post.tags.map((tag) => (
+                <li key={tag}>#{tag}</li>
+              ))}
+            </ul>
+          )}
+        </div>
+        {post.description && <p className={styles.description}>{post.description}</p>}
+        <div className={styles.prose} dangerouslySetInnerHTML={{ __html: post.contentHtml }} />
+      </article>
+    </Layout>
+  );
+}

app/blog/blog.module.css

+/* /blog styling. Two layers:
+ *  - hashed classes (.article, .prose, …) for structure the pages control;
+ *  - :global(.prose-*) / :global(.directive-note) for classes the markdown
+ *    pipeline emits (lib/markdown.ts) — plain, stable names so the lib stays
+ *    decoupled from any CSS module. Element selectors inside .prose style the
+ *    ordinary markdown output (tables, lists, code) the same way.
+ */
+
+.article {
+  max-width: 42rem;
+  margin: 0 auto;
+  padding-bottom: 4rem;
+  word-wrap: break-word;
+}
+
+.meta {
+  margin: 0.25rem 0 0;
+  display: flex;
+  align-items: baseline;
+  gap: 0.75rem;
+}
+
+.tags {
+  list-style: none;
+  display: flex;
+  gap: 0.5rem;
+  margin: 0;
+  padding: 0;
+  font-size: 0.85rem;
+}
+
+.tags li {
+  color: var(--text-muted);
+}
+
+.description {
+  margin: 1rem 0 0;
+  font-size: 1.1rem;
+  color: var(--text-muted);
+}
+
+/* ------------------------------------------------------------------ *
+ * Prose body — figures, tables, code, directive notes
+ * ------------------------------------------------------------------ */
+
+.prose {
+  margin-top: 2rem;
+  line-height: 1.7;
+  font-size: 1.05rem;
+}
+
+.prose h2,
+.prose h3 {
+  margin: 2rem 0 0.75rem;
+  letter-spacing: -0.02rem;
+}
+
+.prose a {
+  color: var(--link);
+}
+
+.prose blockquote {
+  margin: 1.5rem 0;
+  padding: 0.25rem 1.25rem;
+  border-left: 3px solid var(--border);
+  color: var(--text-muted);
+}
+
+/* Lone images wrapped by rehype-figure */
+.prose :global(.prose-figure) {
+  margin: 2rem 0;
+  text-align: center;
+}
+
+.prose :global(.prose-figure img) {
+  display: block;
+  max-width: 100%;
+  height: auto;
+  margin: 0 auto;
+  border-radius: 8px;
+}
+
+.prose :global(.prose-figcaption) {
+  margin-top: 0.6rem;
+  font-size: 0.85rem;
+  color: var(--text-muted);
+}
+
+/* GFM tables */
+.prose table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 1.5rem 0;
+  font-size: 0.95rem;
+}
+
+.prose th,
+.prose td {
+  border: 1px solid var(--border);
+  padding: 0.5rem 0.75rem;
+  text-align: left;
+}
+
+.prose th {
+  background: var(--surface-raised);
+}
+
+/* Code — shiki tokens are inline-styled by rehype-pretty-code; this supplies
+   the dark pre. Vesper's own background is #101010. */
+.prose pre {
+  background: #101010;
+  color: #d5d5d5;
+  padding: 1rem 1.25rem;
+  border-radius: 8px;
+  overflow-x: auto;
+  line-height: 1.6;
+  font-size: 0.9rem;
+}
+
+.prose pre code {
+  display: block;
+  padding: 0;
+  background: none;
+}
+
+.prose :not(pre) > code {
+  background: var(--surface-raised);
+  padding: 0.15em 0.4em;
+  border-radius: 4px;
+  font-size: 0.88em;
+}
+
+/* ::note[...] / ::note directives (lib/markdown.ts directiveComponents) */
+.prose :global(.directive-note) {
+  margin: 1.5rem 0;
+  padding: 0.75rem 1rem;
+  border-left: 3px solid var(--link);
+  border-radius: 0 8px 8px 0;
+  background: var(--surface-raised);
+}
+
+.prose :global(.directive-note p:last-child) {
+  margin-bottom: 0;
+}
+
+/* Draft badge (index, dev only) */
+.draftBadge {
+  margin-left: 0.5rem;
+  padding: 0.1rem 0.45rem;
+  border: 1px dashed #b8860b;
+  border-radius: 4px;
+  color: #b8860b;
+  font-size: 0.7rem;
+  letter-spacing: 0.08em;
+  vertical-align: middle;
+}

app/blog/page.js

+import Link from "next/link";
+import Layout from "@/components/layout";
+import Date from "@/components/date";
+import utilStyles from "@/styles/utils.module.css";
+import styles from "./blog.module.css";
+import { getBlogPosts } from "@/lib/blog";
+
+export const metadata = {
+  title: "Blog",
+  description: "Notes, project archaeology and background noise.",
+};
+
+export default function Blog() {
+  const posts = getBlogPosts();
+
+  return (
+    <Layout>
+      <section className={`${utilStyles.headingMd} ${utilStyles.padding1px}`}>
+        <h1 className={utilStyles.headingXl}>Blog</h1>
+        <ul className={utilStyles.list}>
+          {posts.map(({ slug, title, date, description, draft }) => (
+            <li className={utilStyles.listItem} key={slug}>
+              <Link href={`/blog/${slug}`} className={utilStyles.listItemLink}>
+                <span>{title}</span>
+              </Link>
+              {draft && <small className={styles.draftBadge}>DRAFT</small>}
+              <br />
+              <small className={utilStyles.lightText}>
+                <Date dateString={date} />
+                {description ? ` — ${description}` : null}
+              </small>
+              <br />
+            </li>
+          ))}
+        </ul>
+      </section>
+    </Layout>
+  );
+}

app/post/[id]/page.js

-import Layout from "@/components/layout";
-import Date from "@/components/date";
-import utilStyles from "@/styles/utils.module.css";
-import { getAllPostIds, getPostData } from "@/lib/posts";
-
-export function generateStaticParams() {
-  return getAllPostIds().map((id) => ({ id }));
-}
-
-export async function generateMetadata({ params }) {
-  const { id } = await params;
-  const postData = await getPostData(id);
-  return { title: postData.title };
-}
-
-export default async function Post({ params }) {
-  const { id } = await params;
-  const postData = await getPostData(id);
-
-  return (
-    <Layout>
-      <article>
-        <h1 className={utilStyles.headingXl}>{postData.title}</h1>
-        <div className={utilStyles.lightText}>
-          <Date dateString={postData.date} />
-        </div>
-        <div dangerouslySetInnerHTML={{ __html: postData.contentHtml }} />
-      </article>
-    </Layout>
-  );
-}

content/blog/hello-world-again.md

+---
+title: Hello World
+date: '2026-09-06'
+slug: hello-world-again
+description: Engine fixture — proves figure centering, build-time highlighting, tables. Prose to be written.
+---
+
+Skeleton post. Each element below exercises one rendering path of the blog engine; prose comes later.
+
+1. Centered figure with caption — image below.
+2. Build-time code highlighting — Hydra snippet below.
+3. GFM table — bottom of this post.
+
+![A Hydra sketch rendering a glowing nebula, shown in the Hydra editor](/images/blog/hello-world-again/edge.png)
+
+```js
+osc(20, 0.01, 1.4)
+  .kaleid(5)
+  .mult(osc(10).rotate(0.5))
+  .out()
+```
+
+| element    | proves                     |
+| ---------- | -------------------------- |
+| figure     | image path, caption, centering |
+| code block | shiki at build time        |
+| table      | GFM support                |

content/posts/hello-world.md → content/blog/hello-world.md

 ---
 title: Hello World
 date: '2021-04-23'
+draft: true
 ---
 
 > _C'est un petit pas pour l'homme, mais un grand pas pour le serverless._

content/posts/next.md → content/blog/next.md

 ---
 title: NextJs Tutorial
 date: '2021-04-23'
+draft: true
 ---
 
 Gotta say the [Vercel Next.JS Tutorial](https://nextjs.org/learn/basics/create-nextjs-app) was a delight to follow.

lib/blog.js

+import { getAllContentData, getAllContentIds, getContentData } from '@/lib/content';
+
+/** Blog posts, newest-first. Drafts follow the prod/dev rule in lib/content. */
+export function getBlogPosts() {
+  return getAllContentData('blog', true);
+}
+
+/** Slug list — App Router callers map it to params. */
+export function getAllBlogSlugs() {
+  return getAllContentIds('blog');
+}
+
+/** Single post with rendered HTML body; description stays plain for metadata. */
+export async function getBlogPost(slug) {
+  return getContentData('blog', slug, { plainDescription: true });
+}

lib/content/index.ts

 import path from 'path';
 import fs from 'fs';
 import matter from 'gray-matter';
-import { remark } from 'remark';
-import remarkHtml from 'remark-html';
+import { renderMarkdown } from '../markdown';
 
 /**
  * Unified content loader.
  *
  * Two collection shapes live here, on purpose — not one forced shape:
- *  - flat Markdown collections (posts, poems, talks, hydras): one .md per item
+ *  - flat Markdown collections (blog, poems, talks, hydras): one .md per item
  *    under content/<section>/, frontmatter + rendered HTML body;
  *  - ParVagues "lives": a richer, year-foldered gig collection with optional
  *    tracks.json and gig-photo folders.
  *
- * Thin section wrappers (lib/posts.js, lib/hydras.js, …) bind a section name to
+ * Thin section wrappers (lib/blog.js, lib/hydras.js, …) bind a section name to
  * the flat API; the ParVagues pages call the lives API directly.
  */
 
 const CONTENT_ROOT = path.join(process.cwd(), 'content');
 
+/**
+ * Draft frontmatter (`draft: true`) is dev-only: prod builds filter it out,
+ * every other context (dev server, jest, `SHOW_DRAFTS=true` for previews)
+ * keeps it visible.
+ */
+function draftsVisible() {
+  return process.env.NODE_ENV !== 'production' || process.env.SHOW_DRAFTS === 'true';
+}
+
+/** Frontmatter carried by every flat-collection item (defaults filled in). */
+export interface ContentFrontmatter {
+  slug: string;
+  draft: boolean;
+  [key: string]: any;
+}
+
+function normalizeEntry(fileName: string, data: any): ContentFrontmatter {
+  const id = idFromFileName(fileName);
+  return { ...data, id, slug: data.slug ?? id, draft: data.draft === true };
+}
+
 /* ------------------------------------------------------------------ *
  * Flat Markdown collections — content/<section>/<id>.md
  * ------------------------------------------------------------------ */
@@ -35,16 +55,11 @@ function idFromFileName(fileName: string) {
   return fileName.replace(/\.md$/, '');
 }
 
-async function renderMarkdown(md: string) {
-  const processed = await remark().use(remarkHtml).process(md);
-  return processed.toString();
-}
-
 export function getContentDirectory(section: string) {
   return sectionDir(section);
 }
 
-/** Frontmatter-only listing (used by index/listing pages). */
+/** Frontmatter-only listing (used by index/listing pages). Drafts filtered by the prod/dev rule. */
 export function getAllContentData(section: string, sorted = false) {
   const dir = sectionDir(section);
   const entries = fs
@@ -52,19 +67,40 @@ export function getAllContentData(section: string, sorted = false) {
     .filter(isMarkdownFile)
     .map((fileName) => {
       const { data } = matter(fs.readFileSync(path.join(dir, fileName), 'utf8'));
-      return { id: idFromFileName(fileName), ...data };
-    });
+      return normalizeEntry(fileName, data);
+    })
+    .filter((entry) => draftsVisible() || !entry.draft);
 
   return sorted ? entries.sort((a, b) => (a.date < b.date ? 1 : -1)) : entries;
 }
 
-/** Plain id list. App Router callers map it to params: ids.map((id) => ({ id })). */
+/** Plain id list. App Router callers map it to params: ids.map((id) => ({ id })). Drafts filtered by the prod/dev rule. */
 export function getAllContentIds(section: string): string[] {
-  return fs.readdirSync(sectionDir(section)).filter(isMarkdownFile).map(idFromFileName);
+  return fs
+    .readdirSync(sectionDir(section))
+    .filter(isMarkdownFile)
+    .map(idFromFileName)
+    .filter((id) => draftsVisible() || !isDraft(section, id));
+}
+
+function isDraft(section: string, id: string) {
+  const fileName = path.join(sectionDir(section), `${id}.md`);
+  if (!fs.existsSync(fileName)) return false;
+  const { data } = matter(fs.readFileSync(fileName, 'utf8'));
+  return data.draft === true;
+}
+
+export interface GetContentDataOptions {
+  /** Keep `description` as plain text (metadata) instead of rendering it to HTML. */
+  plainDescription?: boolean;
 }
 
 /** Single item with rendered HTML body (and HTML-rendered description, if any). */
-export async function getContentData(section: string, id: string) {
+export async function getContentData(
+  section: string,
+  id: string,
+  { plainDescription = false }: GetContentDataOptions = {},
+) {
   const fileName = id.endsWith('.md') ? id : `${id}.md`;
   const fullPath = path.join(sectionDir(section), fileName);
 
@@ -74,12 +110,13 @@ export async function getContentData(section: string, id: string) {
 
   const { data, content } = matter(fs.readFileSync(fullPath, 'utf8'));
   const contentHtml = await renderMarkdown(content);
+  const entry = normalizeEntry(idFromFileName(fileName), data);
 
-  if (typeof data.description === 'string') {
-    data.description = await renderMarkdown(data.description);
+  if (typeof entry.description === 'string' && !plainDescription) {
+    entry.description = await renderMarkdown(entry.description);
   }
 
-  return { id: idFromFileName(fileName), contentHtml, ...data };
+  return { contentHtml, ...entry };
 }
 
 /* ------------------------------------------------------------------ *

lib/markdown.ts

+/**
+ * Markdown render chain — the one place /blog HTML is minted.
+ *
+ * unified chain: remark-parse → remark-gfm → remark-directive →
+ * remark-rehype → rehype-figure (custom, below) → rehype-pretty-code →
+ * rehype-stringify. All highlighting happens here at build time via shiki;
+ * the shipped page is flat HTML with inline token colors and zero client JS.
+ *
+ * Directives are the escape hatch for future rich embeds (Hydra / Strudel
+ * islands): `directiveComponents` maps a directive name to a tag + class, the
+ * CSS module styles that class, and a client component can later take over the
+ * tag without this pipeline caring. Until islands exist, unknown directives
+ * are silently dropped by remark-rehype (the unified default).
+ */
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkDirective from 'remark-directive';
+import remarkRehype from 'remark-rehype';
+import rehypePrettyCode from 'rehype-pretty-code';
+import rehypeStringify from 'rehype-stringify';
+import { visit } from 'unist-util-visit';
+
+/**
+ * Directive name → { tag, className }. The component-map stub: add an entry
+ * to light a directive up (e.g. `::note[Heads up]` renders the note tag below);
+ * an island swap later means pointing the tag at a component, nothing more.
+ */
+export const directiveComponents: Record<string, { tag: string; className: string }> = {
+  note: { tag: 'div', className: 'directive-note' },
+};
+
+/** remark plugin: register mapped directives as hast tags via data.hName. */
+export function remarkDirectiveTags() {
+  return (tree: any) => {
+    visit(tree, (node: any) => {
+      if (
+        node.type !== 'containerDirective' &&
+        node.type !== 'leafDirective' &&
+        node.type !== 'textDirective'
+      ) {
+        return;
+      }
+      const mapping = directiveComponents[node.name];
+      if (!mapping) return;
+      node.data = node.data || {};
+      node.data.hName = mapping.tag;
+      node.data.hProperties = { className: [mapping.className] };
+    });
+  };
+}
+
+/**
+ * rehype plugin: wrap a lone image paragraph in <figure>, with the alt text as
+ * figcaption when present. Images sitting next to prose stay inline — only
+ * paragraphs that are just an image get figured.
+ */
+export function rehypeFigure() {
+  return (tree: any) => {
+    visit(tree, 'element', (node: any, index: number, parent: any) => {
+      if (node.tagName !== 'p' || index === null || !parent) return;
+      const img = node.children.find(
+        (child: any) => child.type === 'element' && child.tagName === 'img',
+      );
+      if (!img) return;
+      const leftovers = node.children.filter(
+        (child: any) =>
+          child !== img && !(child.type === 'text' && !child.value.trim()),
+      );
+      if (leftovers.length > 0) return;
+
+      const caption = img.properties && img.properties.alt;
+      parent.children[index] = {
+        type: 'element',
+        tagName: 'figure',
+        properties: { className: ['prose-figure'] },
+        children: [
+          img,
+          ...(caption
+            ? [
+                {
+                  type: 'element',
+                  tagName: 'figcaption',
+                  properties: { className: ['prose-figcaption'] },
+                  children: [{ type: 'text', value: caption }],
+                },
+              ]
+            : []),
+        ],
+      };
+    });
+  };
+}
+
+const processor = unified()
+  .use(remarkParse)
+  .use(remarkGfm)
+  .use(remarkDirective)
+  .use(remarkDirectiveTags)
+  .use(remarkRehype)
+  .use(rehypeFigure)
+  // Dark theme on a dark pre (background comes from the blog CSS module —
+  // keepBackground: false keeps the pipeline's HTML free of hardcoded hex).
+  .use(rehypePrettyCode, { theme: 'vesper', keepBackground: false })
+  .use(rehypeStringify);
+
+/** Markdown → HTML string (tables, directives, figures, shiki spans). */
+export async function renderMarkdown(md: string) {
+  return String(await processor.process(md));
+}

lib/posts.js

-import {getAllContentData, getAllContentIds, getContentData} from '@/lib/content'
-
-export function getPostsData() {
-  return getAllContentData('posts', true)
-}
-
-export function getAllPostIds() {
-  return getAllContentIds("posts")
-}
-
-export async function getPostData(id) {
-  return getContentData("posts", id)
-}

package.json

@@ -13,6 +13,8 @@
     "platform:build": "vercel build",
     "test": "jest -c jest.config.js",
     "test:watch": "jest -c jest.config.js --watch",
+    "post": "node scripts/new-post.mjs",
+    "post:image": "node scripts/add-image.mjs",
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui"
   },
@@ -40,10 +42,17 @@
     "react-masonry-css": "^1.0.16",
     "react-player": "^2.14.1",
     "react-syntax-highlighter": "^15.5.0",
-    "remark": "^14.0.0",
-    "remark-html": "^15.0.0",
+    "rehype-pretty-code": "^0.14.5",
+    "rehype-stringify": "^10.0.1",
+    "remark-directive": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "shiki": "^4.4.3",
     "swiper": "^11.2.6",
-    "tailwindcss": "^4.2.1"
+    "tailwindcss": "^4.2.1",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0"
   },
   "devDependencies": {
     "@playwright/test": "1.60.0",

scripts/add-image.mjs

+#!/usr/bin/env node
+// Copy an image into a post's asset folder and print the markdown snippet.
+// Usage: node scripts/add-image.mjs <slug> <file> [alt]   (or `yarn post:image <slug> <file>`)
+import fs from 'node:fs';
+import path from 'node:path';
+
+const [slug, file, alt = ''] = process.argv.slice(2);
+if (!slug || !file) {
+  console.error('Usage: node scripts/add-image.mjs <slug> <file> [alt]');
+  process.exit(1);
+}
+
+const src = path.resolve(process.cwd(), file);
+if (!fs.existsSync(src) || !fs.statSync(src).isFile()) {
+  console.error(`No such file: ${src}`);
+  process.exit(1);
+}
+
+const dir = path.join(process.cwd(), 'public/images/blog', slug);
+fs.mkdirSync(dir, { recursive: true });
+const name = path.basename(src);
+fs.copyFileSync(src, path.join(dir, name));
+
+console.log(`![${alt}](/images/blog/${slug}/${name})`);

scripts/new-post.mjs

+#!/usr/bin/env node
+// Scaffold a blog post. Usage: node scripts/new-post.mjs <slug>  (or `yarn post <slug>`).
+import fs from 'node:fs';
+import path from 'node:path';
+
+const slug = process.argv[2];
+if (!slug || /[^a-z0-9-]/i.test(slug)) {
+  console.error('Usage: node scripts/new-post.mjs <slug>   (kebab-case: letters, digits, dashes)');
+  process.exit(1);
+}
+
+const date = new Date().toISOString().slice(0, 10);
+const file = path.join(process.cwd(), 'content/blog', `${date}-${slug}.md`);
+
+if (fs.existsSync(file)) {
+  console.error(`Already exists: ${file}`);
+  process.exit(1);
+}
+
+const title = slug
+  .split('-')
+  .map((word) => (word ? word[0].toUpperCase() + word.slice(1) : word))
+  .join(' ');
+
+fs.writeFileSync(
+  file,
+  `---
+title: ${title}
+date: '${date}'
+slug: ${slug}
+draft: true
+description: ''
+tags: []
+---
+
+Start typing here.
+`,
+);
+
+console.log(file);

tests/e2e/smoke.spec.ts

@@ -22,7 +22,7 @@ const ROUTES: string[] = [
   '/talks',
   '/poesie',
   '/poesie/berg',
-  '/post/hello-world',
+  '/blog/hello-world-again',
   '/hydra',
   '/hydra/adenora',
   '/starry-nights',