@kenjura/ursa 0.84.0 → 0.86.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+# 0.86.0
+2026-05-18
+
+- small CSS fix
+
+# 0.85.0
+2026-05-15
+
+- deflists in MDX
+
+
 # 0.84.0
 2026-05-08
 

package/bin/ursa.js

@@ -6,6 +6,7 @@ import { generate } from '../src/jobs/generate.js';
 import { resolve, dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { stagePromotedChangelog, registerCleanupOnExit } from '../src/helper/promoteChangelog.js';
+import { instantiateTemplate } from '../src/helper/documentTemplates.js';
 
 // Get the directory where ursa is installed
 const __filename = fileURLToPath(import.meta.url);
@@ -14,7 +15,7 @@ const PACKAGE_META = join(__dirname, '..', 'meta');
 
 yargs(hideBin(process.argv))
   .command(
-    'generate <source>',
+    ['generate <source>', '$0 <source>'],
     'Generate a static site from source files',
     (yargs) => {
       return yargs
@@ -235,54 +236,40 @@ yargs(hideBin(process.argv))
     }
   )
   .command(
-    '$0 <source>',
-    'Generate a static site from source files (default command)',
+    'template <source> <templatePath> <destination>',
+    'Create a new document from a document template',
     (yargs) => {
       return yargs
         .positional('source', {
-          describe: 'Source directory containing markdown/wikitext files',
+          describe: 'Source directory (docroot) of the Ursa site',
           type: 'string',
           demandOption: true
         })
-        .option('meta', {
-          alias: 'm',
-          default: 'meta',
-          describe: 'Meta directory containing templates and styles',
-          type: 'string'
-        })
-        .option('output', {
-          alias: 'o', 
-          default: 'output',
-          describe: 'Output directory for generated site',
-          type: 'string'
+        .positional('templatePath', {
+          describe: 'Path to the template file (relative to source, e.g. _templates/city.md)',
+          type: 'string',
+          demandOption: true
         })
-        .option('whitelist', {
-          alias: 'w',
-          describe: 'Path to whitelist file containing patterns for files to include',
-          type: 'string'
+        .positional('destination', {
+          describe: 'Path for the new document (relative to source, e.g. places/springfield.md)',
+          type: 'string',
+          demandOption: true
         });
     },
     async (argv) => {
       const source = resolve(argv.source);
-      const meta = resolve(argv.meta);
-      const output = resolve(argv.output);
-      const whitelist = argv.whitelist ? resolve(argv.whitelist) : null;
-      
-      console.log(`Generating site from ${source} to ${output} using meta from ${meta}`);
-      if (whitelist) {
-        console.log(`Using whitelist: ${whitelist}`);
-      }
-      
+      const templateAbsPath = resolve(source, argv.templatePath);
+      const destAbsPath = resolve(source, argv.destination);
+
       try {
-        await generate({
-          _source: source,
-          _meta: meta,
-          _output: output,
-          _whitelist: whitelist
-        });
-        console.log('Site generation completed successfully!');
+        const { templateRelPath, destRelPath } = await instantiateTemplate(
+          templateAbsPath,
+          destAbsPath,
+          source
+        );
+        console.log(`✅ Created ${destRelPath} from template ${templateRelPath}`);
       } catch (error) {
-        console.error('Error generating site:', error.message);
+        console.error(`Error creating template instance: ${error.message}`);
         process.exit(1);
       }
     }

package/meta/templates/default-template/default.css

@@ -50,6 +50,26 @@ h1 {
   text-overflow: ellipsis;
 }
 
+h1,h2,h3 {
+  clear: both;
+}
+
+figure {
+  margin: 0.5rem 0;
+  padding: 0;
+  max-width: 300px;
+  float: left;
+  clear: both;
+  margin-right: 1.5rem;
+  margin-bottom: 0.5rem;
+
+  &:nth-of-type(even) {
+    float: right;
+    margin-left: 1.5rem;
+    margin-right: 0;
+  }
+}
+
 nav#nav-global {
   background-color: var(--nav-top-bg);
   height: var(--global-nav-height);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@kenjura/ursa",
   "author": "Andrew London <andrew@kenjura.com>",
   "type": "module",
-  "version": "0.84.0",
+  "version": "0.86.0",
   "description": "static site generator from MD/wikitext/YML",
   "main": "lib/index.js",
   "bin": {
@@ -35,6 +35,7 @@
     "markdown-it-front-matter": "^0.2.3",
     "markdown-it-sup": "^1.0.0",
     "mdx-bundler": "^10.1.1",
+    "node-diff3": "^3.2.0",
     "node-watch": "^0.7.3",
     "object-to-xml": "^2.0.0",
     "react": "^19.2.4",

package/src/dev.js

@@ -569,10 +569,12 @@ async function wrapInTemplate(body, title, fileMeta, urlPath, sourcePath, hydrat
   // Resolve relative URLs
   finalHtml = resolveRelativeUrls(finalHtml, docUrlPath);
   
-  // Mark inactive links (only if validPaths is ready)
-  if (validPaths) {
-    finalHtml = markInactiveLinks(finalHtml, validPaths, docUrlPath, false);
-  }
+  // Mark inactive links + rewrite .md/.mdx → .html. We always run this even
+  // before validPaths is ready, because the optimistic .md→.html conversion
+  // inside resolveHref does not require validPaths. Without this, links to
+  // markdown files served before background caches finish would not be
+  // rewritten and the browser would request the source .md file directly.
+  finalHtml = markInactiveLinks(finalHtml, validPaths || new Map(), docUrlPath, false);
   
   return finalHtml;
 }

package/src/helper/__test__/documentTemplates.test.js

@@ -0,0 +1,354 @@
+import { join } from 'path';
+import { mkdtemp, writeFile, readFile, mkdir, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import {
+  isInsideTemplatesFolder,
+  extractFrontmatterBlock,
+  extractBody,
+  buildFrontmatter,
+  ensureTemplateSourceFrontmatter,
+  findAllDocumentTemplates,
+  threeWayMerge,
+  instantiateTemplate,
+  reconcileDocument,
+  reconcileAll,
+  loadBaseSnapshot,
+} from '../documentTemplates.js';
+
+// Helper: create a temp directory for each test
+let tempDir;
+beforeEach(async () => {
+  tempDir = await mkdtemp(join(tmpdir(), 'ursa-doctemplate-'));
+});
+afterEach(async () => {
+  await rm(tempDir, { recursive: true, force: true });
+});
+
+// ---------------------------------------------------------------------------
+// isInsideTemplatesFolder
+// ---------------------------------------------------------------------------
+describe('isInsideTemplatesFolder', () => {
+  it('detects _templates as a path segment', () => {
+    expect(isInsideTemplatesFolder('/site/docs/_templates/city.md')).toBe(true);
+    expect(isInsideTemplatesFolder('_templates/foo.md')).toBe(true);
+    expect(isInsideTemplatesFolder('/a/b/_templates/c/d.md')).toBe(true);
+  });
+
+  it('returns false for normal paths', () => {
+    expect(isInsideTemplatesFolder('/site/docs/city.md')).toBe(false);
+    expect(isInsideTemplatesFolder('/site/my_templates/city.md')).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Frontmatter helpers
+// ---------------------------------------------------------------------------
+describe('extractFrontmatterBlock / extractBody', () => {
+  it('extracts frontmatter from a standard document', () => {
+    const content = '---\ntitle: Hello\n---\nBody here';
+    expect(extractFrontmatterBlock(content)).toBe('---\ntitle: Hello\n---\n');
+    expect(extractBody(content)).toBe('Body here');
+  });
+
+  it('returns empty string when no frontmatter', () => {
+    const content = 'Just body content';
+    expect(extractFrontmatterBlock(content)).toBe('');
+    expect(extractBody(content)).toBe('Just body content');
+  });
+});
+
+describe('buildFrontmatter', () => {
+  it('builds YAML frontmatter from an object', () => {
+    const result = buildFrontmatter({ title: 'My City', type: 'city' });
+    expect(result).toBe('---\ntitle: My City\ntype: city\n---\n');
+  });
+
+  it('returns empty string for null/empty', () => {
+    expect(buildFrontmatter(null)).toBe('');
+    expect(buildFrontmatter({})).toBe('');
+  });
+});
+
+describe('ensureTemplateSourceFrontmatter', () => {
+  it('adds frontmatter when none exists', () => {
+    const result = ensureTemplateSourceFrontmatter('Body text', '_templates/city.md');
+    expect(result).toContain('template-source: _templates/city.md');
+    expect(result).toContain('Body text');
+  });
+
+  it('inserts into existing frontmatter', () => {
+    const content = '---\ntitle: Springfield\n---\nBody';
+    const result = ensureTemplateSourceFrontmatter(content, '_templates/city.md');
+    expect(result).toContain('template-source: _templates/city.md');
+    expect(result).toContain('title: Springfield');
+    expect(result).toContain('Body');
+  });
+
+  it('updates existing template-source value', () => {
+    const content = '---\ntemplate-source: old/path.md\ntitle: X\n---\nBody';
+    const result = ensureTemplateSourceFrontmatter(content, '_templates/new.md');
+    expect(result).toContain('template-source: _templates/new.md');
+    expect(result).not.toContain('old/path.md');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Discovery
+// ---------------------------------------------------------------------------
+describe('findAllDocumentTemplates', () => {
+  it('finds .md files inside _templates folders', () => {
+    const files = [
+      '/src/docs/_templates/city.md',
+      '/src/docs/_templates/character.md',
+      '/src/docs/places/springfield.md',
+      '/src/docs/deep/path/_templates/quest.mdx',
+    ];
+    const result = findAllDocumentTemplates(files, '/src/docs/');
+    expect(result.size).toBe(3);
+    expect(result.has('_templates/city.md')).toBe(true);
+    expect(result.has('_templates/character.md')).toBe(true);
+    expect(result.has('deep/path/_templates/quest.mdx')).toBe(true);
+  });
+
+  it('ignores non-markdown files in _templates', () => {
+    const files = ['/src/_templates/style.css', '/src/_templates/image.png'];
+    const result = findAllDocumentTemplates(files, '/src/');
+    expect(result.size).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 3-way merge
+// ---------------------------------------------------------------------------
+describe('threeWayMerge', () => {
+  it('cleanly merges non-conflicting changes', () => {
+    const base   = 'line 1\nline 2\nline 3';
+    const ours   = 'line 1\nline 2 modified\nline 3';     // user edited line 2
+    const theirs = 'line 1\nline 2\nline 3\nline 4 new';  // template added line 4
+
+    const { merged, conflict } = threeWayMerge(base, ours, theirs);
+    expect(conflict).toBe(false);
+    expect(merged).toContain('line 2 modified');
+    expect(merged).toContain('line 4 new');
+  });
+
+  it('returns conflict markers when both sides edit the same line', () => {
+    const base   = 'line 1\nline 2\nline 3';
+    const ours   = 'line 1\nours version\nline 3';
+    const theirs = 'line 1\ntheirs version\nline 3';
+
+    const { merged, conflict } = threeWayMerge(base, ours, theirs);
+    expect(conflict).toBe(true);
+    expect(merged).toContain('<<<<<<<');
+    expect(merged).toContain('>>>>>>>');
+  });
+
+  it('handles identical changes on both sides (no conflict)', () => {
+    const base   = 'line 1\nline 2\nline 3';
+    const ours   = 'line 1\nline 2 same change\nline 3';
+    const theirs = 'line 1\nline 2 same change\nline 3';
+
+    const { merged, conflict } = threeWayMerge(base, ours, theirs);
+    expect(conflict).toBe(false);
+    expect(merged).toBe('line 1\nline 2 same change\nline 3');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// instantiateTemplate (filesystem)
+// ---------------------------------------------------------------------------
+describe('instantiateTemplate', () => {
+  it('creates a document from a template with template-source frontmatter', async () => {
+    // Setup: create a template file
+    const tplDir = join(tempDir, '_templates');
+    await mkdir(tplDir, { recursive: true });
+    const tplPath = join(tplDir, 'city.md');
+    await writeFile(tplPath, '---\ntype: city\n---\n# {City Name}\n\n## Geography\n');
+
+    const destPath = join(tempDir, 'places', 'springfield.md');
+    const result = await instantiateTemplate(tplPath, destPath, tempDir);
+
+    expect(result.templateRelPath).toBe('_templates/city.md');
+    expect(result.destRelPath).toBe(join('places', 'springfield.md'));
+
+    // Check the created file
+    const content = await readFile(destPath, 'utf8');
+    expect(content).toContain('template-source: _templates/city.md');
+    expect(content).toContain('type: city');
+    expect(content).toContain('# {City Name}');
+    expect(content).toContain('## Geography');
+  });
+
+  it('creates frontmatter even if the template has none', async () => {
+    const tplDir = join(tempDir, '_templates');
+    await mkdir(tplDir, { recursive: true });
+    const tplPath = join(tplDir, 'bare.md');
+    await writeFile(tplPath, '# Simple Template\n\nContent here.\n');
+
+    const destPath = join(tempDir, 'pages', 'new.md');
+    await instantiateTemplate(tplPath, destPath, tempDir);
+
+    const content = await readFile(destPath, 'utf8');
+    expect(content).toContain('---');
+    expect(content).toContain('template-source: _templates/bare.md');
+    expect(content).toContain('# Simple Template');
+  });
+
+  it('throws if destination already exists', async () => {
+    const tplDir = join(tempDir, '_templates');
+    await mkdir(tplDir, { recursive: true });
+    const tplPath = join(tplDir, 'city.md');
+    await writeFile(tplPath, '# Template');
+
+    const destPath = join(tempDir, 'existing.md');
+    await writeFile(destPath, 'already here');
+
+    await expect(instantiateTemplate(tplPath, destPath, tempDir)).rejects.toThrow(
+      /already exists/
+    );
+  });
+
+  it('saves a base snapshot for future reconciliation', async () => {
+    const tplDir = join(tempDir, '_templates');
+    await mkdir(tplDir, { recursive: true });
+    const tplPath = join(tplDir, 'city.md');
+    await writeFile(tplPath, '---\ntype: city\n---\n# {City Name}\n');
+
+    const destPath = join(tempDir, 'places', 'springfield.md');
+    const result = await instantiateTemplate(tplPath, destPath, tempDir);
+
+    const base = await loadBaseSnapshot(tempDir, result.destRelPath);
+    expect(base).toBe('# {City Name}\n');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// reconcileDocument (filesystem)
+// ---------------------------------------------------------------------------
+describe('reconcileDocument', () => {
+  it('initializes a base snapshot on first encounter', async () => {
+    // Setup: template + document that references it, but no base snapshot yet
+    const tplDir = join(tempDir, '_templates');
+    await mkdir(tplDir, { recursive: true });
+    const tplPath = join(tplDir, 'city.md');
+    await writeFile(tplPath, '# {City Name}\n\n## Geography\n');
+
+    const docPath = join(tempDir, 'springfield.md');
+    await writeFile(docPath, '---\ntemplate-source: _templates/city.md\n---\n# Springfield\n\n## Geography\nFlat plains.\n');
+
+    const result = await reconcileDocument(docPath, tplPath, tempDir);
+    expect(result.action).toBe('initialized');
+  });
+
+  it('returns "none" when template has not changed', async () => {
+    const tplDir = join(tempDir, '_templates');
+    await mkdir(tplDir, { recursive: true });
+    const tplPath = join(tplDir, 'city.md');
+    const tplBody = '# {City Name}\n\n## Geography\n';
+    await writeFile(tplPath, tplBody);
+
+    const destPath = join(tempDir, 'springfield.md');
+    // Instantiate first so base is saved
+    await instantiateTemplate(tplPath, destPath, tempDir);
+
+    // Now reconcile without changing the template
+    const result = await reconcileDocument(destPath, tplPath, tempDir);
+    expect(result.action).toBe('none');
+  });
+
+  it('auto-merges when template and document change different parts', async () => {
+    const tplDir = join(tempDir, '_templates');
+    await mkdir(tplDir, { recursive: true });
+    const tplPath = join(tplDir, 'city.md');
+    await writeFile(tplPath, '# {City Name}\n\n## Geography\n\n## History\n');
+
+    const destPath = join(tempDir, 'springfield.md');
+    await instantiateTemplate(tplPath, destPath, tempDir);
+
+    // User modifies the document (fills in Geography)
+    const docContent = await readFile(destPath, 'utf8');
+    const edited = docContent.replace('## Geography', '## Geography\nFlat plains and rivers.');
+    await writeFile(destPath, edited);
+
+    // Template adds a new section at the end
+    await writeFile(tplPath, '# {City Name}\n\n## Geography\n\n## History\n\n## Notable People\n');
+
+    const result = await reconcileDocument(destPath, tplPath, tempDir);
+    expect(result.action).toBe('updated');
+    expect(result.conflict).toBe(false);
+
+    // Verify the merged document has both changes
+    const merged = await readFile(destPath, 'utf8');
+    expect(merged).toContain('Flat plains and rivers.');
+    expect(merged).toContain('## Notable People');
+  });
+
+  it('writes conflict markers when both sides edit the same section', async () => {
+    const tplDir = join(tempDir, '_templates');
+    await mkdir(tplDir, { recursive: true });
+    const tplPath = join(tplDir, 'city.md');
+    await writeFile(tplPath, '# {City Name}\n\n## Geography\nDescribe here.\n');
+
+    const destPath = join(tempDir, 'springfield.md');
+    await instantiateTemplate(tplPath, destPath, tempDir);
+
+    // User changes "Describe here." to their own text
+    const docContent = await readFile(destPath, 'utf8');
+    await writeFile(destPath, docContent.replace('Describe here.', 'User wrote this.'));
+
+    // Template also changes "Describe here." to something else
+    await writeFile(tplPath, '# {City Name}\n\n## Geography\nTemplate says this instead.\n');
+
+    const result = await reconcileDocument(destPath, tplPath, tempDir);
+    expect(result.action).toBe('conflict');
+    expect(result.conflict).toBe(true);
+
+    const merged = await readFile(destPath, 'utf8');
+    expect(merged).toContain('<<<<<<<');
+    expect(merged).toContain('>>>>>>>');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// reconcileAll (filesystem)
+// ---------------------------------------------------------------------------
+describe('reconcileAll', () => {
+  it('reconciles multiple documents at once', async () => {
+    const tplDir = join(tempDir, '_templates');
+    await mkdir(tplDir, { recursive: true });
+    const tplPath = join(tplDir, 'city.md');
+    await writeFile(tplPath, '# {City Name}\n\n## Geography\n');
+
+    // Create two instances
+    const doc1 = join(tempDir, 'springfield.md');
+    const doc2 = join(tempDir, 'shelbyville.md');
+    await instantiateTemplate(tplPath, doc1, tempDir);
+    await instantiateTemplate(tplPath, doc2, tempDir);
+
+    // Change template
+    await writeFile(tplPath, '# {City Name}\n\n## Geography\n\n## History\n');
+
+    const allFiles = [tplPath, doc1, doc2];
+    const articlePaths = [doc1, doc2];
+
+    const summary = await reconcileAll(articlePaths, allFiles, tempDir);
+    expect(summary.updated).toBe(2);
+    expect(summary.conflicts).toBe(0);
+    expect(summary.affectedPaths.size).toBe(2);
+
+    // Verify both docs now have the new section
+    const content1 = await readFile(doc1, 'utf8');
+    const content2 = await readFile(doc2, 'utf8');
+    expect(content1).toContain('## History');
+    expect(content2).toContain('## History');
+  });
+
+  it('returns zeroes when there are no templated documents', async () => {
+    const doc = join(tempDir, 'plain.md');
+    await writeFile(doc, '# Just a regular doc');
+
+    const summary = await reconcileAll([doc], [doc], tempDir);
+    expect(summary.updated).toBe(0);
+    expect(summary.initialized).toBe(0);
+  });
+});

package/src/helper/automenu.js

@@ -449,7 +449,7 @@ function collapseSingleDocFolders(items) {
 
 export async function getAutomenu(source, validPaths) {
   const tree = dirTree(source, {
-    exclude: /[\/\\]\.|node_modules/,  // Exclude hidden folders (starting with .) and node_modules
+    exclude: /[\/\\]\.|node_modules|_templates/,  // Exclude hidden folders (starting with .), node_modules, and _templates
   });
   
   // Build menu data WITHOUT debug fields for smaller JSON

package/src/helper/documentTemplates.js

@@ -0,0 +1,454 @@
+/**
+ * Document Templates
+ *
+ * Allows users to create _templates/ folders anywhere in the docroot tree.
+ * Template .md files inside those folders serve as reusable stubs (e.g. a City
+ * page with headings and placeholder text).  An instance is a normal document
+ * whose frontmatter contains `template-source: <relative-path-to-template>`.
+ *
+ * When a template changes, Ursa performs a 3-way merge (git-style) against
+ * every instance:
+ *   base  = template body at the time the instance was last synced
+ *   ours  = current instance body (user edits)
+ *   theirs = new template body
+ *
+ * If the merge succeeds the instance is updated silently.  If it fails,
+ * git-style conflict markers are written and the user is warned.
+ *
+ * Base snapshots live in <sourceRoot>/.ursa/template-bases/ so they survive
+ * across builds.
+ */
+
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join, dirname, relative, resolve } from 'path';
+import { merge as diff3Merge } from 'node-diff3';
+import { extractMetadata } from './metadataExtractor.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const TEMPLATES_FOLDER = '_templates';
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * True when any segment of `filePath` is `_templates`.
+ * Works with both / and \ separators.
+ */
+export function isInsideTemplatesFolder(filePath) {
+  return filePath.split(/[/\\]/).includes(TEMPLATES_FOLDER);
+}
+
+/**
+ * Return the on-disk directory that stores template-base snapshots.
+ */
+function templateBasesDir(sourceRoot) {
+  return join(sourceRoot.replace(/\/$/, ''), '.ursa', 'template-bases');
+}
+
+/**
+ * Deterministic filename for a document's stored base snapshot.
+ * We encode slashes so everything lives in one flat directory.
+ */
+function baseSnapshotPath(sourceRoot, documentRelPath) {
+  const safeName = documentRelPath.replace(/[/\\]/g, '__');
+  return join(templateBasesDir(sourceRoot), safeName);
+}
+
+// ---------------------------------------------------------------------------
+// Frontmatter helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the raw frontmatter block (including delimiters + trailing newline)
+ * from the beginning of a markdown string.  Returns '' if there is none.
+ */
+export function extractFrontmatterBlock(content) {
+  const match = content.match(/^---\r?\n[\s\S]+?\r?\n---(?:\r?\n|$)/);
+  return match ? match[0] : '';
+}
+
+/**
+ * Return everything *after* the frontmatter block.
+ */
+export function extractBody(content) {
+  return content.slice(extractFrontmatterBlock(content).length);
+}
+
+/**
+ * Build a YAML frontmatter string from a plain object.
+ * Produces `---\nkey: value\n---\n`.
+ */
+export function buildFrontmatter(meta) {
+  if (!meta || Object.keys(meta).length === 0) return '';
+  const lines = Object.entries(meta).map(([k, v]) => {
+    if (typeof v === 'string') return `${k}: ${v}`;
+    // For non-string values use JSON-compatible representation that YAML also accepts
+    return `${k}: ${JSON.stringify(v)}`;
+  });
+  return `---\n${lines.join('\n')}\n---\n`;
+}
+
+/**
+ * Ensure the document content has a `template-source` frontmatter field.
+ * Preserves any existing frontmatter, adding or updating the field.
+ */
+export function ensureTemplateSourceFrontmatter(content, templateRelPath) {
+  const fmBlock = extractFrontmatterBlock(content);
+  const body = extractBody(content);
+
+  if (fmBlock) {
+    // Frontmatter exists — check if template-source is already there
+    if (/^template-source:/m.test(fmBlock)) {
+      // Update existing value
+      const updated = fmBlock.replace(
+        /^template-source:.*$/m,
+        `template-source: ${templateRelPath}`
+      );
+      return updated + body;
+    }
+    // Insert before closing ---
+    const insertPos = fmBlock.lastIndexOf('---');
+    const before = fmBlock.slice(0, insertPos);
+    const after = fmBlock.slice(insertPos);
+    return `${before}template-source: ${templateRelPath}\n${after}${body}`;
+  }
+
+  // No frontmatter at all — create one
+  return `---\ntemplate-source: ${templateRelPath}\n---\n${content}`;
+}
+
+// ---------------------------------------------------------------------------
+// Discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * From the full list of source files, return a Map of
+ *   templateRelPath → absolutePath
+ * for every .md/.mdx file inside a _templates folder.
+ */
+export function findAllDocumentTemplates(allFiles, sourceRoot) {
+  const normalizedRoot = sourceRoot.replace(/\/$/, '');
+  const templates = new Map();
+  for (const file of allFiles) {
+    if (isInsideTemplatesFolder(file) && /\.(md|mdx)$/.test(file)) {
+      const relPath = relative(normalizedRoot, file);
+      templates.set(relPath, file);
+    }
+  }
+  return templates;
+}
+
+/**
+ * From the full list of source files, return a Map of
+ *   documentAbsPath → templateRelPath
+ * for every document whose frontmatter contains `template-source`.
+ *
+ * `rawBodyCache` is an optional Map<absPath, string> of already-read file
+ * contents to avoid double I/O during the build.
+ */
+export async function findTemplatedDocuments(articlePaths, sourceRoot, rawBodyCache) {
+  const normalizedRoot = sourceRoot.replace(/\/$/, '');
+  const result = new Map(); // docAbsPath → templateRelPath
+
+  for (const absPath of articlePaths) {
+    try {
+      // Skip files that are themselves inside _templates
+      if (isInsideTemplatesFolder(absPath)) continue;
+
+      const content = rawBodyCache?.get(absPath) ?? await readFile(absPath, 'utf8');
+      const meta = extractMetadata(content);
+      const tplSrc = meta?.['template-source'];
+      if (tplSrc) {
+        result.set(absPath, tplSrc);
+      }
+    } catch {
+      // Unreadable file — skip silently
+    }
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Base snapshot I/O
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the stored base snapshot for a document.
+ * Returns `null` if no snapshot exists yet.
+ */
+export async function loadBaseSnapshot(sourceRoot, documentRelPath) {
+  const p = baseSnapshotPath(sourceRoot, documentRelPath);
+  if (!existsSync(p)) return null;
+  return readFile(p, 'utf8');
+}
+
+/**
+ * Persist the base snapshot for a document.
+ */
+export async function saveBaseSnapshot(sourceRoot, documentRelPath, body) {
+  const p = baseSnapshotPath(sourceRoot, documentRelPath);
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, body, 'utf8');
+}
+
+// ---------------------------------------------------------------------------
+// 3-way merge
+// ---------------------------------------------------------------------------
+
+/**
+ * Perform a git-style 3-way merge.
+ *
+ * @param {string} base      – template body when instance was last synced
+ * @param {string} ours      – current instance body (user edits)
+ * @param {string} theirs    – new template body
+ * @returns {{ merged: string, conflict: boolean }}
+ */
+export function threeWayMerge(base, ours, theirs) {
+  const baseLines  = base.split('\n');
+  const ourLines   = ours.split('\n');
+  const theirLines = theirs.split('\n');
+
+  const result = diff3Merge(ourLines, baseLines, theirLines);
+
+  if (!result.conflict) {
+    return { merged: result.result.join('\n'), conflict: false };
+  }
+
+  // Has conflicts — build output with conflict markers
+  const lines = [];
+  for (const chunk of result.result) {
+    if (typeof chunk === 'string') {
+      lines.push(chunk);
+    }
+  }
+  // The `merge` function from node-diff3 returns { conflict: bool, result: string[] }
+  // When conflict is true, result already contains conflict markers by default
+  return { merged: result.result.join('\n'), conflict: true };
+}
+
+// ---------------------------------------------------------------------------
+// Reconciliation (the main entry point for the build)
+// ---------------------------------------------------------------------------
+
+/**
+ * Reconcile a single templated document against its parent template.
+ *
+ * @param {string} docAbsPath      – absolute path to the document
+ * @param {string} templateAbsPath – absolute path to the template .md
+ * @param {string} sourceRoot      – docroot (with or without trailing /)
+ * @returns {Promise<{ action: string, conflict: boolean, message: string }>}
+ *   action: 'none' | 'updated' | 'initialized' | 'conflict' | 'error'
+ */
+export async function reconcileDocument(docAbsPath, templateAbsPath, sourceRoot) {
+  const normalizedRoot = sourceRoot.replace(/\/$/, '');
+  const docRelPath = relative(normalizedRoot, docAbsPath);
+
+  try {
+    const [docContent, templateContent] = await Promise.all([
+      readFile(docAbsPath, 'utf8'),
+      readFile(templateAbsPath, 'utf8'),
+    ]);
+
+    const templateBody = extractBody(templateContent);
+    const docBody = extractBody(docContent);
+    const docFmBlock = extractFrontmatterBlock(docContent);
+
+    // Load stored base snapshot
+    const storedBase = await loadBaseSnapshot(normalizedRoot, docRelPath);
+
+    if (storedBase === null) {
+      // First encounter — save current template body as the base.
+      // No merge needed; the document is already an instance.
+      await saveBaseSnapshot(normalizedRoot, docRelPath, templateBody);
+      return { action: 'initialized', conflict: false, message: `Initialized base snapshot for ${docRelPath}` };
+    }
+
+    // Check if template actually changed since last sync
+    if (storedBase === templateBody) {
+      return { action: 'none', conflict: false, message: `Template unchanged for ${docRelPath}` };
+    }
+
+    // Template changed — 3-way merge
+    const { merged, conflict } = threeWayMerge(storedBase, docBody, templateBody);
+
+    // Write the reconciled document (frontmatter + merged body)
+    await writeFile(docAbsPath, docFmBlock + merged, 'utf8');
+
+    // Update the base snapshot to the new template body
+    // (even on conflict — the user will resolve, and next run should be clean)
+    await saveBaseSnapshot(normalizedRoot, docRelPath, templateBody);
+
+    if (conflict) {
+      return { action: 'conflict', conflict: true, message: `Conflict in ${docRelPath} — manual resolution required` };
+    }
+    return { action: 'updated', conflict: false, message: `Auto-merged template changes into ${docRelPath}` };
+  } catch (e) {
+    return { action: 'error', conflict: false, message: `Error reconciling ${docRelPath}: ${e.message}` };
+  }
+}
+
+/**
+ * Reconcile ALL templated documents in the source tree.
+ *
+ * Returns a summary object:
+ *   { initialized, updated, conflicts, unchanged, errors, affectedPaths }
+ *
+ * `affectedPaths` is the set of absolute document paths that were written to
+ * disk (so the caller knows which files to regenerate).
+ */
+export async function reconcileAll(articlePaths, allFiles, sourceRoot) {
+  const normalizedRoot = sourceRoot.replace(/\/$/, '');
+
+  // 1. Discover templates and templated documents
+  const templateMap = findAllDocumentTemplates(allFiles, normalizedRoot);
+  const templatedDocs = await findTemplatedDocuments(articlePaths, normalizedRoot);
+
+  const summary = {
+    initialized: 0,
+    updated: 0,
+    conflicts: 0,
+    unchanged: 0,
+    errors: 0,
+    affectedPaths: new Set(),
+    messages: [],
+  };
+
+  if (templatedDocs.size === 0) {
+    return summary;
+  }
+
+  // 2. For each templated document, reconcile
+  for (const [docAbsPath, templateRelPath] of templatedDocs) {
+    const templateAbsPath = templateMap.get(templateRelPath)
+      ?? resolve(normalizedRoot, templateRelPath);
+
+    if (!existsSync(templateAbsPath)) {
+      summary.errors++;
+      summary.messages.push(`Template not found: ${templateRelPath} (referenced by ${relative(normalizedRoot, docAbsPath)})`);
+      continue;
+    }
+
+    const result = await reconcileDocument(docAbsPath, templateAbsPath, normalizedRoot);
+    summary.messages.push(result.message);
+
+    switch (result.action) {
+      case 'initialized':
+        summary.initialized++;
+        break;
+      case 'updated':
+        summary.updated++;
+        summary.affectedPaths.add(docAbsPath);
+        break;
+      case 'conflict':
+        summary.conflicts++;
+        summary.affectedPaths.add(docAbsPath);
+        break;
+      case 'none':
+        summary.unchanged++;
+        break;
+      case 'error':
+        summary.errors++;
+        break;
+    }
+  }
+
+  return summary;
+}
+
+/**
+ * Reconcile only documents that reference a specific template.
+ * Used by serve mode when a single template file changes.
+ *
+ * @param {string} changedTemplateAbsPath – the template that was saved
+ * @param {string[]} articlePaths         – all known article paths
+ * @param {string} sourceRoot             – docroot
+ * @returns same shape as reconcileAll's summary
+ */
+export async function reconcileByTemplate(changedTemplateAbsPath, articlePaths, sourceRoot) {
+  const normalizedRoot = sourceRoot.replace(/\/$/, '');
+  const templateRelPath = relative(normalizedRoot, changedTemplateAbsPath);
+
+  const summary = {
+    initialized: 0,
+    updated: 0,
+    conflicts: 0,
+    unchanged: 0,
+    errors: 0,
+    affectedPaths: new Set(),
+    messages: [],
+  };
+
+  // Find documents that reference this specific template
+  for (const docPath of articlePaths) {
+    if (isInsideTemplatesFolder(docPath)) continue;
+    try {
+      const content = await readFile(docPath, 'utf8');
+      const meta = extractMetadata(content);
+      if (meta?.['template-source'] !== templateRelPath) continue;
+
+      const result = await reconcileDocument(docPath, changedTemplateAbsPath, normalizedRoot);
+      summary.messages.push(result.message);
+
+      switch (result.action) {
+        case 'initialized': summary.initialized++; break;
+        case 'updated':
+          summary.updated++;
+          summary.affectedPaths.add(docPath);
+          break;
+        case 'conflict':
+          summary.conflicts++;
+          summary.affectedPaths.add(docPath);
+          break;
+        case 'none': summary.unchanged++; break;
+        case 'error': summary.errors++; break;
+      }
+    } catch {
+      // skip unreadable
+    }
+  }
+
+  return summary;
+}
+
+// ---------------------------------------------------------------------------
+// Template instantiation (CLI helper)
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new document from a template.
+ *
+ * @param {string} templateAbsPath – absolute path to the template .md file
+ * @param {string} destAbsPath     – absolute path for the new document
+ * @param {string} sourceRoot      – docroot
+ * @returns {{ templateRelPath: string, destRelPath: string }}
+ */
+export async function instantiateTemplate(templateAbsPath, destAbsPath, sourceRoot) {
+  const normalizedRoot = sourceRoot.replace(/\/$/, '');
+  const templateRelPath = relative(normalizedRoot, templateAbsPath);
+  const destRelPath = relative(normalizedRoot, destAbsPath);
+
+  if (existsSync(destAbsPath)) {
+    throw new Error(`Destination already exists: ${destAbsPath}`);
+  }
+
+  const templateContent = await readFile(templateAbsPath, 'utf8');
+  const templateBody = extractBody(templateContent);
+
+  // Build instance content: original template frontmatter + template-source + body
+  const templateMeta = extractMetadata(templateContent);
+  const instanceMeta = { ...(templateMeta || {}), 'template-source': templateRelPath };
+  const instanceContent = buildFrontmatter(instanceMeta) + templateBody;
+
+  await mkdir(dirname(destAbsPath), { recursive: true });
+  await writeFile(destAbsPath, instanceContent, 'utf8');
+
+  // Save the base snapshot so future reconciliation works
+  await saveBaseSnapshot(normalizedRoot, destRelPath, templateBody);
+
+  return { templateRelPath, destRelPath };
+}

package/src/helper/mdxRenderer.js

@@ -12,6 +12,25 @@ import remarkSupersub from "remark-supersub";
 import remarkGfm from "remark-gfm";
 import { visit } from "unist-util-visit";
 
+/**
+ * remark-definition-list only registers the `:` (charcode 58) marker, but
+ * PHP Markdown Extra (and markdown-it-deflist) also support `~` (charcode 126).
+ * This sibling plugin must run AFTER remarkDefinitionList; it locates the
+ * already-registered defList construct and re-registers it under `~` so that
+ * .mdx files have parity with .md files.
+ */
+function remarkDefinitionListTildeMarker() {
+  const data = this.data();
+  const micromarkExtensions = data.micromarkExtensions ?? (data.micromarkExtensions = []);
+  for (const ext of micromarkExtensions) {
+    const construct = ext?.document?.[58];
+    if (construct) {
+      micromarkExtensions.push({ document: { 126: construct } });
+      return;
+    }
+  }
+}
+
 /**
  * Custom remark plugin that converts container directives (:::name ... :::)
  * into <aside> HTML elements, matching the markdown-it-container behavior
@@ -122,6 +141,7 @@ export async function renderMDX({ source, filePath, sourceRoot, hydrate = false
       remarkDirective,
       remarkAsideContainers,
       remarkDefinitionList,
+      remarkDefinitionListTildeMarker,
       remarkSupersub,
     ];
     // remark-definition-list needs custom handlers for remark-rehype conversion

package/src/jobs/generate.js

@@ -79,6 +79,7 @@ import {
   copyMetaAssets,
 } from "../helper/build/index.js";
 import { getProfiler } from "../helper/build/profiler.js";
+import { reconcileAll, isInsideTemplatesFolder } from "../helper/documentTemplates.js";
 
 // Concurrency limiter for batch processing to avoid memory exhaustion
 const BATCH_SIZE = parseInt(process.env.URSA_BATCH_SIZE || '50', 10);
@@ -210,7 +211,7 @@ export async function generate({
 
   // read all articles, process them, copy them to build
   const articleExtensions = /\.(md|mdx|txt|yml)$/;
-  const hiddenOrSystemDirs = /[\/\\]\.(?!\.)|[\/\\]node_modules[\/\\]/;  // Matches hidden folders (starting with .) or node_modules
+  const hiddenOrSystemDirs = /[\/\\]\.(?!\.)|[\/\\]node_modules[\/\\]|[\/\\]_templates[\/\\]|[\/\\]_templates$/;  // Matches hidden folders (starting with .), node_modules, or _templates
   const allSourceFilenamesThatAreArticles = allSourceFilenames.filter(
     (filename) => filename.match(articleExtensions) && !filename.match(hiddenOrSystemDirs) && !isInHiddenFolder(filename)
   );
@@ -230,6 +231,40 @@ export async function generate({
   progress.logTimed(`Classified: ${allSourceFilenamesThatAreArticles.length} articles, ${allSourceFilenamesThatAreDirectories.length} dirs, ${existingHtmlFiles.size} HTML [${progress.stopTimer('Filter')}]`);
   profiler.endPhase('Filter & classify');
 
+  // Phase: Document template reconciliation
+  // Must run BEFORE article processing so that any template-driven changes
+  // to source .md files are picked up during rendering.
+  profiler.startPhase('Template reconciliation');
+  progress.startTimer('Templates');
+  const templateReconciliation = await reconcileAll(
+    allSourceFilenamesThatAreArticles,
+    allSourceFilenamesUnfiltered,   // templates live in _templates which is filtered out of articles
+    source
+  );
+  if (templateReconciliation.updated > 0 || templateReconciliation.conflicts > 0 || templateReconciliation.initialized > 0) {
+    progress.logTimed(
+      `📄 Document templates: ${templateReconciliation.initialized} initialized, ` +
+      `${templateReconciliation.updated} auto-merged, ` +
+      `${templateReconciliation.conflicts} conflicts, ` +
+      `${templateReconciliation.unchanged} unchanged, ` +
+      `${templateReconciliation.errors} errors`
+    );
+    if (templateReconciliation.conflicts > 0) {
+      console.warn(`\n⚠️  Template conflicts require manual resolution:`);
+      for (const msg of templateReconciliation.messages) {
+        if (msg.includes('Conflict')) console.warn(`   ${msg}`);
+      }
+      console.warn('');
+    }
+    if (templateReconciliation.errors > 0) {
+      for (const msg of templateReconciliation.messages) {
+        if (msg.includes('Error') || msg.includes('not found')) console.warn(`   ⚠️  ${msg}`);
+      }
+    }
+  }
+  progress.logTimed(`Document templates processed [${progress.stopTimer('Templates')}]`);
+  profiler.endPhase('Template reconciliation');
+
   // Phase: Build navigation and metadata
   profiler.startPhase('Build navigation');
   progress.startTimer('Navigation');

package/src/serve.js

@@ -11,6 +11,7 @@ import { watchModeCache } from "./helper/build/watchCache.js";
 import { dependencyTracker } from "./helper/dependencyTracker.js";
 import { bundleMetaTemplateAssets, clearMetaBundleCache } from "./helper/assetBundler.js";
 import { getTemplates, copyMetaAssets } from "./helper/build/templates.js";
+import { isInsideTemplatesFolder, reconcileByTemplate } from "./helper/documentTemplates.js";
 import { WebSocketServer } from "ws";
 import { createServer } from "http";
 import { resolvePort } from "./helper/portUtils.js";
@@ -553,9 +554,32 @@ export async function serve({
         try { await promises.unlink(join(ursaDir, 'nav-cache.json')); } catch {}
       }
 
+      // --- 5.5) Handle document template changes ---
+      // If a _templates/*.md file changed, reconcile all documents using that template
+      // and add the affected instance documents to the regeneration set.
+      const templateChanges = articleChanges.filter(c => c.name && isInsideTemplatesFolder(c.name));
+      if (templateChanges.length > 0 && watchModeCache.isInitialized) {
+        const allArticles = watchModeCache.allArticlePaths || [];
+        for (const change of templateChanges) {
+          console.log(`📄 Document template changed: ${basename(change.name)}`);
+          const reconcileResult = await reconcileByTemplate(change.name, allArticles, sourceDir);
+          if (reconcileResult.updated > 0 || reconcileResult.conflicts > 0) {
+            console.log(`   ${reconcileResult.updated} auto-merged, ${reconcileResult.conflicts} conflicts`);
+            reconcileResult.affectedPaths.forEach(p => affectedDocPaths.add(p));
+          }
+          if (reconcileResult.conflicts > 0) {
+            for (const msg of reconcileResult.messages) {
+              if (msg.includes('Conflict')) console.warn(`   ⚠️  ${msg}`);
+            }
+          }
+        }
+      }
+
       // --- 6) Handle article changes via fast single-file regen ---
       // Deduplicate articles (same file may appear multiple times in rapid saves)
-      const uniqueArticles = [...new Set(articleChanges.map(c => c.name))];
+      // Exclude _templates files from direct article regeneration (they aren't rendered)
+      const uniqueArticles = [...new Set(articleChanges.map(c => c.name))]
+        .filter(name => !isInsideTemplatesFolder(name));
       for (const articlePath of uniqueArticles) {
         affectedDocPaths.add(articlePath);
       }