@nutin/cli 2.1.1 → 3.0.0

package/templates/features/markdown/tools/builder/core/markdown/markdown-compiler.test.js.hbs

@@ -0,0 +1,390 @@
+import * as fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { Marked } from 'marked';
+import matter from 'gray-matter';
+import { compileLanguages, compileSource, firstProse, folderTitle, headingId, normalizeSource, slugFromFilename, stripInlineMarkdown } from './markdown-compiler.js';
+
+let root;
+
+function write(relPath, content) {
+  const fullPath = path.join(root, relPath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content);
+}
+
+function compile(entry) {
+  return compileSource(normalizeSource(entry, root), { Marked, matter, root });
+}
+
+const I18N = { i18n: true, languages: ['en', 'fr'], defaultLanguage: 'en' };
+
+function compileAll(entry, options = I18N) {
+  return compileLanguages(normalizeSource(entry, root), { Marked, matter, root }, options);
+}
+
+describe('markdown-compiler', () => {
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'nutin-markdown-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  it('derives the id, route prefix and conventional hub file from the folder', () => {
+    write('articles/ARTICLES.md', '# Articles\n');
+    const source = normalizeSource('articles', root);
+    expect(source.id).toBe('articles');
+    expect(source.hubFiles).toEqual(['ARTICLES.md']);
+    expect(source.sectionInPath).toBe(false);
+  });
+
+  // Same cases as src/app/markdown/markdown-sources.test.js: the runtime derives these ids too.
+  it('derives manifest ids like the runtime does', () => {
+    const cases = [
+      ['content', 'content', false],
+      ['docs/My Guides', 'my-guides', false],
+      ['docs/guides/', 'guides', false],
+      [{ folder: 'x', routePrefix: 'api' }, 'api', false],
+      [{ folder: 'docs', sectionInPath: true }, 'docs', true],
+    ];
+    for (const [entry, id, sectionInPath] of cases) {
+      const source = normalizeSource(entry, root);
+      expect(source.id).toBe(id);
+      expect(source.sectionInPath).toBe(sectionInPath);
+    }
+  });
+
+  it('rejects invalid entries and route prefixes', () => {
+    expect(() => normalizeSource({}, root)).toThrow('expected a folder path');
+    expect(() => normalizeSource({ folder: 'docs', routePrefix: 'Docs Pages' }, root)).toThrow('"routePrefix"');
+    expect(() => normalizeSource({ folder: 'docs', hubFiles: 'API.md' }, root)).toThrow('"hubFiles"');
+  });
+
+  it('enables SEO pages by default, and validates the "seo" option', () => {
+    expect(normalizeSource('content', root).seo).toBe(true);
+    expect(normalizeSource({ folder: 'content', seo: false }, root).seo).toBe(false);
+    expect(() => normalizeSource({ folder: 'content', seo: 'no' }, root)).toThrow('"seo"');
+  });
+
+  it('passes a frontmatter ogImage through to the page', () => {
+    write('content/a.md', '---\nogImage: /og/a.jpg\n---\n# A\n\nText.\n');
+    write('content/b.md', '# B\n\nText.\n');
+
+    const { manifest } = compile('content');
+
+    expect(manifest.pages.a.ogImage).toBe('/og/a.jpg');
+    expect('ogImage' in manifest.pages.b).toBeFalsy();
+  });
+
+  it('derives plain-text descriptions from inline Markdown', () => {
+    expect(stripInlineMarkdown('Built with [marked](https://marked.js.org/), **fast** and `small`.')).toBe('Built with marked, fast and small.');
+    expect(stripInlineMarkdown('An ![logo](/l.png) _here_ and snake_case_name')).toBe('An logo here and snake_case_name');
+  });
+
+  it('applies prefix replacements to file-name slugs', () => {
+    const replacements = [['HOWDOI_', ''], ['WHATIS_', 'what-is-']];
+    expect(slugFromFilename('HOWDOI_CREATE_A_VIEW.md', replacements)).toBe('create-a-view');
+    expect(slugFromFilename('WHATIS_A_VIEW.md', replacements)).toBe('what-is-a-view');
+    expect(slugFromFilename('Plain Name.md')).toBe('plain-name');
+  });
+
+  it('compiles a frontmatter-only folder, sorted by order and grouped', () => {
+    write('content/b.md', '---\norder: 2\ngroup: Guides\n---\n# Second\n\nSecond page.\n');
+    write('content/a.md', '---\ntitle: First page\norder: 1\n---\n# Ignored H1\n\nFirst page.\n');
+    write('content/nested/c.md', '# Third\n\nThird page.\n');
+
+    const { manifest } = compile('content');
+    const [section] = manifest.sections;
+
+    expect(section.id).toBe('index');
+    expect(section.groups).toEqual([
+      { id: null, title: null, pages: ['a'] },
+      { id: 'guides', title: 'Guides', pages: ['b'] },
+      { id: 'nested', title: 'Nested', pages: ['c'] },
+    ]);
+    expect(manifest.pages.a.title).toBe('First page');
+    expect(manifest.pages.a.description).toBe('First page.');
+    expect(manifest.pages.c.source).toBe('content/nested/c.md');
+  });
+
+  it('groups a frontmatter-only folder\'s pages by first-level subfolder, root pages first', () => {
+    write('content/intro.md', '# Intro\n\nWelcome.\n');
+    write('content/01-getting-started/install.md', '# Install\n\nRun it.\n');
+    write('content/01-getting-started/configure.md', '# Configure\n\nSet it up.\n');
+    write('content/02_advanced/routing.md', '# Routing\n\nRoutes.\n');
+    write('content/02_advanced/deep/guards.md', '# Guards\n\nGuards.\n');
+    write('content/02_advanced/faq.md', '---\ngroup: Help\n---\n# FAQ\n\nQuestions.\n');
+    write('content/API/reference.md', '# Reference\n\nAll of it.\n');
+    write('content/misc.md', '---\ngroup: API\n---\n# Misc\n\nOther.\n');
+
+    const [section] = compile('content').manifest.sections;
+
+    expect(section.groups).toEqual([
+      { id: null, title: null, pages: ['intro'] },
+      { id: 'getting-started', title: 'Getting started', pages: ['configure', 'install'] },
+      { id: 'advanced', title: 'Advanced', pages: ['guards', 'routing'] },
+      { id: 'help', title: 'Help', pages: ['faq'] },
+      { id: 'api', title: 'API', pages: ['reference', 'misc'] },
+    ]);
+  });
+
+  it('makes a folder name a readable group title', () => {
+    expect(folderTitle('getting-started')).toBe('Getting started');
+    expect(folderTitle('02_advanced_topics')).toBe('Advanced topics');
+    expect(folderTitle('3. reference')).toBe('Reference');
+    expect(folderTitle('API')).toBe('API');
+    expect(folderTitle('HowTo')).toBe('HowTo');
+    expect(folderTitle('2024')).toBe('2024');
+  });
+
+  it('compiles hub files into sections, honoring their order and link titles', () => {
+    write('docs/API.md', '# API\n\nThe API.\n\n## Table of Contents\n\n### Views\n\n- [Create a view](./API/HOWDOI_CREATE_A_VIEW.md)\n');
+    write('docs/TOOLS.md', '---\ntitle: Tooling\n---\n# Nutin - Tools\n\n## Table of Contents\n\n- [Builder](./TOOLS/BUILDER.md)\n');
+    write('docs/API/HOWDOI_CREATE_A_VIEW.md', '# How do I create a view?\n\nLike this.\n\nSee the [builder](../TOOLS/BUILDER.md#usage).\n');
+    write('docs/TOOLS/BUILDER.md', '# Builder\n\n## Usage\n\n## Options\n');
+
+    const { manifest, warnings } = compile({
+      folder: 'docs',
+      hubFiles: ['API.md', 'TOOLS.md'],
+      sectionInPath: true,
+      prefixReplacements: [['HOWDOI_', '']],
+    });
+
+    expect(manifest.sections.map((s) => [s.id, s.title])).toEqual([['api', 'API'], ['tools', 'Tooling']]);
+    expect(manifest.sections[0].groups).toEqual([{ id: 'views', title: 'Views', pages: ['create-a-view'] }]);
+    expect(manifest.sections[1].pages).toEqual(['builder']);
+    expect(manifest.pages['create-a-view'].title).toBe('Create a view');
+    expect(manifest.pages['create-a-view'].html).toContain('href="/docs/tools/builder#usage" data-event="click:_navigateTo:@attr:href"');
+    expect(manifest.pages.builder.headings).toEqual([
+      { depth: 2, text: 'Usage', id: 'usage' },
+      { depth: 2, text: 'Options', id: 'options' },
+    ]);
+    expect(warnings.some((w) => w.includes('Title mismatch'))).toBe(true);
+  });
+
+  it('warns about pages no hub lists', () => {
+    write('guides/GUIDES.md', '# Guides\n\n## Table of Contents\n\n- [One](./ONE.md)\n');
+    write('guides/ONE.md', '# One\n');
+    write('guides/ORPHAN.md', '# Orphan\n');
+
+    const { manifest, warnings } = compile('guides');
+    expect(Object.keys(manifest.pages)).toEqual(['one']);
+    expect(warnings.some((w) => w.includes('guides/ORPHAN.md'))).toBe(true);
+  });
+
+  it('fails on duplicate slugs', () => {
+    write('content/a.md', '---\nslug: same\n---\n# A\n');
+    write('content/b.md', '---\nslug: same\n---\n# B\n');
+    expect(() => compile('content')).toThrow('Duplicate slug "same"');
+  });
+
+  it('fails on links to pages that are not compiled', () => {
+    write('content/a.md', '# A\n\n[Missing](./missing.md)\n');
+    expect(() => compile('content')).toThrow('Unresolvable internal link "./missing.md"');
+  });
+
+  it('reports every broken link of a page in one error, without marked\'s bug-report suffix', () => {
+    write('content/a.md', '# A\n\n[One](./one.md) and [Two](./two.md#part)\n');
+    let message = '';
+    try {
+      compile('content');
+    } catch (err) {
+      message = err.message;
+    }
+    expect(message).toContain('"./one.md"');
+    expect(message).toContain('"./two.md#part"');
+    expect(message).not.toContain('Please report');
+  });
+
+  it('gives repeated headings unique ids and keeps accented letters as their base letter', () => {
+    const seen = new Map();
+    expect(['Usage', 'Usage', 'Usage'].map((text) => headingId(text, seen))).toEqual(['usage', 'usage-1', 'usage-2']);
+    expect(headingId('Résumé à côté', new Map())).toBe('resume-a-cote');
+
+    write('notes/a.md', '# A\n\n## Usage\n\n## Options\n\n## Usage\n\n## Été `chaud`\n');
+    const { manifest } = compile({ folder: 'notes', hubFiles: [] });
+    expect(manifest.pages.a.headings).toEqual([
+      { depth: 2, text: 'Usage', id: 'usage' },
+      { depth: 2, text: 'Options', id: 'options' },
+      { depth: 2, text: 'Usage', id: 'usage-1' },
+      { depth: 2, text: 'Été chaud', id: 'ete-chaud' },
+    ]);
+    expect(manifest.pages.a.html).toContain('<h2 id="usage-1">Usage</h2>');
+  });
+
+  it('keeps page slugs as they were: accents only change heading ids', () => {
+    write('notes/café.md', '# Café\n');
+    const { manifest } = compile({ folder: 'notes', hubFiles: [] });
+    expect(Object.keys(manifest.pages)).toEqual(['caf']);
+  });
+
+  it('derives descriptions from the first paragraph or list item, as plain text', () => {
+    expect(firstProse('<details>\n<summary>Q</summary>\n</details>\n\nA **real** `paragraph`\nover two lines.\n', Marked)).toBe('A real paragraph over two lines.');
+    expect(firstProse('## Fixes\n\n- Fixed `npm run dev` for **nested** templates.\n- Other fix.\n', Marked)).toBe('Fixed npm run dev for nested templates.');
+    expect(firstProse('```ts\nconst a = 1;\n```\n', Marked)).toBe('');
+    // Whichever comes first: a list before a later paragraph wins.
+    expect(firstProse('- Added `x`.\n\nNotes: about x.\n', Marked)).toBe('Added x.');
+    // HTML tags are dropped, but not inside code spans, where they are text.
+    expect(firstProse('A <em>tag</em> and `<b>code</b>`.\n', Marked)).toBe('A tag and <b>code</b>.');
+
+    write('log/1-0-0.md', '# 1.0.0\n\n## Fixes\n\n- Fixed `npm run dev`.\n');
+    const { manifest } = compile({ folder: 'log', hubFiles: [] });
+    expect(manifest.pages['1-0-0'].description).toBe('Fixed npm run dev.');
+  });
+
+  it('strips Markdown from hub descriptions', () => {
+    write('docs/TOOLS.md', '# Tools\n\n***Important:*** switching **package manager**\nneeds `care`.\n\n- a list after it\n\n## Table of Contents\n\n- [Builder](./BUILDER.md)\n');
+    write('docs/BUILDER.md', '# Builder\n');
+    const { manifest } = compile({ folder: 'docs', hubFiles: ['TOOLS.md'] });
+    expect(manifest.sections[0].description).toBe('Important: switching package manager needs care.');
+  });
+
+  it('fails on a page listed in two hub files, or twice in one', () => {
+    write('docs/API.md', '# API\n\n## Table of Contents\n\n- [Intro](./INTRO.md)\n');
+    write('docs/TOOLS.md', '# Tools\n\n## Table of Contents\n\n- [Intro again](./INTRO.md)\n');
+    write('docs/INTRO.md', '# Intro\n');
+    expect(() => compile({ folder: 'docs', hubFiles: ['API.md', 'TOOLS.md'] }))
+      .toThrow('"docs/INTRO.md" is listed in both "API.md" and "TOOLS.md"');
+
+    write('docs/API.md', '# API\n\n## Table of Contents\n\n- [Intro](./INTRO.md)\n- [Intro](./INTRO.md)\n');
+    expect(() => compile({ folder: 'docs', hubFiles: ['API.md'] })).toThrow('is listed in "API.md" twice');
+  });
+
+  it('accepts "*" and "+" page bullets in hub files, and warns about list items that are not pages', () => {
+    write('docs/DOCS.md', '---\ntitle: Docs\n---\n# Docs\n\n## Table of Contents\n\n* [A](./A.md)\n+ [B](./B.md)\n- [C](./C.md) — the third\n  - [D](./D.md)\n1. [E](./E.md)\n');
+    ['A', 'B', 'C', 'D', 'E'].forEach((name) => write(`docs/${name}.md`, `# ${name}\n`));
+    const { manifest, warnings } = compile('docs');
+
+    expect(manifest.sections[0].pages).toEqual(['a', 'b']);
+    const ignored = warnings.filter((w) => w.includes('is not a page entry'));
+    expect(ignored.length).toBe(3);
+    expect(ignored[0]).toContain('"DOCS.md" line 10');
+    expect(ignored[0]).toContain('- [C](./C.md) — the third');
+  });
+
+  it('validates the "ogImage" and "landing" options', () => {
+    expect(normalizeSource({ folder: 'docs', ogImage: '/og/docs.jpg' }, root).ogImage).toBe('/og/docs.jpg');
+    expect(() => normalizeSource({ folder: 'docs', ogImage: 3 }, root)).toThrow('"ogImage"');
+    expect(normalizeSource('docs', root).landing).toBe(null);
+    expect(normalizeSource({ folder: 'docs', landing: true }, root).landing).toEqual({});
+    expect(normalizeSource({ folder: 'docs', landing: { title: 'Docs' } }, root).landing).toEqual({ title: 'Docs', description: undefined });
+    expect(() => normalizeSource({ folder: 'docs', landing: 'yes' }, root)).toThrow('"landing"');
+    expect(() => normalizeSource({ folder: 'docs', landing: { title: 1 } }, root)).toThrow('"landing"');
+  });
+
+  it('adds a landing to the manifest: the single hub\'s title and description, or the folder\'s', () => {
+    write('guides/GUIDES.md', '# Guides\n\nHow-tos for **common** tasks.\n\n## Table of Contents\n\n- [A](./A.md)\n');
+    write('guides/A.md', '# A\n');
+    expect(compile('guides').manifest.landing).toBe(undefined);
+    expect(compile({ folder: 'guides', landing: true }).manifest.landing).toEqual({ title: 'Guides', description: 'How-tos for common tasks.' });
+
+    write('docs/API.md', '# API\n\nThe API.\n\n## Table of Contents\n\n- [A](./A.md)\n');
+    write('docs/TOOLS.md', '# Tools\n\n## Table of Contents\n\n- [B](./B.md)\n');
+    write('docs/A.md', '# A\n');
+    write('docs/B.md', '# B\n');
+    const hubs = { folder: 'docs', hubFiles: ['API.md', 'TOOLS.md'], sectionInPath: true };
+    expect(compile({ ...hubs, landing: true }).manifest.landing).toEqual({ title: 'docs', description: '' });
+    expect(compile({ ...hubs, landing: { title: 'Documentation', description: 'Everything.' } }).manifest.landing)
+      .toEqual({ title: 'Documentation', description: 'Everything.' });
+  });
+
+  it('translates a single-hub landing with its hub', () => {
+    write('guides/en/GUIDES.md', '# Guides\n\nHow-tos.\n\n## Table of Contents\n\n- [A](./A.md)\n');
+    write('guides/en/A.md', '# A\n');
+    write('guides/fr/GUIDES.md', '# Guides FR\n\nTutoriels.\n\n## Table of Contents\n\n- [A](./A.md)\n');
+    write('guides/fr/A.md', '# A FR\n');
+    const { manifests } = compileAll({ folder: 'guides', landing: true });
+    expect(manifests.en.landing).toEqual({ title: 'Guides', description: 'How-tos.' });
+    expect(manifests.fr.landing).toEqual({ title: 'Guides FR', description: 'Tutoriels.' });
+  });
+
+  it('fails on missing folders, hub files and listed pages', () => {
+    expect(() => compile('nope')).toThrow('Markdown folder "nope" not found');
+
+    write('docs/intro.md', '# Intro\n');
+    expect(() => compile({ folder: 'docs', hubFiles: ['API.md'] })).toThrow('Hub file "API.md" not found');
+
+    write('docs/DOCS.md', '# Docs\n\n## Table of Contents\n\n- [Gone](./GONE.md)\n');
+    expect(() => compile('docs')).toThrow('does not exist');
+  });
+
+  it('compiles one manifest per language with "/<lang>" links when i18n is on', () => {
+    write('content/a.md', '# A\n\nSee [B](./b.md).\n');
+    write('content/b.md', '# B\n\nText.\n');
+
+    const { manifests } = compileAll('content');
+
+    expect(Object.keys(manifests)).toEqual(['en', 'fr']);
+    expect(manifests.en.pages.a.html).toContain('href="/en/content/b"');
+    expect(manifests.fr.pages.a.html).toContain('href="/fr/content/b"');
+  });
+
+  it('translates a localized folder over its default language, falling back for missing pages', () => {
+    write('content/en/a.md', '---\norder: 1\n---\n# A\n\nSee [B](./b.md).\n');
+    write('content/en/b.md', '---\norder: 2\n---\n# B\n\nText.\n');
+    write('content/fr/a.md', '# A fr\n\nVoir [B](./b.md).\n');
+
+    const { manifests, warnings } = compileAll('content');
+
+    expect(manifests.fr.pages.a.title).toBe('A fr');
+    expect(manifests.fr.pages.a.html).toContain('href="/fr/content/b"');
+    expect(manifests.fr.pages.b.title).toBe('B');
+    expect(manifests.fr.pages.b.fallback).toBe(true);
+    expect(manifests.fr.pages.b.html).toBe(manifests.en.pages.b.html);
+    expect(manifests.fr.sections[0].title).toBe('content');
+    expect(warnings.some((w) => w.includes('content/fr') && w.includes('b'))).toBeTruthy();
+  });
+
+  it('uses the default language for a language with no folder at all', () => {
+    write('content/en/a.md', '# A\n\nText.\n');
+
+    const { manifests, warnings } = compileAll('content');
+
+    expect(manifests.fr.pages.a.fallback).toBe(true);
+    expect(warnings.some((w) => w.includes('no "fr" folder'))).toBeTruthy();
+  });
+
+  it('fails on a page that only exists in a translation', () => {
+    write('content/en/a.md', '# A\n\nText.\n');
+    write('content/fr/extra.md', '# Extra\n\nTexte.\n');
+
+    expect(() => compileAll('content')).toThrow('has no "en" counterpart');
+  });
+
+  it('compiles only the default language of a localized folder when i18n is off', () => {
+    write('content/en/a.md', '# A\n\nText.\n');
+    write('content/fr/a.md', '# A fr\n\nTexte.\n');
+
+    const { manifests } = compileAll('content', { i18n: false, languages: ['en', 'fr'], defaultLanguage: 'en' });
+
+    expect(Object.keys(manifests)).toEqual(['']);
+    expect(manifests[''].pages.a.title).toBe('A');
+  });
+
+  it('groups a localized frontmatter-only folder by subfolder within each language, ids shared across languages', () => {
+    write('content/en/start/a.md', '# A\n\nText.\n');
+    write('content/fr/start/a.md', '---\ngroup: Débuter\n---\n# A fr\n\nTexte.\n');
+
+    const { manifests } = compileAll('content');
+
+    expect(manifests.en.sections[0].groups).toEqual([{ id: 'start', title: 'Start', pages: ['a'] }]);
+    expect(manifests.fr.sections[0].groups).toEqual([{ id: 'start', title: 'Débuter', pages: ['a'] }]);
+  });
+
+  it('translates hub section and group titles', () => {
+    write('docs/en/GUIDES.md', '# Guides\n\nLearn.\n\n## Table of Contents\n\n### Start\n\n- [Install](./install.md)\n');
+    write('docs/en/install.md', '# Install\n\nRun it.\n');
+    write('docs/fr/GUIDES.md', '# Guides fr\n\nApprendre.\n\n## Table of Contents\n\n### Débuter\n\n- [Installer](./install.md)\n');
+    write('docs/fr/install.md', '# Installer\n\nLancez-le.\n');
+
+    const { manifests } = compileAll({ folder: 'docs', sectionInPath: true, hubFiles: ['GUIDES.md'] });
+
+    expect(manifests.fr.sections[0].title).toBe('Guides fr');
+    expect(manifests.fr.sections[0].groups[0].title).toBe('Débuter');
+    expect(manifests.fr.sections[0].groups[0].id).toBe(manifests.en.sections[0].groups[0].id);
+    expect(manifests.fr.pages.install.title).toBe('Installer');
+  });
+});
+

package/templates/features/markdown/tools/builder/core/markdown/markdown-seo-routes.js.hbs

@@ -0,0 +1,155 @@
+import * as fs from 'fs';
+import path from 'path';
+import { print, errorExit } from '../../../utils/index.js';
+import { PATHS } from '../app/paths.js';
+import nutinConfig from '../../../../nutin.config.js';
+import { LANGUAGES, DEFAULT_LANGUAGE } from '../../../utils/languages.js';
+import { normalizeSource } from './markdown-compiler.js';
+
+// The app route each source is served on — keep in sync with src/app/markdown/markdown-routes.ts.
+function routePattern(source) {
+  return source.sectionInPath ? `/${source.id}/:section?/:slug?` : `/${source.id}/:slug?`;
+}
+
+// Page slugs in nav order (sections, then their groups or pages).
+function orderedSlugs(manifest) {
+  return manifest.sections.flatMap((section) => section.groups ? section.groups.flatMap((group) => group.pages) : (section.pages ?? []));
+}
+
+function describe(manifest, page) {
+  if (page.description) return { description: page.description, fallback: null };
+  const section = manifest.sections.find((s) => s.id === page.section);
+  return section?.description
+    ? { description: section.description, fallback: 'its section\'s' }
+    : { description: page.title, fallback: 'its title' };
+}
+
+// The landing's SEO routes: the bare /<id>, plus /<id>/<section> for each section with
+// "sectionInPath". Titles and descriptions come from each language's manifest.
+function landingRoutes(source, byLang, languages, warnings) {
+  const perLanguage = (pick, label) => {
+    const title = {};
+    const description = {};
+    for (const [lang, manifest] of Object.entries(byLang)) {
+      const { title: t, description: d } = pick(manifest);
+      title[lang] = t;
+      description[lang] = d || t;
+      if (!d) warnings.push(`${label}${lang ? ` (${lang})` : ''} has no description for its SEO page — using its title.`);
+    }
+    return { title: languages ? title : title[''], description: languages ? description : description[''] };
+  };
+  const ogImage = source.ogImage ? { ogImage: source.ogImage } : {};
+  const reference = Object.values(byLang)[0];
+
+  const routes = [{
+    path: routePattern(source),
+    mockParams: {},
+    ...perLanguage((manifest) => manifest.landing, `The "${source.id}" landing`),
+    ...ogImage,
+  }];
+
+  if (source.sectionInPath) {
+    for (const { id } of reference.sections) {
+      routes.push({
+        path: routePattern(source),
+        mockParams: { section: id },
+        ...perLanguage((manifest) => manifest.sections.find((section) => section.id === id) ?? {}, `The "${source.id}/${id}" landing`),
+        ...ogImage,
+      });
+    }
+  }
+  return routes;
+}
+
+/**
+ * One SEO route per compiled Markdown page, in the shape config/seo.json routes use, so
+ * generate-seo-html.js prerenders it at its real URL (`mockParams` fill the route's params)
+ * and generate-sitemap-xml.js lists it. The bare /<id> URL gets no page of its own (the SPA
+ * replaces it with its first page's URL) unless the source has a "landing": then /<id>, and
+ * each /<id>/<section> with "sectionInPath", get one too.
+ *
+ * `manifestsById[id]` is the source's manifest, or with `languages` (i18n) a
+ * { [lang]: manifest } map: titles and descriptions then become per-language objects, and
+ * the default language's manifest defines the pages.
+ */
+export function buildMarkdownSeoRoutes(sources, manifestsById, { languages = null, defaultLanguage = null } = {}) {
+  const routes = [];
+  const warnings = [];
+
+  for (const source of sources) {
+    if (!source.seo) continue;
+    const byLang = languages ? manifestsById[source.id] : { '': manifestsById[source.id] };
+    const reference = byLang?.[languages ? defaultLanguage : ''];
+    if (!reference) continue;
+
+    for (const slug of orderedSlugs(reference)) {
+      const page = reference.pages[slug];
+      if (!page) continue;
+
+      const title = {};
+      const description = {};
+      for (const [lang, manifest] of Object.entries(byLang)) {
+        const localized = manifest.pages[slug] ?? page;
+        const described = describe(manifest, localized);
+        title[lang] = localized.title;
+        description[lang] = described.description;
+        if (described.fallback && !localized.fallback) {
+          warnings.push(`"${source.id}/${slug}"${lang ? ` (${lang})` : ''} has no description for its SEO page — using ${described.fallback}. Add a frontmatter "description".`);
+        }
+      }
+
+      const ogImage = page.ogImage ?? source.ogImage;
+      routes.push({
+        path: routePattern(source),
+        mockParams: source.sectionInPath ? { section: page.section, slug } : { slug },
+        title: languages ? title : title[''],
+        description: languages ? description : description[''],
+        ...(ogImage ? { ogImage } : {}),
+      });
+    }
+
+    if (reference.landing) routes.push(...landingRoutes(source, byLang, languages, warnings));
+  }
+
+  return { routes, warnings };
+}
+
+function readSources() {
+  return (nutinConfig.markdownSources?.sourceFolders ?? []).map((entry) => normalizeSource(entry, process.cwd()));
+}
+
+// Route patterns of sources with "seo: false".
+export function markdownSeoOptOutPaths() {
+  return readSources().filter((source) => !source.seo).map(routePattern);
+}
+
+let cached;
+
+// Reads nutin.config.js "markdownSources" and the manifest(s) the markdown build step wrote
+// to dist-build earlier in the pipeline. Memoized: the SEO HTML and sitemap steps both ask.
+export function markdownSeoRoutes() {
+  if (cached) return cached;
+
+  const sources = readSources();
+  const languages = nutinConfig.i18n ? LANGUAGES : null;
+  const readManifest = (fileName) => {
+    const manifestPath = path.join(PATHS.tempSource, 'generated', fileName);
+    try {
+      return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch (err) {
+      errorExit(`Cannot read the Markdown manifest ${manifestPath} for SEO pages: ${err.message}`, 'markdown-seo');
+    }
+  };
+
+  const manifestsById = {};
+  for (const source of sources.filter((s) => s.seo)) {
+    manifestsById[source.id] = languages
+      ? Object.fromEntries(languages.map((lang) => [lang, readManifest(`${source.id}.${lang}.json`)]))
+      : readManifest(`${source.id}.json`);
+  }
+
+  const { routes, warnings } = buildMarkdownSeoRoutes(sources, manifestsById, { languages, defaultLanguage: DEFAULT_LANGUAGE });
+  warnings.forEach((warning) => print.warn(`markdown: ${warning}`));
+  cached = routes;
+  return routes;
+}

package/templates/features/markdown/tools/builder/core/markdown/markdown-seo-routes.test.js.hbs

@@ -0,0 +1,112 @@
+import { buildMarkdownSeoRoutes } from './markdown-seo-routes.js';
+
+const page = (slug, section, extra = {}) => ({ slug, section, title: `T ${slug}`, description: `D ${slug}`, ...extra });
+
+describe('buildMarkdownSeoRoutes', () => {
+  it('emits one route per page on /<id>/:slug?, in nav order', () => {
+    const manifest = {
+      sections: [{ id: 'index', title: 'x', description: '', pages: ['b', 'a'] }],
+      pages: { a: page('a', 'index'), b: page('b', 'index') },
+    };
+
+    const { routes } = buildMarkdownSeoRoutes([{ id: 'content', seo: true, sectionInPath: false }], { content: manifest });
+
+    expect(routes).toEqual([
+      { path: '/content/:slug?', mockParams: { slug: 'b' }, title: 'T b', description: 'D b' },
+      { path: '/content/:slug?', mockParams: { slug: 'a' }, title: 'T a', description: 'D a' },
+    ]);
+  });
+
+  it('fills the section param for sectionInPath sources and walks groups', () => {
+    const manifest = {
+      sections: [{ id: 'api', title: 'API', description: '', groups: [{ id: 'g', title: 'G', pages: ['nav'] }] }],
+      pages: { nav: page('nav', 'api') },
+    };
+
+    const { routes } = buildMarkdownSeoRoutes([{ id: 'docs', seo: true, sectionInPath: true }], { docs: manifest });
+
+    expect(routes[0].path).toBe('/docs/:section?/:slug?');
+    expect(routes[0].mockParams).toEqual({ section: 'api', slug: 'nav' });
+  });
+
+  it('uses the folder ogImage when a page has none of its own', () => {
+    const manifest = {
+      sections: [{ id: 'index', title: 'x', description: '', pages: ['a', 'b'] }],
+      pages: { a: page('a', 'index'), b: page('b', 'index', { ogImage: '/og/b.jpg' }) },
+    };
+    const { routes } = buildMarkdownSeoRoutes([{ id: 'blog', seo: true, ogImage: '/og/blog.jpg' }], { blog: manifest });
+    expect(routes.map((r) => r.ogImage)).toEqual(['/og/blog.jpg', '/og/b.jpg']);
+  });
+
+  it('adds landing routes: the bare /<id>, and each section with sectionInPath', () => {
+    const manifest = {
+      sections: [
+        { id: 'api', title: 'API', description: 'The API.', pages: ['nav'] },
+        { id: 'tools', title: 'Tools', description: '', pages: ['cli'] },
+      ],
+      pages: { nav: page('nav', 'api'), cli: page('cli', 'tools') },
+      landing: { title: 'Docs', description: 'Everything.' },
+    };
+
+    const { routes, warnings } = buildMarkdownSeoRoutes([{ id: 'docs', seo: true, sectionInPath: true, ogImage: '/og/docs.jpg' }], { docs: manifest });
+    const landings = routes.filter((r) => !r.mockParams.slug);
+
+    expect(landings).toEqual([
+      { path: '/docs/:section?/:slug?', mockParams: {}, title: 'Docs', description: 'Everything.', ogImage: '/og/docs.jpg' },
+      { path: '/docs/:section?/:slug?', mockParams: { section: 'api' }, title: 'API', description: 'The API.', ogImage: '/og/docs.jpg' },
+      { path: '/docs/:section?/:slug?', mockParams: { section: 'tools' }, title: 'Tools', description: 'Tools', ogImage: '/og/docs.jpg' },
+    ]);
+    expect(warnings.some((w) => w.includes('"docs/tools" landing'))).toBe(true);
+  });
+
+  it('gives a landing per-language titles with i18n, and none without "landing"', () => {
+    const en = { sections: [{ id: 'index', title: 'Guides', description: 'How-tos.', pages: ['a'] }], pages: { a: page('a', 'index') }, landing: { title: 'Guides', description: 'How-tos.' } };
+    const fr = { ...en, landing: { title: 'Guides FR', description: 'Tutoriels.' } };
+    const { routes } = buildMarkdownSeoRoutes([{ id: 'guides', seo: true }], { guides: { en, fr } }, { languages: ['en', 'fr'], defaultLanguage: 'en' });
+    const landing = routes.find((r) => !r.mockParams.slug);
+    expect(landing.title).toEqual({ en: 'Guides', fr: 'Guides FR' });
+    expect(landing.description).toEqual({ en: 'How-tos.', fr: 'Tutoriels.' });
+
+    const { landing: _, ...noLanding } = en;
+    expect(buildMarkdownSeoRoutes([{ id: 'guides', seo: true }], { guides: noLanding }).routes.every((r) => r.mockParams.slug)).toBe(true);
+  });
+
+  it('skips sources with seo: false', () => {
+    const manifest = { sections: [{ id: 'index', pages: ['a'] }], pages: { a: page('a', 'index') } };
+
+    expect(buildMarkdownSeoRoutes([{ id: 'content', seo: false }], { content: manifest }).routes).toEqual([]);
+  });
+
+  it('falls back to the section description, then the title, with a warning', () => {
+    const manifest = {
+      sections: [
+        { id: 'one', title: 'One', description: 'Section one', pages: ['a'] },
+        { id: 'two', title: 'Two', description: '', pages: ['b'] },
+      ],
+      pages: { a: page('a', 'one', { description: '' }), b: page('b', 'two', { description: '' }) },
+    };
+
+    const { routes, warnings } = buildMarkdownSeoRoutes([{ id: 'c', seo: true }], { c: manifest });
+
+    expect(routes.map((r) => r.description)).toEqual(['Section one', 'T b']);
+    expect(warnings.length).toBe(2);
+  });
+
+  it('passes a page ogImage through', () => {
+    const manifest = { sections: [{ id: 'index', pages: ['a'] }], pages: { a: page('a', 'index', { ogImage: '/og/a.jpg' }) } };
+
+    expect(buildMarkdownSeoRoutes([{ id: 'c', seo: true }], { c: manifest }).routes[0].ogImage).toBe('/og/a.jpg');
+  });
+
+  it('with languages, emits per-language titles and descriptions from each manifest', () => {
+    const en = { sections: [{ id: 'index', pages: ['a'] }], pages: { a: page('a', 'index', { title: 'Hello', description: 'Hi' }) } };
+    const fr = { sections: [{ id: 'index', pages: ['a'] }], pages: { a: page('a', 'index', { title: 'Bonjour', description: 'Salut' }) } };
+
+    const { routes } = buildMarkdownSeoRoutes([{ id: 'c', seo: true }], { c: { en, fr } }, { languages: ['en', 'fr'], defaultLanguage: 'en' });
+
+    expect(routes).toEqual([
+      { path: '/c/:slug?', mockParams: { slug: 'a' }, title: { en: 'Hello', fr: 'Bonjour' }, description: { en: 'Hi', fr: 'Salut' } },
+    ]);
+  });
+});
+