@nutin/cli 2.1.0 → 3.0.0

package/templates/base/tools/utils/run-command.js.hbs

@@ -1,8 +1,19 @@
 import { spawn } from 'child_process';
 
+const isWindows = process.platform === 'win32';
+
+// Windows needs a shell to launch .cmd shims (npm, tsc, ...); a single pre-quoted command
+// string avoids Node's deprecated args-array-with-shell form. Elsewhere no shell is
+// involved, so arguments containing spaces or shell characters are passed through as-is.
+function quoteForCmd(arg) {
+  return /[\s"&|<>^]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg;
+}
+
 export function runCommand(command, args = [], options = {}) {
   return new Promise((resolve, reject) => {
-    const child = spawn([command, ...args].join(' '), { stdio: 'inherit', shell: true, ...options });
+    const child = isWindows
+      ? spawn([command, ...args].map(quoteForCmd).join(' '), { stdio: 'inherit', shell: true, ...options })
+      : spawn(command, args, { stdio: 'inherit', ...options });
 
     child.on('error', (err) => reject(err));
 
@@ -12,3 +23,21 @@ export function runCommand(command, args = [], options = {}) {
     });
   });
 }
+
+// Like runCommand(), but collects the child's stdout and stderr (interleaved, in arrival order)
+// instead of printing them, and resolves with its exit code rather than rejecting: for a caller
+// that rewrites the output, e.g. compile-ts mapping tsc errors back to source files.
+export function captureCommand(command, args = [], options = {}) {
+  return new Promise((resolve, reject) => {
+    const stdio = ['inherit', 'pipe', 'pipe'];
+    const child = isWindows
+      ? spawn([command, ...args].map(quoteForCmd).join(' '), { stdio, shell: true, ...options })
+      : spawn(command, args, { stdio, ...options });
+
+    let output = '';
+    child.stdout.on('data', (chunk) => { output += chunk; });
+    child.stderr.on('data', (chunk) => { output += chunk; });
+    child.on('error', (err) => reject(err));
+    child.on('close', (code) => resolve({ code, output }));
+  });
+}

package/templates/base/tools/utils/run-command.test.js.hbs

@@ -1,4 +1,4 @@
-import { runCommand } from './run-command.js';
+import { runCommand, captureCommand } from './run-command.js';
 
 describe('runCommand', () => {
   it('resolves when the child process exits with code 0', async () => {
@@ -16,4 +16,15 @@ describe('runCommand', () => {
     expect(error).toBeDefined();
     expect(error.message).toContain('7');
   });
+
+  it('passes arguments containing spaces through unsplit', async () => {
+    await runCommand('node', ['-e', 'if (process.argv[1] !== "a b") process.exitCode = 1', 'a b']);
+  });
+
+  it('captureCommand resolves with the exit code and the collected stdout and stderr', async () => {
+    const { code, output } = await captureCommand('node', ['-e', 'console.log("out"); console.error("err"); process.exitCode = 2']);
+    expect(code).toBe(2);
+    expect(output).toContain('out');
+    expect(output).toContain('err');
+  });
 });

package/templates/base/tools/utils/run-script.js.hbs

@@ -1,7 +1,7 @@
 import { resolve } from 'path';
 import { spawnSync } from 'child_process';
 import process from 'process';
-import { print } from './index.js';
+import { print } from './print.js';
 
 export function runScript(path, message) {
   if (!message) print.boldSection(`Running ${path}...`);
@@ -9,7 +9,7 @@ export function runScript(path, message) {
 
   const args = [resolve(path), '--silent'];
 
-  const result = spawnSync('node', args,
+  const result = spawnSync(process.execPath, args,
     { 
       stdio: 'inherit',
       env: { ...process.env }, 

package/templates/features/docker/tools/docker/Dockerfile.template.hbs

@@ -1,5 +1,5 @@
-ARG NODE_VERSION=22.23.2
-ARG ALPINE_VERSION=3.20
+ARG NODE_VERSION=24.21.0
+ARG ALPINE_VERSION=3.24
 ARG PORT="__PORTS_PLACEHOLDER__"
 
 FROM node:${NODE_VERSION}-alpine AS builder
@@ -23,11 +23,14 @@ RUN {{ciCommand}} || pnpm approve-builds --all
 {{else}}
 RUN {{ciCommand}}
 {{/if}}
+{{#unless (eq lang "js")}}
 COPY tsconfig.json .
+{{/unless}}
 COPY ./src ./src
 COPY ./public ./public
 COPY ./nutin.config.js .
 COPY ./config ./config
+__MARKDOWN_SOURCES_PLACEHOLDER__
 COPY ./tools/builder ./tools/builder
 COPY ./tools/docker ./tools/docker
 COPY ./tools/utils ./tools/utils

package/templates/features/docker/tools/docker/nginx.conf.template

@@ -10,7 +10,7 @@ map $uri $content_type_options {
 }
 
 map $uri $xss_protection {
-    default "1; mode=block";
+    default "0";
 }
 
 map $uri $referrer_policy {
@@ -42,6 +42,11 @@ server {
     __PORTS_PLACEHOLDER__
     server_name _;
 
+    # Keep nginx's own automatic redirects (e.g. the missing-trailing-slash 301 on a
+    # prerendered route directory) relative, so they never leak this container's
+    # internal port/scheme when served behind a reverse proxy or a remapped port.
+    absolute_redirect off;
+
     # ---------------------------
     # ROOT + ROUTING
     # ---------------------------
@@ -51,6 +56,11 @@ server {
     # Hide nginx version
     server_tokens off;
 
+    # With i18n enabled, redirects "/" and unprefixed paths ("/docs") to the default
+    # language, so every served URL matches a page's canonical/og:url instead of
+    # returning a duplicate SPA shell (filled in by validate-docker).
+    __ROOT_REDIRECT_PLACEHOLDER__
+
     # SPA routing: serve index.html for unknown paths
     location / {
         try_files $uri $uri/ /index.html;
@@ -100,7 +110,8 @@ server {
     # ---------------------------
     # HEALTH ENDPOINT
     # ---------------------------
-    location /health {
+    # Exact match: it must win over the i18n unprefixed-path redirect (a regex location).
+    location = /health {
         access_log off;
         add_header Content-Type text/plain always;
         add_header Cache-Control "no-store" always;
@@ -112,6 +123,12 @@ server {
     # --------------------------
     error_page 404 /404.html;
 
+    # A route directory that exists on disk but has no index.html of its own (e.g. a
+    # parent route whose only prerendered pages are its children) makes try_files'
+    # $uri/ candidate match the directory and stop there, returning 403 instead of
+    # falling through to the SPA shell. Serve the shell for that case too.
+    error_page 403 = /index.html;
+
     location = /404.html {
         internal;
         try_files /404.html =404;

package/templates/features/docker/tools/docker/scripts/docker-ports.js.hbs

@@ -31,7 +31,7 @@ export function validateDockerPorts(rawPorts) {
     }
 
     if (port > MAX_PORT) {
-      throw new Error(`nutin.config.js: "dockerPorts[${i}]" (${port}) is in the OS ephemeral port range (49152-65535) — use a registered port between ${MIN_PORT} and ${MAX_PORT}.`);
+      throw new Error(`nutin.config.js: "dockerPorts[${i}]": use a registered port between ${MIN_PORT} and ${MAX_PORT}.`);
     }
 
     if (port < MIN_PORT || port > MAX_PORT) {

package/templates/features/docker/tools/docker/scripts/docker-ports.test.js.hbs

@@ -29,8 +29,8 @@ describe('validateDockerPorts', () => {
   });
 
   it('throws for ephemeral ports at or above 49152', () => {
-    expect(() => validateDockerPorts([49152])).toThrow('ephemeral port range');
-    expect(() => validateDockerPorts([60000])).toThrow('ephemeral port range');
+    expect(() => validateDockerPorts([49152])).toThrow('use a registered port');
+    expect(() => validateDockerPorts([60000])).toThrow('use a registered port');
   });
 
   it('throws for duplicate ports', () => {

package/templates/features/docker/tools/docker/scripts/locale-redirects.js.hbs

@@ -0,0 +1,28 @@
+// Language codes end up in an nginx regex and redirect target: letters, digits and "-" only (e.g. "pt-BR").
+const LANGUAGE_CODE = /^[A-Za-z0-9-]+$/;
+
+// Only i18n builds serve every page under a language prefix — without it, "/" and every
+// other path are real pages, and nothing is redirected.
+export function localeRedirects({ i18n, languages, defaultLanguage }) {
+  if (!i18n) return '';
+
+  [defaultLanguage, ...languages].forEach((lang) => {
+    if (typeof lang !== 'string' || !LANGUAGE_CODE.test(lang)) {
+      throw new Error(`config/languages.json: invalid language code ${JSON.stringify(lang)} — use letters, digits and "-" only (e.g. "en", "pt-BR").`);
+    }
+  });
+
+  // Unprefixed app paths (old or external links like "/docs") get a 301 to the default
+  // language instead of a 200 SPA shell that duplicates the real page. Paths with a "."
+  // (robots.txt, sitemap.xml, assets) are left to the other locations. $request_uri is
+  // the raw request (query included): the decoded $uri could inject headers via %0D%0A.
+  return [
+    `location = / {`,
+    `        return 301 /${defaultLanguage}/$is_args$args;`,
+    `    }`,
+    ``,
+    `    location ~ ^/(?!(?:${languages.join('|')})(?:/|$))[^.]*$ {`,
+    `        return 301 /${defaultLanguage}$request_uri;`,
+    `    }`,
+  ].join('\n');
+}

package/templates/features/docker/tools/docker/scripts/locale-redirects.test.js.hbs

@@ -0,0 +1,34 @@
+import { localeRedirects } from './locale-redirects.js';
+
+describe('localeRedirects', () => {
+  it('redirects nothing without i18n', () => {
+    expect(localeRedirects({ i18n: false, languages: ['en'], defaultLanguage: 'en' })).toBe('');
+  });
+
+  it('redirects "/" to the default language', () => {
+    const conf = localeRedirects({ i18n: true, languages: ['en', 'fr'], defaultLanguage: 'fr' });
+    expect(conf).toContain('location = / {\n        return 301 /fr/$is_args$args;\n    }');
+  });
+
+  it('redirects unprefixed, extensionless paths with the raw request URI', () => {
+    const conf = localeRedirects({ i18n: true, languages: ['en', 'fr'], defaultLanguage: 'en' });
+    expect(conf).toContain('location ~ ^/(?!(?:en|fr)(?:/|$))[^.]*$ {\n        return 301 /en$request_uri;\n    }');
+  });
+
+  it('only matches unprefixed, extensionless paths', () => {
+    const conf = localeRedirects({ i18n: true, languages: ['en', 'pt-BR'], defaultLanguage: 'en' });
+    const pattern = new RegExp(conf.match(/location ~ (\S+) \{/)[1]);
+
+    ['/docs', '/docs/', '/docs/api/x', '/english', '/enx/docs', '/pt-BRx'].forEach((path) => {
+      expect(pattern.test(path)).toBe(true);
+    });
+    ['/en', '/en/', '/en/docs/', '/pt-BR/docs', '/robots.txt', '/main.1a2b.css', '/assets/og.jpg'].forEach((path) => {
+      expect(pattern.test(path)).toBe(false);
+    });
+  });
+
+  it('throws on a language code that could break the nginx config', () => {
+    expect(() => localeRedirects({ i18n: true, languages: ['en', 'f r'], defaultLanguage: 'en' })).toThrow('invalid language code');
+    expect(() => localeRedirects({ i18n: true, languages: ['en'], defaultLanguage: 'en|.*' })).toThrow('invalid language code');
+  });
+});

package/templates/features/docker/tools/docker/scripts/markdown-sources-copy.js.hbs

@@ -0,0 +1,25 @@
+import path from 'path';
+
+// Markdown folders live outside src/ but build:prod compiles them, so the Docker
+// builder stage needs them too. Returns one COPY line per folder ('' without markdown).
+export function markdownSourcesCopy(sourceFolders, cwd = process.cwd()) {
+  const folders = (sourceFolders ?? [])
+    .map((entry) => (typeof entry === 'string' ? entry : entry?.folder))
+    .filter(Boolean);
+
+  const relativePaths = folders.map((folder) => {
+    const relative = path.relative(cwd, path.resolve(cwd, folder));
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      throw new Error(`Markdown folder "${folder}" is outside the project, so it can't be copied into the Docker image — move it inside the project.`);
+    }
+    return relative.split(path.sep).join('/');
+  });
+
+  // JSON form keeps folder names with spaces intact.
+  return [...new Set(relativePaths)]
+    .map((relative) => {
+      const target = `./${relative}`;
+      return `COPY ${JSON.stringify([target, target])}`;
+    })
+    .join('\n');
+}

package/templates/features/docker/tools/docker/scripts/markdown-sources-copy.test.js.hbs

@@ -0,0 +1,34 @@
+import path from 'path';
+import { markdownSourcesCopy } from './markdown-sources-copy.js';
+
+describe('markdownSourcesCopy', () => {
+  const cwd = path.resolve('/project');
+
+  it('returns an empty string without markdown folders', () => {
+    expect(markdownSourcesCopy(undefined, cwd)).toBe('');
+    expect(markdownSourcesCopy([], cwd)).toBe('');
+  });
+
+  it('returns one COPY line per folder, for string and object entries', () => {
+    expect(markdownSourcesCopy(['markdown-content', { folder: 'docs/guides' }], cwd)).toBe(
+      'COPY ["./markdown-content","./markdown-content"]\nCOPY ["./docs/guides","./docs/guides"]'
+    );
+  });
+
+  it('keeps folder names with spaces in a single path', () => {
+    expect(markdownSourcesCopy(['my docs'], cwd)).toBe('COPY ["./my docs","./my docs"]');
+  });
+
+  it('copies a folder once when it is listed with different spellings', () => {
+    expect(markdownSourcesCopy(['docs', './docs/', { folder: 'docs' }], cwd)).toBe('COPY ["./docs","./docs"]');
+  });
+
+  it('skips entries without a folder', () => {
+    expect(markdownSourcesCopy([null, {}, 'docs'], cwd)).toBe('COPY ["./docs","./docs"]');
+  });
+
+  it('throws for a folder outside the project', () => {
+    expect(() => markdownSourcesCopy(['../shared-docs'], cwd)).toThrow('"../shared-docs" is outside the project');
+    expect(() => markdownSourcesCopy([path.resolve('/elsewhere/docs')], cwd)).toThrow('is outside the project');
+  });
+});

package/templates/features/docker/tools/docker/scripts/render-docker-template.js.hbs

@@ -14,7 +14,9 @@ export async function renderFromTemplate(dockerDir, templateName, outputName, re
 
   for (const [placeholder, value] of replacements) {
     if (!content.includes(placeholder)) {
-      throw new Error(`tools/docker/${templateName} is missing the "${placeholder}" token — validate-docker has nothing to substitute. Restore the token or re-run "nutin-add docker".`);
+      // Nothing to insert: a template from before this token was added still renders.
+      if (value === '') continue;
+      throw new Error(`tools/docker/${templateName} is missing the "${placeholder}" token — validate-docker has nothing to substitute. Add the token back — "nutin-update" reports the current template's changes.`);
     }
     content = content.replace(placeholder, value);
   }

package/templates/features/docker/tools/docker/scripts/render-docker-template.test.js.hbs

@@ -46,6 +46,18 @@ describe('renderFromTemplate', () => {
     ).toThrow('missing.template');
   });
 
+  it('skips a missing placeholder token when its value is empty', async () => {
+    fs.writeFileSync(path.join(tmpDir, 'Dockerfile.template'), 'ARG PORT="__PORTS_PLACEHOLDER__"\n');
+
+    await renderFromTemplate(tmpDir, 'Dockerfile.template', 'Dockerfile', [
+      ['__PORTS_PLACEHOLDER__', '8080'],
+      ['__MARKDOWN_SOURCES_PLACEHOLDER__', ''],
+    ]);
+
+    const output = fs.readFileSync(path.join(tmpDir, 'Dockerfile'), 'utf-8');
+    expect(output).toBe('ARG PORT="8080"\n');
+  });
+
   it('throws when a placeholder token is missing from the template, without writing the output', async () => {
     fs.writeFileSync(path.join(tmpDir, 'nginx.conf.template'), 'listen 9090;\n');
 

package/templates/features/docker/tools/docker/scripts/validate-docker.js.hbs

@@ -1,11 +1,24 @@
+import fs from 'fs';
 import path from 'path';
 import { errorExit } from '../../utils/index.js';
 import nutinConfig from '../../../nutin.config.js';
 import { validateDockerPorts } from './docker-ports.js';
 import { renderFromTemplate } from './render-docker-template.js';
+import { markdownSourcesCopy } from './markdown-sources-copy.js';
+import { localeRedirects } from './locale-redirects.js';
 
 const DOCKER_DIR = path.join(process.cwd(), 'tools', 'docker');
 const PLACEHOLDER = '__PORTS_PLACEHOLDER__';
+const ROOT_REDIRECT_PLACEHOLDER = '__ROOT_REDIRECT_PLACEHOLDER__';
+const MARKDOWN_SOURCES_PLACEHOLDER = '__MARKDOWN_SOURCES_PLACEHOLDER__';
+
+function rootRedirect() {
+  if (!nutinConfig.i18n) return '';
+
+  const languagesConfigPath = path.join(process.cwd(), 'config', 'languages.json');
+  const { languages, defaultLanguage } = JSON.parse(fs.readFileSync(languagesConfigPath, 'utf-8'));
+  return localeRedirects({ i18n: true, languages, defaultLanguage });
+}
 
 async function validateDocker() {
   let ports;
@@ -15,13 +28,29 @@ async function validateDocker() {
     errorExit(err.message);
   }
 
+  let markdownCopy;
+  try {
+    markdownCopy = markdownSourcesCopy(nutinConfig.markdownSources?.sourceFolders);
+  } catch (err) {
+    errorExit(err.message);
+  }
+
   await renderFromTemplate(DOCKER_DIR, 'Dockerfile.template', 'Dockerfile', [
     [PLACEHOLDER, ports.join(' ')],
     ['__PRIMARY_PORT_PLACEHOLDER__', String(ports[0])],
+    [MARKDOWN_SOURCES_PLACEHOLDER, markdownCopy],
   ]).catch((err) => errorExit(err.message));
 
+  let redirects;
+  try {
+    redirects = rootRedirect();
+  } catch (err) {
+    errorExit(err.message);
+  }
+
   await renderFromTemplate(DOCKER_DIR, 'nginx.conf.template', 'nginx.conf', [
     [PLACEHOLDER, ports.map((port) => `listen ${port};`).join('\n    ')],
+    [ROOT_REDIRECT_PLACEHOLDER, redirects],
   ]).catch((err) => errorExit(err.message));
 }
 

package/templates/features/markdown/markdown-content/getting-started.md.hbs

@@ -0,0 +1,28 @@
+---
+title: Getting started
+description: Pages in this folder are compiled to /generated/markdown-content.json at build time.
+order: 1
+---
+
+# Getting started
+
+Pages in this folder are compiled to `/generated/markdown-content.json` at build time, then served at `/markdown-content` by `MarkdownView`.
+
+## Adding a page
+
+Create a `.md` file anywhere in `markdown-content/`. Its YAML frontmatter is optional:
+
+```yaml
+---
+title: My page        # defaults to the first "# Heading"
+description: Summary  # defaults to the first paragraph
+slug: my-page         # defaults to the file name
+order: 2              # pages are sorted by order, then by path
+group: Guides         # groups pages under a heading in the navigation
+---
+```
+
+## Linking pages
+
+Link to another page with its relative path, like [writing pages](./writing-pages.md) —
+the link becomes an in-app route. A link to a missing page fails the build.

package/templates/features/markdown/markdown-content/writing-pages.md.hbs

@@ -0,0 +1,19 @@
+---
+order: 2
+group: Guides
+---
+
+# Writing pages
+
+Markdown is compiled with [marked](https://marked.js.org/) (GitHub-flavored), so tables,
+fenced code blocks and task lists all work.
+
+## Headings
+
+Every `##` to `######` heading gets an `id`, and pages with two or more of them show an
+"On this page" table of contents.
+
+## Checking your content
+
+Run the `markdown:check` script to compile every folder without building the app: it fails
+on duplicate slugs and broken links between pages.

package/templates/features/markdown/src/app/markdown/components/markdown-content/markdown-content.component.scss.hbs

@@ -0,0 +1,75 @@
+// :where() keeps these rules at zero specificity: see markdown.view.scss.
+// A landing (.markdown-landing, .markdown-landing__body) shares the page's rules, so it
+// looks like the folder's pages and any restyling of them applies to it too.
+:where(.markdown-content, .markdown-landing) {
+  display: flex;
+  gap: var(--markdown-gap, 2rem);
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+:where(.markdown-content__body, .markdown-landing__body) {
+  flex: 1 1 auto;
+  min-width: 0;
+  line-height: var(--markdown-line-height, 1.7);
+}
+
+:where(.markdown-content__body pre) {
+  overflow-x: auto;
+}
+
+:where(.markdown-toc) {
+  flex: 0 0 var(--markdown-toc-width, 14rem);
+  font-size: 0.875rem;
+}
+
+:where(.markdown-toc ul) {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+:where(.markdown-toc__title) {
+  display: block;
+  font-weight: bold;
+  margin-bottom: 0.5rem;
+}
+
+:where(.markdown-toc__item--depth-3) {
+  padding-left: 1rem;
+}
+
+:where(.markdown-toc__item--depth-4, .markdown-toc__item--depth-5, .markdown-toc__item--depth-6) {
+  padding-left: 2rem;
+}
+
+// The landing's index: its sections and pages, with their descriptions.
+:where(.markdown-landing__pages, .markdown-landing__sections) {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+:where(.markdown-landing__page, .markdown-landing__sections > .markdown-landing__section) {
+  margin-bottom: 0.75rem;
+}
+
+:where(.markdown-landing__link) {
+  font-weight: bold;
+}
+
+:where(.markdown-landing__page-description, .markdown-landing__section-description) {
+  margin: 0.25rem 0 0;
+  opacity: 0.75;
+}
+
+@media (max-width: 900px) {
+  :where(.markdown-content, .markdown-landing) {
+    flex-direction: column;
+  }
+
+  :where(.markdown-toc) {
+    order: -1;
+    flex-basis: auto;
+  }
+}

package/templates/features/markdown/src/app/markdown/components/markdown-content/markdown-content.component.test.js.hbs

@@ -0,0 +1,40 @@
+import { MarkdownContentComponent } from '#root/dist/src/app/markdown/components/markdown-content/markdown-content.component.js';
+
+function mount(config) {
+  const target = document.createElement('div');
+  document.body.appendChild(target);
+  const component = new MarkdownContentComponent(target, config);
+  component.render();
+  return component;
+}
+
+describe('MarkdownContentComponent', () => {
+  it('shows the empty state when the folder has no page to show', () => {
+    const component = mount({});
+    expect(component.element.querySelector('.markdown-content__empty')).toBeTruthy();
+    expect(component.element.querySelector('.markdown-content__error')).toBe(null);
+    component.destroy();
+  });
+
+  it('shows an error, not the empty state, when the manifest failed to load', () => {
+    const component = mount({ loadFailed: true });
+    const error = component.element.querySelector('.markdown-content__error');
+    expect(error.getAttribute('role')).toBe('alert');
+    expect(error.textContent.trim()).not.toBe('');
+    expect(component.element.querySelector('.markdown-content__empty')).toBe(null);
+    component.destroy();
+  });
+
+  it('renders the page with its table of contents', () => {
+    const component = mount({
+      page: {
+        slug: 'a', title: 'A', description: '', section: 'index', group: null, order: 0, source: 'a.md',
+        html: '<h1 id="a">A</h1><h2 id="one">One</h2><h2 id="two">Two</h2>',
+        headings: [{ depth: 2, text: 'One', id: 'one' }, { depth: 2, text: 'Two', id: 'two' }],
+      },
+    });
+    expect(component.element.querySelector('.markdown-content__body h2#one')).toBeTruthy();
+    expect([...component.element.querySelectorAll('.markdown-toc a')].map((a) => a.getAttribute('href'))).toEqual(['#one', '#two']);
+    component.destroy();
+  });
+});

package/templates/features/markdown/src/app/markdown/components/markdown-content/markdown-content.component.ts.hbs

@@ -0,0 +1,65 @@
+import { Component, Navigation, html, trustedRaw, SafeHtml } from '../../../../core/index.js';
+import { IMarkdownHeading, IMarkdownPage } from '../../markdown-manifest.js';
+import { markdownText } from '../../markdown-i18n.js';
+
+export interface IMarkdownContentConfig {
+  page?: IMarkdownPage;
+  // The folder's manifest failed to load: shown as an error, not as an empty folder.
+  loadFailed?: boolean;
+  // Called after each render that shows a page (MarkdownView's "onContentRendered" option).
+  onRendered?: (element: HTMLElement, page: IMarkdownPage) => void;
+}
+
+// Exported so a custom template can reuse it.
+export function renderToc(headings: IMarkdownHeading[]): SafeHtml | string {
+  // A single heading adds nothing next to the page title — only worth a TOC at 2+.
+  if (headings.length <= 1) return '';
+
+  const items = headings
+    .map((heading) => html`
+      <li class="markdown-toc__item markdown-toc__item--depth-${heading.depth}">
+        <a href="#${heading.id}">${heading.text}</a>
+      </li>
+    `);
+
+  return html`
+    <nav class="markdown-toc" aria-label="${markdownText('onThisPage', 'On this page')}">
+      <span class="markdown-toc__title">${markdownText('onThisPage', 'On this page')}</span>
+      <ul>${items}</ul>
+    </nav>
+  `;
+}
+
+// page.html is compiled at build time from the project's own Markdown files (not user
+// input), hence trustLevel 'trusted'. With generateSEOFiles, every page is also prerendered
+// (tools/builder/core/markdown/markdown-seo-routes.js).
+export const markdownContentTemplate = (_config: IMarkdownContentConfig) => {
+  if (!_config.page) {
+    return _config.loadFailed
+      ? html`<p class="markdown-content__error" role="alert">${markdownText('loadError', "This page couldn't be loaded.")}</p>`
+      : html`<p class="markdown-content__empty">${markdownText('empty', 'Nothing here yet.')}</p>`;
+  }
+
+  return html`
+    <article class="markdown-content__body">${trustedRaw(_config.page.html)}</article>
+    ${renderToc(_config.page.headings)}
+  `;
+};
+
+export class MarkdownContentComponent extends Component<HTMLElement, IMarkdownContentConfig> {
+  // templateFn: your own template, e.g. built from renderToc() and the page's html.
+  constructor(mountTarget: HTMLElement, config: IMarkdownContentConfig, templateFn: (config: IMarkdownContentConfig) => Nutin.Template = markdownContentTemplate) {
+    // Mounting replaces the placeholder element, so its class is re-applied here.
+    super({ templateFn, mountTarget, config, trustLevel: 'trusted', props: { className: 'markdown-content' } });
+  }
+
+  protected override onAfterRender(): void {
+    if (this.config.page) this.config.onRendered?.(this.element, this.config.page);
+    super.onAfterRender();
+  }
+
+  // Internal links between pages carry data-event="click:_navigateTo:@attr:href".
+  protected _navigateTo(href: string): void {
+    Navigation.navigateTo(href);
+  }
+}