@softure-ai/blog 0.1.5 → 0.1.7

package/src/options.ts

@@ -50,8 +50,12 @@ function isFieldsSchema(value: unknown): value is BlogFieldsSchema {
 
 function isBlockPlugin(value: unknown): value is BlockPlugin {
   if (typeof value !== "object" || value === null) return false;
-  const candidate = value as { type?: unknown; render?: unknown };
-  return typeof candidate.type === "string" && KEBAB.test(candidate.type) && typeof candidate.render === "function";
+  const candidate = value as { type?: unknown; syntax?: unknown; render?: unknown; markdown?: unknown };
+  return (
+    typeof candidate.type === "string" && KEBAB.test(candidate.type) && typeof candidate.render === "function" &&
+    (candidate.syntax === undefined || candidate.syntax === "fence" || candidate.syntax === "directive") &&
+    (candidate.markdown === undefined || typeof candidate.markdown === "function")
+  );
 }
 
 /** How long the pages cache their reads by default, in seconds; the app's `revalidate` should match. */

package/src/pages/accept.ts

@@ -0,0 +1,39 @@
+// Content negotiation for the Markdown representation: which requests ask for Markdown.
+
+interface MediaRange {
+  readonly type: string;
+  readonly subtype: string;
+  readonly q: number;
+}
+
+function parseAccept(accept: string): MediaRange[] {
+  return accept.split(",").flatMap((part) => {
+    const [range = "", ...params] = part.trim().toLowerCase().split(";");
+    const [type, subtype] = range.trim().split("/");
+    if (type === undefined || type === "" || subtype === undefined || subtype === "") return [];
+    const qParam = params.map((param) => param.trim()).find((param) => param.startsWith("q="));
+    const q = qParam === undefined ? 1 : Number(qParam.slice(2));
+    return Number.isFinite(q) ? [{ type, subtype, q }] : [];
+  });
+}
+
+/** The weight of a type by the most specific matching range (RFC 9110 §12.5.1); 0 without a match. */
+function getQuality(ranges: readonly MediaRange[], type: string, subtype: string): number {
+  const exact = ranges.find((range) => range.type === type && range.subtype === subtype);
+  const group = ranges.find((range) => range.type === type && range.subtype === "*");
+  const any = ranges.find((range) => range.type === "*" && range.subtype === "*");
+  return (exact ?? group ?? any)?.q ?? 0;
+}
+
+/**
+ * Whether an `Accept` header asks for Markdown rather than HTML. `text/markdown` must be named: `*\/*`
+ * (curl, most crawlers, browser prefetches) matches Markdown as well as HTML, and they want the page.
+ * A tie goes to Markdown: a client that names it next to HTML with the same weight is an agent.
+ */
+export function prefersMarkdown(accept: string | null): boolean {
+  if (accept === null) return false;
+  const ranges = parseAccept(accept);
+  const markdown = ranges.find((range) => range.type === "text" && range.subtype === "markdown");
+  if (markdown === undefined || markdown.q <= 0) return false;
+  return markdown.q >= getQuality(ranges, "text", "html");
+}

package/src/proxy/index.ts

@@ -8,12 +8,21 @@
 //   }
 //
 // Next 16 runs `proxy.ts` on Node.js, so the database handle is the process-wide one.
+//
+// `createBlogMarkdown` answers an article or term page asked for with `Accept: text/markdown` with the
+// text as Markdown; put it before the redirects so a moved or withdrawn text still answers as before:
+//
+//   return (await blogMarkdown(request)) ?? (await blogRedirects(request)) ?? …
 import { systemClock, type SoftureConfig } from "@softure-ai/core";
-import { getSharedDatabase } from "@softure-ai/db";
-import { findArticleBySlug, findSlugRedirect, type BlogContext } from "../db/articles.js";
+import { getConfiguredDatabase } from "@softure-ai/db";
+import { findArticleBySlug, findSlugRedirect, getPublishedArticle, type BlogContext } from "../db/articles.js";
+import { prefersMarkdown } from "../pages/accept.js";
+import { toArticleMarkdown } from "../render/article-markdown.js";
 import { matchBlogPath } from "../pages/paths.js";
 import { buildGonePage, createCachedBlogPathDecider, type BlogPathLookup, type CachedDeciderOptions } from "../pages/redirects.js";
-import { getBlogMessages, getBlogReservedSlugs, getBlogRoutes } from "../server/options.js";
+import { getBlogMessages, getBlogOptions, getBlogReservedSlugs, getBlogRoutes } from "../server/options.js";
+
+export { prefersMarkdown };
 
 export type BlogRedirects = (request: Request) => Promise<Response | null>;
 
@@ -25,7 +34,7 @@ export interface BlogRedirectsOptions extends CachedDeciderOptions {
 function createDefaultContext(config: SoftureConfig): () => Promise<BlogContext> {
   return async () => {
     if (config.database === null) throw new Error("@softure-ai/blog: softure.config.ts has no database; the blog needs one");
-    const { db } = await getSharedDatabase(config.database.url);
+    const { db } = await getConfiguredDatabase(config.database);
     return { db, clock: systemClock, config };
   };
 }
@@ -64,3 +73,52 @@ export function createBlogRedirects(config: SoftureConfig, options: BlogRedirect
     return null;
   };
 }
+
+export type BlogMarkdown = (request: Request) => Promise<Response | null>;
+
+export interface BlogMarkdownOptions {
+  /** The store's context; the shared database handle of `config.database` by default (tests pass PGlite). */
+  readonly getContext?: () => Promise<BlogContext>;
+  /** Where a failed read is reported; `console.error` by default. The request then goes on to the page. */
+  readonly onError?: (message: string) => void;
+}
+
+const MARKDOWN_HEADERS = {
+  "content-type": "text/markdown; charset=utf-8",
+  // One address, two representations. `private`: a shared cache must not hand Markdown to a browser.
+  vary: "Accept",
+  "cache-control": "private, max-age=0, must-revalidate",
+};
+
+/**
+ * Answers a GET or HEAD of a published article or term whose `Accept` asks for Markdown
+ * (`prefersMarkdown`) with the text as Markdown (`toArticleMarkdown`, the app's block plugins giving
+ * their Markdown form). `null` for everything else, and when the read fails: the page answers then.
+ */
+export function createBlogMarkdown(config: SoftureConfig, options: BlogMarkdownOptions = {}): BlogMarkdown {
+  const routes = getBlogRoutes(config);
+  const reservedSlugs = getBlogReservedSlugs(config);
+  const getContext = options.getContext ?? createDefaultContext(config);
+  const onError = options.onError ?? ((message: string) => console.error(message));
+  const { blocks } = getBlogOptions(config);
+  const messages = getBlogMessages(config).pages;
+
+  return async (request) => {
+    if (request.method !== "GET" && request.method !== "HEAD") return null;
+    if (!prefersMarkdown(request.headers.get("accept"))) return null;
+    const url = new URL(request.url);
+    const match = matchBlogPath(url.pathname, routes, reservedSlugs);
+    if (match === null) return null;
+    let article;
+    try {
+      article = await getPublishedArticle(await getContext(), match.slug);
+    } catch (error) {
+      onError(`@softure-ai/blog: reading ${url.pathname} as Markdown failed: ${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
+    if (article?.kind !== match.kind) return null;
+    const body = toArticleMarkdown(article, { blocks, messages });
+    const headers = { ...MARKDOWN_HEADERS, "x-markdown-tokens": String(Math.ceil(body.length / 4)) };
+    return new Response(request.method === "HEAD" ? null : body, { status: 200, headers });
+  };
+}

package/src/quality/catalog.ts

@@ -75,7 +75,10 @@ export function listQualityRules(settings: QualitySettings): QualityCatalogRule[
     ...ruleset.patterns.map((pattern) => rule("style", pattern.id, pattern.severity, pattern.message)),
     ...settings.voicePatterns.map((pattern) => rule("voice", pattern.id, pattern.severity, pattern.message)),
     ...(options.ymyl === null ? [] : YMYL_RULES),
-    ...(options.blocks.length === 0 ? [] : [rule("structure", "block-requires", "error", "a block plugin's fenced block has the frontmatter keys it requires")]),
+    ...(options.blocks.length === 0 ? [] : [rule("structure", "block-requires", "error", "a block plugin's block has the frontmatter keys it requires")]),
+    ...(options.blocks.some((plugin) => plugin.syntax === "directive")
+      ? [rule("structure", "block-directive", "error", "a ::directive line names a directive the blog renders, with readable key=\"value\" attributes")]
+      : []),
     ...(options.plugins.length === 0 ? [] : PLUGIN_RULES),
     ...options.plugins.flatMap((plugin) => plugin.rules.map((info) => rule("plugin", info.id, info.severity, info.description))),
   ];

package/src/quality/check-article.ts

@@ -8,7 +8,7 @@ import { parseArticleFile, type ParseArticleFileOptions } from "../content/artic
 import { splitArticleBody, splitBlocks } from "./blocks.js";
 import { sortFindings, type QualityFinding } from "./finding.js";
 import type { QualityPlugin } from "./plugin.js";
-import { checkBlockRequires } from "./rules/blocks.js";
+import { checkBlockRequires, checkDirectives } from "./rules/blocks.js";
 import { checkImages } from "./rules/images.js";
 import type { RuleInput } from "./rules/input.js";
 import { checkLinks, collectLinks, type InternalLinkResolver } from "./rules/links.js";
@@ -58,6 +58,7 @@ export function checkArticle(input: CheckArticleInput): QualityCheckResult {
     ...checkStyle(ruleInput),
     ...checkRhythm(ruleInput),
     ...checkBlockRequires(article, pluginBlocks),
+    ...checkDirectives(blocks, pluginBlocks, settings.options.blocks),
     ...checkImages(images, settings.images),
   ];
   const fromPlugins = settings.options.plugins.flatMap((plugin) => runPlugin(plugin, { article, blocks, pluginBlocks, today, ruleset: settings.ruleset }));

package/src/quality/options.ts

@@ -9,8 +9,12 @@ const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 
 function isBlockPlugin(value: unknown): value is BlockPlugin {
   if (typeof value !== "object" || value === null) return false;
-  const candidate = value as { type?: unknown; render?: unknown };
-  return typeof candidate.type === "string" && typeof candidate.render === "function";
+  const candidate = value as { type?: unknown; syntax?: unknown; render?: unknown; markdown?: unknown };
+  return (
+    typeof candidate.type === "string" && typeof candidate.render === "function" &&
+    (candidate.syntax === undefined || candidate.syntax === "fence" || candidate.syntax === "directive") &&
+    (candidate.markdown === undefined || typeof candidate.markdown === "function")
+  );
 }
 
 const range = (min: number, max: number) =>

package/src/quality/rules/blocks.ts

@@ -1,7 +1,8 @@
 // Block plugin needs (BL-3): a fenced block of a block plugin reads frontmatter keys (`requires`), and
 // an article that lacks one would render the block without its data.
 import type { BlogArticleInput } from "../../contract.js";
-import type { FoundBlock } from "../../render/render-article.js";
+import { parseDirectiveLine, type BlockPlugin, type FoundBlock } from "../../render/render-article.js";
+import type { Block } from "../blocks.js";
 import type { QualityFinding } from "../finding.js";
 
 export function checkBlockRequires(article: BlogArticleInput, pluginBlocks: readonly FoundBlock[]): QualityFinding[] {
@@ -41,3 +42,27 @@ function hasFrontmatterKey(article: BlogArticleInput, key: string): boolean {
       return article.fields[key] !== undefined;
   }
 }
+
+/**
+ * Directive lines the renderer would not turn into a block (BL-6 for directives): a name no directive
+ * plugin renders (it would show as a paragraph `::chrat{…}`), or attributes it cannot read. Checked
+ * only when the app registers a directive plugin; otherwise `::` lines are the app's own business.
+ */
+export function checkDirectives(blocks: readonly Block[], pluginBlocks: readonly FoundBlock[], plugins: readonly BlockPlugin[]): QualityFinding[] {
+  const names = plugins.filter((plugin) => plugin.syntax === "directive").map((plugin) => plugin.type);
+  if (names.length === 0) return [];
+  const unknown = blocks.flatMap((block) => {
+    if (block.kind !== "directive") return [];
+    const directive = parseDirectiveLine(block.text);
+    if (directive === null || names.includes(directive.name)) return [];
+    return [finding(`::${directive.name} is not a directive this blog renders; use one of: ${names.join(", ")}`, block.line)];
+  });
+  const unreadable = pluginBlocks
+    .filter((block) => block.syntax === "directive" && block.attributes === null)
+    .map((block) => finding(`the attributes of ::${block.type} cannot be read; write them as key="value" pairs, each key once`, block.line));
+  return [...unknown, ...unreadable].sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
+}
+
+function finding(message: string, line: number): QualityFinding {
+  return { rule: "block-directive", severity: "error", message, line };
+}

package/src/render/article-markdown.ts

@@ -0,0 +1,34 @@
+// An article or term as Markdown for agents (`Accept: text/markdown`): the stored Markdown in a frame
+// that carries what the HTML page shows around it (title, description, the day the facts were checked,
+// the summary, sources and FAQ). Exact by construction: no HTML round trip.
+import type { BlogArticle } from "../contract.js";
+import { en } from "../messages/en.js";
+import { replaceArticleBlocks, type BlockPlugin } from "./render-article.js";
+
+export type ArticleMarkdownInput = Pick<BlogArticle, "title" | "description" | "summary" | "bodyMarkdown" | "sources" | "faq" | "currentAsOf" | "fields">;
+
+export interface ArticleMarkdownOptions {
+  /** The app's block plugins; a block whose plugin has `markdown` is replaced by its output. */
+  readonly blocks?: readonly BlockPlugin[];
+  /** The pages' copy for the frame's labels; English by default. */
+  readonly messages?: Pick<(typeof en)["pages"], "summary" | "sources" | "faq" | "currentAsOf">;
+}
+
+export function toArticleMarkdown(article: ArticleMarkdownInput, options: ArticleMarkdownOptions = {}): string {
+  const messages = options.messages ?? en.pages;
+  const body = replaceArticleBlocks(article.bodyMarkdown.trim(), options.blocks ?? [], { currentAsOf: article.currentAsOf, fields: article.fields });
+  const parts = [`# ${article.title}`, article.description, `${messages.currentAsOf}: ${article.currentAsOf}`];
+  if (article.summary !== null) parts.push(`> **${messages.summary}:** ${article.summary}`);
+  parts.push(body);
+  if (article.sources.length > 0) {
+    parts.push(`## ${messages.sources}`, article.sources.map((source) => `- [${escapeLinkText(source.name)}](${source.url})`).join("\n"));
+  }
+  if (article.faq.length > 0) {
+    parts.push(`## ${messages.faq}`, ...article.faq.flatMap((entry) => [`### ${entry.question}`, entry.answer]));
+  }
+  return `${parts.join("\n\n")}\n`;
+}
+
+function escapeLinkText(text: string): string {
+  return text.replace(/[[\]\\]/g, (char) => `\\${char}`);
+}

package/src/render/index.ts

@@ -11,11 +11,17 @@ export {
   type ImageProblem,
   type ImageVerdict,
 } from "./images.js";
+export { toArticleMarkdown, type ArticleMarkdownInput, type ArticleMarkdownOptions } from "./article-markdown.js";
 export { DEFAULT_WORDS_PER_MINUTE, getReadingMinutes } from "./reading-time.js";
 export {
   findArticleBlocks,
+  parseDirectiveAttributes,
+  parseDirectiveLine,
   renderArticle,
+  replaceArticleBlocks,
   type ArticleBlock,
+  type BlockAttributes,
+  type BlockSyntax,
   type ArticleHeading,
   type ArticleSegment,
   type BlockArticle,

package/src/render/render-article.ts

@@ -36,6 +36,10 @@
 // A fenced block whose type an app registers (```` ```chart ````) is rendered by the app's plugin, as
 // HTML or as a node (e.g. a React server component). Plugin output is the app's own code and is
 // trusted as is. Only top-level fences are plugin blocks; a fence inside a list or a quote stays code.
+//
+// A plugin with `syntax: "directive"` renders a leaf directive instead: a line of its own,
+// `::chart{type="wealth" scenario="…"}` (braces optional), with double-quoted values and each key
+// once. Like fences, only top-level lines count; a directive in a list, a quote or code stays text.
 import MarkdownIt, { type MarkdownIt as Markdown, type StateCore, type Token } from "markdown-it";
 import footnote from "markdown-it-footnote";
 import type { BlogFields } from "../contract.js";
@@ -61,12 +65,24 @@ export interface BlockArticle {
   readonly fields?: BlogFields;
 }
 
+/** How a block is written: a fence (```` ```chart ````) or a leaf directive (`::chart{…}`). */
+export type BlockSyntax = "fence" | "directive";
+
+/** A directive's attributes, or `null` when its braces cannot be read. Always `{}` for a fence. */
+export type BlockAttributes = Readonly<Record<string, string>> | null;
+
 export interface ArticleBlock {
-  /** The block type, the first word of the fence's info string. */
+  /** The block type: the first word of the fence's info string, or the directive's name. */
   readonly type: string;
-  /** The rest of the info string, trimmed: ```` ```chart wealth ```` → `"wealth"`. */
+  readonly syntax: BlockSyntax;
+  /**
+   * Fence: the rest of the info string, trimmed (```` ```chart wealth ```` → `"wealth"`). Directive:
+   * the text inside the braces, trimmed.
+   */
   readonly info: string;
-  /** The body of the fence, as written. */
+  /** `key="value"` pairs of a directive; `{}` for a fence. */
+  readonly attributes: BlockAttributes;
+  /** Fence: its body, as written. Directive: the whole line, trimmed. */
   readonly content: string;
   readonly article: BlockArticle;
 }
@@ -78,6 +94,8 @@ export type BlockOutput<TNode = unknown> =
 export interface BlockPlugin<TNode = unknown> {
   /** Lower-case kebab-case, e.g. `chart`. */
   readonly type: string;
+  /** Which blocks the plugin renders: fences (the default) or leaf directives. */
+  readonly syntax?: BlockSyntax;
   /**
    * The frontmatter keys the block reads (`current_as_of` or keys of the app's `fields`), so the
    * quality gate can report a block whose article lacks them.
@@ -85,6 +103,11 @@ export interface BlockPlugin<TNode = unknown> {
   readonly requires?: readonly string[];
   /** Throws only on a bug; a block that cannot render returns its own error markup. */
   readonly render: (block: ArticleBlock) => BlockOutput<TNode>;
+  /**
+   * The block as Markdown for agents (`toArticleMarkdown`, `Accept: text/markdown`): a table or a
+   * sentence. Without it the block's source stays in the Markdown.
+   */
+  readonly markdown?: (block: ArticleBlock) => string;
 }
 
 export type ArticleSegment<TNode = unknown> =
@@ -127,8 +150,10 @@ export interface RenderedArticle<TNode = unknown> {
 
 export interface FoundBlock {
   readonly type: string;
+  readonly syntax: BlockSyntax;
   readonly info: string;
-  /** 1-based line of the opening fence. */
+  readonly attributes: BlockAttributes;
+  /** 1-based line of the opening fence or of the directive. */
   readonly line: number;
   readonly requires: readonly string[];
 }
@@ -141,6 +166,61 @@ const FOOTNOTES_HEADING_ID = "footnotes";
 // Ids the renderer gives footnotes; a heading whose slug equals one of them gets a suffix.
 const FOOTNOTE_ID = /^(?:footnotes|fn(?:ref)?-\d+(?:-\d+)?)$/;
 const BLOCK_TOKEN = "blog_block";
+const DIRECTIVE_LINE = /^::([a-z][a-z0-9]*(?:-[a-z0-9]+)*)(?:\{(.*)\})?$/;
+const DIRECTIVE_START = /^::[a-z]/;
+const ATTRIBUTE_KEY_START = /[a-z]/;
+const ATTRIBUTE_KEY_CHAR = /[a-z0-9_-]/;
+const WHITESPACE = /\s/;
+
+interface BlockMeta {
+  readonly type: string;
+  readonly syntax: BlockSyntax;
+  readonly info: string;
+  readonly attributes: BlockAttributes;
+}
+
+/** The `key="value"` pairs inside a directive's braces; `null` when anything else is there or a key repeats. */
+export function parseDirectiveAttributes(text: string): BlockAttributes {
+  // A hand scanner, linear in the text: a regex here runs on author input and backtracks on long runs.
+  const attributes: Record<string, string> = {};
+  let index = 0;
+  const skipWhitespace = (): void => {
+    while (index < text.length && WHITESPACE.test(text.charAt(index))) index += 1;
+  };
+  skipWhitespace();
+  while (index < text.length) {
+    if (!ATTRIBUTE_KEY_START.test(text.charAt(index))) return null;
+    const keyStart = index;
+    while (index < text.length && ATTRIBUTE_KEY_CHAR.test(text.charAt(index))) index += 1;
+    const key = text.slice(keyStart, index);
+    if (text.charAt(index) !== "=" || text.charAt(index + 1) !== '"') return null;
+    const valueEnd = text.indexOf('"', index + 2);
+    if (valueEnd === -1) return null;
+    if (Object.hasOwn(attributes, key)) return null;
+    attributes[key] = text.slice(index + 2, valueEnd);
+    index = valueEnd + 1;
+    skipWhitespace();
+  }
+  return attributes;
+}
+
+/**
+ * A line read as a leaf directive: its name, the text inside the braces and the attributes. `null`
+ * for a line that is not one (a name must follow `::`); a directive whose braces do not close keeps
+ * its name and gets `null` attributes.
+ */
+export function parseDirectiveLine(line: string): { readonly name: string; readonly info: string; readonly attributes: BlockAttributes } | null {
+  const trimmed = line.trim();
+  if (!DIRECTIVE_START.test(trimmed)) return null;
+  const match = DIRECTIVE_LINE.exec(trimmed);
+  if (match === null) {
+    const name = /^::([a-z][a-z0-9-]*)/.exec(trimmed)?.[1] ?? "";
+    const rest = trimmed.slice(2 + name.length).trim();
+    return { name, info: rest.replace(/^\{/, "").trim(), attributes: null };
+  }
+  const info = (match[2] ?? "").trim();
+  return { name: match[1] ?? "", info, attributes: parseDirectiveAttributes(info) };
+}
 
 function getDefaultTermHref(slug: string): string {
   return `/blog/glossary/${slug}`;
@@ -354,26 +434,77 @@ function addBlockTokens(md: Markdown, types: ReadonlySet<string>): void {
       const [type = "", ...rest] = token.info.trim().split(/\s+/);
       if (!types.has(type)) continue;
       token.type = BLOCK_TOKEN;
-      token.meta = { type, info: rest.join(" ") };
+      const meta: BlockMeta = { type, syntax: "fence", info: rest.join(" "), attributes: {} };
+      token.meta = { block: meta };
     }
   });
 }
 
-function getPluginsByType<TNode>(plugins: readonly BlockPlugin<TNode>[]): Map<string, BlockPlugin<TNode>> {
-  const byType = new Map<string, BlockPlugin<TNode>>();
+/**
+ * A block rule for top-level lines `::name{…}` of registered directive names. Before `paragraph`
+ * and allowed to end one, so a directive right under a paragraph line is still a block.
+ */
+function addDirectiveRule(md: Markdown, names: ReadonlySet<string>): void {
+  if (names.size === 0) return;
+  md.block.ruler.before(
+    "paragraph",
+    "blog_directive",
+    (state, startLine, _endLine, silent) => {
+      // Four spaces are an indented code block; a nested block (list, quote) is not top level.
+      if (state.level !== 0 || state.blkIndent !== 0 || (state.sCount[startLine] ?? 0) - state.blkIndent >= 4) return false;
+      const line = state.src.slice((state.bMarks[startLine] ?? 0) + (state.tShift[startLine] ?? 0), state.eMarks[startLine]);
+      const directive = parseDirectiveLine(line);
+      if (directive === null || !names.has(directive.name)) return false;
+      if (!silent) {
+        const token = state.push(BLOCK_TOKEN, "", 0);
+        token.block = true;
+        token.content = line.trim();
+        token.map = [startLine, startLine + 1];
+        const meta: BlockMeta = { type: directive.name, syntax: "directive", info: directive.info, attributes: directive.attributes };
+        token.meta = { block: meta };
+      }
+      state.line = startLine + 1;
+      return true;
+    },
+    { alt: ["paragraph"] },
+  );
+}
+
+/** The block a `blog_block` token stands for; set by `addBlockTokens` and `addDirectiveRule`. */
+function readBlockMeta(token: Token): BlockMeta {
+  return (token.meta as { block: BlockMeta }).block;
+}
+
+/** Plugins by `syntax:type`. */
+type PluginRegistry<TNode> = Map<string, BlockPlugin<TNode>>;
+
+function getPluginKey(syntax: BlockSyntax, type: string): string {
+  return `${syntax}:${type}`;
+}
+
+function getPluginsByType<TNode>(plugins: readonly BlockPlugin<TNode>[]): PluginRegistry<TNode> {
+  const byType: PluginRegistry<TNode> = new Map();
   for (const plugin of plugins) {
     if (!BLOCK_TYPE.test(plugin.type)) {
       throw new Error(`Block plugin type "${plugin.type}" must be lower-case kebab-case, e.g. "chart".`);
     }
-    if (byType.has(plugin.type)) throw new Error(`Block plugin type "${plugin.type}" is registered twice.`);
-    byType.set(plugin.type, plugin);
+    const syntax = plugin.syntax ?? "fence";
+    const key = getPluginKey(syntax, plugin.type);
+    if (byType.has(key)) {
+      throw new Error(syntax === "fence" ? `Block plugin type "${plugin.type}" is registered twice.` : `Block plugin type "${plugin.type}" (directive) is registered twice.`);
+    }
+    byType.set(key, plugin);
   }
   return byType;
 }
 
+function getTypes<TNode>(plugins: PluginRegistry<TNode>, syntax: BlockSyntax): Set<string> {
+  return new Set([...plugins.values()].filter((plugin) => (plugin.syntax ?? "fence") === syntax).map((plugin) => plugin.type));
+}
+
 function createMarkdown<TNode>(
   options: RenderArticleOptions<TNode>,
-  plugins: ReadonlyMap<string, BlockPlugin<TNode>>,
+  plugins: PluginRegistry<TNode>,
   state: RenderState,
 ): Markdown {
   const messages = options.messages ?? en.render;
@@ -383,7 +514,8 @@ function createMarkdown<TNode>(
   addImages(md, options.images);
   addFootnoteMarkup(md, messages);
   addExternalLinks(md, options.siteHosts ?? [], messages);
-  addBlockTokens(md, new Set(plugins.keys()));
+  addBlockTokens(md, getTypes(plugins, "fence"));
+  addDirectiveRule(md, getTypes(plugins, "directive"));
   addHeadingIds(md, state);
   addGlossaryLinks(
     md,
@@ -442,10 +574,10 @@ export function renderArticle<TNode = unknown>(markdown: string, options: Render
     if (token.type !== BLOCK_TOKEN) return;
     addHtmlSegment(segments, md.renderer.render(tokens.slice(start, index), md.options, env));
     start = index + 1;
-    const meta = token.meta as { type: string; info: string };
-    const plugin = plugins.get(meta.type);
+    const meta = readBlockMeta(token);
+    const plugin = plugins.get(getPluginKey(meta.syntax, meta.type));
     if (plugin === undefined) return;
-    const output = plugin.render({ type: meta.type, info: meta.info, content: token.content, article: options.article ?? {} });
+    const output = plugin.render({ ...meta, content: token.content, article: options.article ?? {} });
     if (output.kind === "html") {
       addHtmlSegment(segments, output.html);
     } else {
@@ -481,7 +613,29 @@ export function findArticleBlocks(markdown: string, plugins: readonly BlockPlugi
   const md = createMarkdown({ blocks: plugins }, byType, { headings: [], linkedTerms: [] });
   return md.parse(markdown, {}).flatMap((token) => {
     if (token.type !== BLOCK_TOKEN) return [];
-    const meta = token.meta as { type: string; info: string };
-    return [{ type: meta.type, info: meta.info, line: (token.map?.[0] ?? 0) + 1, requires: byType.get(meta.type)?.requires ?? [] }];
+    const meta = readBlockMeta(token);
+    const requires = byType.get(getPluginKey(meta.syntax, meta.type))?.requires ?? [];
+    return [{ type: meta.type, syntax: meta.syntax, info: meta.info, attributes: meta.attributes, line: (token.map?.[0] ?? 0) + 1, requires }];
   });
 }
+
+/**
+ * The text with each plugin block that has a Markdown form (`BlockPlugin.markdown`) replaced by it;
+ * other blocks keep their source. For agents that read the article as Markdown.
+ */
+export function replaceArticleBlocks(markdown: string, plugins: readonly BlockPlugin[], article: BlockArticle = {}): string {
+  if (!plugins.some((plugin) => plugin.markdown !== undefined)) return markdown;
+  const byType = getPluginsByType(plugins);
+  const md = createMarkdown({ blocks: plugins }, byType, { headings: [], linkedTerms: [] });
+  const lines = markdown.split("\n");
+  const blocks = md.parse(markdown, {}).filter((token) => token.type === BLOCK_TOKEN && token.map !== null);
+  for (const token of blocks.reverse()) {
+    const meta = readBlockMeta(token);
+    const plugin = byType.get(getPluginKey(meta.syntax, meta.type));
+    const [start = 0, end = start] = token.map ?? [];
+    if (plugin?.markdown === undefined) continue;
+    const replacement = plugin.markdown({ ...meta, content: token.content, article });
+    lines.splice(start, end - start, ...replacement.split("\n"));
+  }
+  return lines.join("\n");
+}

package/src/server/index.ts

@@ -10,7 +10,9 @@ export {
   publishArticle,
   type BlogContext,
   type ListArticlesFilter,
+  type PublishArticleOptions,
 } from "../db/articles.js";
+export { articleHistorySchema, parseArticleHistory, type ArticleHistory, type ArticleHistoryMap } from "../db/history.js";
 export {
   runBlogPublish,
   type ArticleFile,

package/src/sitemap.ts

@@ -4,7 +4,7 @@
 // one query on the shared database, not from the pages' Next cache. Crawlers read a sitemap rarely.
 import { systemClock, type SoftureConfig } from "@softure-ai/core";
 import { getSoftureConfig } from "@softure-ai/core/next";
-import { getSharedDatabase } from "@softure-ai/db";
+import { getConfiguredDatabase } from "@softure-ai/db";
 import { listArticles } from "./db/articles.js";
 import { getBlogSitemapEntries, type BlogSitemapEntry } from "./discovery/sitemap.js";
 import { getBlogOptions, getBlogRoutes } from "./server/options.js";
@@ -15,7 +15,7 @@ export async function readBlogSitemap(config: SoftureConfig): Promise<BlogSitema
     // Unreachable for a validated config: the module has a database schema.
     throw new Error("@softure-ai/blog: softure.config.ts has no database; the blog sitemap needs one");
   }
-  const { db } = await getSharedDatabase(config.database.url);
+  const { db } = await getConfiguredDatabase(config.database);
   const texts = await listArticles({ db, clock: systemClock, config });
   const routes = getBlogRoutes(config);
   return getBlogSitemapEntries({