@nutin/cli 2.1.1 → 3.0.0

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

@@ -4,18 +4,20 @@ 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__';
 
-// Only i18n builds serve every page under a language prefix — without it, "/" is a real page.
 function rootRedirect() {
   if (!nutinConfig.i18n) return '';
 
   const languagesConfigPath = path.join(process.cwd(), 'config', 'languages.json');
-  const { defaultLanguage } = JSON.parse(fs.readFileSync(languagesConfigPath, 'utf-8'));
-  return `location = / {\n        return 301 /${defaultLanguage}/$is_args$args;\n    }`;
+  const { languages, defaultLanguage } = JSON.parse(fs.readFileSync(languagesConfigPath, 'utf-8'));
+  return localeRedirects({ i18n: true, languages, defaultLanguage });
 }
 
 async function validateDocker() {
@@ -26,14 +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, rootRedirect()],
+    [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);
+  }
+}

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

@@ -0,0 +1,67 @@
+import { Navigation } from '#root/dist/src/core/index.js';
+import { MarkdownLandingComponent } from '#root/dist/src/app/markdown/components/markdown-landing/markdown-landing.component.js';
+
+const PAGES = {
+  a: { slug: 'a', title: 'Page A', description: 'About A' },
+  b: { slug: 'b', title: 'Page B', description: '' },
+};
+const manifest = { getPage: (slug) => PAGES[slug] };
+const pageHref = (slug) => `/docs/${slug}`;
+
+function mount(config) {
+  const target = document.createElement('div');
+  document.body.appendChild(target);
+  const component = new MarkdownLandingComponent(target, { title: 'Docs', description: 'Everything.', manifest, pageHref, ...config });
+  component.render();
+  return component;
+}
+
+const texts = (element, selector) => [...element.querySelectorAll(selector)].map((node) => node.textContent.trim());
+
+describe('MarkdownLandingComponent', () => {
+  it('lists a single hub\'s groups and pages, without repeating its title', () => {
+    const component = mount({ sections: [{ id: 'index', title: 'Docs', description: '', groups: [{ id: 'g', title: 'Basics', pages: ['a', 'b'] }] }] });
+    const element = component.getElement();
+    expect(element.querySelector('.markdown-landing__title').textContent).toBe('Docs');
+    expect(element.querySelector('.markdown-landing__section-title')).toBe(null);
+    expect(texts(element, '.markdown-landing__group-title')).toEqual(['Basics']);
+    expect(texts(element, '.markdown-landing__link')).toEqual(['Page A', 'Page B']);
+    expect(texts(element, '.markdown-landing__page-description')).toEqual(['About A']);
+    component.destroy();
+  });
+
+  it('heads each section when there are several', () => {
+    const component = mount({
+      sections: [
+        { id: 'api', title: 'API', description: 'The API.', pages: ['a'] },
+        { id: 'tools', title: 'Tools', description: '', pages: ['b'] },
+      ],
+    });
+    expect(texts(component.getElement(), '.markdown-landing__section-title')).toEqual(['API', 'Tools']);
+    expect(texts(component.getElement(), '.markdown-landing__section-description')).toEqual(['The API.']);
+    component.destroy();
+  });
+
+  it('links each section to its own landing when sectionHref is set', () => {
+    const component = mount({
+      sections: [{ id: 'api', title: 'API', description: 'The API.', pages: ['a'] }],
+      sectionHref: (id) => `/docs/${id}`,
+    });
+    const links = [...component.getElement().querySelectorAll('.markdown-landing__link')];
+    expect(links.map((a) => a.getAttribute('href'))).toEqual(['/docs/api']);
+    expect(component.getElement().querySelector('.markdown-landing__pages')).toBe(null);
+    component.destroy();
+  });
+
+  it('routes link clicks through the SPA router', () => {
+    const navigateSpy = spyOn(Navigation, 'navigateTo').andCallFake(() => {});
+    const component = mount({ sections: [{ id: 'index', title: 'Docs', description: '', pages: ['a'] }] });
+    try {
+      component.getElement().querySelector('.markdown-landing__link').click();
+    } finally {
+      navigateSpy.restore();
+    }
+    expect(navigateSpy.lastCall[0]).toBe('/docs/a');
+    component.destroy();
+  });
+});

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

@@ -0,0 +1,87 @@
+import { Component, Navigation, html, SafeHtml } from '../../../../core/index.js';
+import { IMarkdownGroup, IMarkdownSection, MarkdownManifest } from '../../markdown-manifest.js';
+
+export interface IMarkdownLandingConfig {
+  title: string;
+  description: string;
+  // Listed with their pages, or as links to their own landing when sectionHref is set.
+  sections: IMarkdownSection[];
+  manifest: MarkdownManifest;
+  pageHref: (slug: string) => string;
+  sectionHref?: (sectionId: string) => string;
+}
+
+// The landing's building blocks, exported so a custom template can reuse them.
+export function renderLandingPages(slugs: string[], config: IMarkdownLandingConfig): SafeHtml {
+  const items = slugs.map((slug) => {
+    const page = config.manifest.getPage(slug);
+    if (!page) return '';
+    return html`
+      <li class="markdown-landing__page">
+        <a href="${config.pageHref(slug)}" class="markdown-landing__link" data-event="click:_navigateTo:@attr:href">${page.title}</a>
+        ${page.description ? html`<p class="markdown-landing__page-description">${page.description}</p>` : ''}
+      </li>
+    `;
+  });
+  return html`<ul class="markdown-landing__pages">${items}</ul>`;
+}
+
+export function renderLandingGroup(group: IMarkdownGroup, config: IMarkdownLandingConfig): SafeHtml {
+  return html`
+    <div class="markdown-landing__group">
+      ${group.title ? html`<h3 class="markdown-landing__group-title">${group.title}</h3>` : ''}
+      ${renderLandingPages(group.pages, config)}
+    </div>
+  `;
+}
+
+// withHeading: false for the only section of a landing, whose title is already the page's.
+export function renderLandingSection(section: IMarkdownSection, config: IMarkdownLandingConfig, withHeading: boolean): SafeHtml {
+  const body = section.groups
+    ? section.groups.map((group) => renderLandingGroup(group, config))
+    : renderLandingPages(section.pages ?? [], config);
+  return html`
+    <section class="markdown-landing__section">
+      ${withHeading ? html`<h2 class="markdown-landing__section-title">${section.title}</h2>` : ''}
+      ${withHeading && section.description ? html`<p class="markdown-landing__section-description">${section.description}</p>` : ''}
+      ${body}
+    </section>
+  `;
+}
+
+export function renderLandingSectionLinks(config: IMarkdownLandingConfig): SafeHtml {
+  const sectionHref = config.sectionHref ?? ((id: string) => id);
+  return html`
+    <ul class="markdown-landing__sections">
+      ${config.sections.map((section) => html`
+        <li class="markdown-landing__section">
+          <a href="${sectionHref(section.id)}" class="markdown-landing__link" data-event="click:_navigateTo:@attr:href">${section.title}</a>
+          ${section.description ? html`<p class="markdown-landing__section-description">${section.description}</p>` : ''}
+        </li>
+      `)}
+    </ul>
+  `;
+}
+
+export const markdownLandingTemplate = (_config: IMarkdownLandingConfig) => html`
+  <div class="markdown-landing__body">
+    <h1 class="markdown-landing__title">${_config.title}</h1>
+    ${_config.description ? html`<p class="markdown-landing__description">${_config.description}</p>` : ''}
+    ${_config.sectionHref
+      ? renderLandingSectionLinks(_config)
+      : _config.sections.map((section) => renderLandingSection(section, _config, _config.sections.length > 1))}
+  </div>
+`;
+
+// The index shown on the bare route of a folder with "landing": its hub(s) and pages.
+export class MarkdownLandingComponent extends Component<HTMLElement, IMarkdownLandingConfig> {
+  // templateFn: your own template, e.g. built from the render helpers above.
+  constructor(mountTarget: HTMLElement, config: IMarkdownLandingConfig, templateFn: (config: IMarkdownLandingConfig) => Nutin.Template = markdownLandingTemplate) {
+    // Mounting replaces the placeholder element, so its class is set here.
+    super({ templateFn, mountTarget, config, props: { className: 'markdown-landing' } });
+  }
+
+  protected _navigateTo(href: string): void {
+    Navigation.navigateTo(href);
+  }
+}

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

@@ -0,0 +1,42 @@
+// :where() keeps these rules at zero specificity: see markdown.view.scss.
+:where(.markdown-nav__container) {
+  flex: 0 0 var(--markdown-nav-width, 16rem);
+}
+
+:where(.markdown-nav ul) {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+:where(.markdown-nav__section + .markdown-nav__section, .markdown-nav__group + .markdown-nav__group) {
+  margin-top: 1rem;
+}
+
+:where(.markdown-nav__section-title, .markdown-nav__group-title) {
+  display: block;
+  font-weight: bold;
+  margin-bottom: 0.25rem;
+}
+
+:where(.markdown-nav__group-title) {
+  font-size: 0.875rem;
+  opacity: 0.75;
+}
+
+:where(.markdown-nav__link) {
+  display: block;
+  padding: 0.25rem 0;
+}
+
+:where(.markdown-nav__link--active) {
+  font-weight: bold;
+}
+
+// Stacked above the content on narrow screens (see markdown.view.scss): the width
+// basis would otherwise become a fixed height.
+@media (max-width: 700px) {
+  :where(.markdown-nav__container) {
+    flex-basis: auto;
+  }
+}

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

@@ -0,0 +1,59 @@
+import { Navigation, html } from '#root/dist/src/core/index.js';
+import { MarkdownNavComponent, renderNavSection } from '#root/dist/src/app/markdown/components/markdown-nav/markdown-nav.component.js';
+
+const PAGES = { a: { slug: 'a', title: 'Page A' }, b: { slug: 'b', title: 'Page B' } };
+const manifest = { getPage: (slug) => PAGES[slug] };
+
+function mount(config, templateFn) {
+  const target = document.createElement('div');
+  document.body.appendChild(target);
+  const component = new MarkdownNavComponent(target, {
+    sections: [{ id: 'api', title: 'API', groups: [{ id: 'g', title: 'Group', pages: ['a', 'b', 'missing'] }] }],
+    manifest,
+    currentSlug: 'b',
+    pageHref: (slug) => `/docs/api/${slug}`,
+    ...config,
+  }, templateFn);
+  component.render();
+  return component;
+}
+
+describe('MarkdownNavComponent', () => {
+  it('lists sections, group titles and pages, skipping slugs without a page', () => {
+    const component = mount();
+    const element = component.getElement();
+    expect(element.querySelector('.markdown-nav__section-title').textContent).toBe('API');
+    expect(element.querySelector('.markdown-nav__group-title').textContent).toBe('Group');
+    expect([...element.querySelectorAll('.markdown-nav__link')].map((a) => a.getAttribute('href'))).toEqual(['/docs/api/a', '/docs/api/b']);
+    component.destroy();
+  });
+
+  it('marks the current page as active, with aria-current', () => {
+    const component = mount();
+    const active = component.getElement().querySelector('.markdown-nav__link--active');
+    expect(active.textContent).toBe('Page B');
+    expect(active.getAttribute('aria-current')).toBe('page');
+    expect(component.getElement().querySelectorAll('[aria-current]').length).toBe(1);
+    component.destroy();
+  });
+
+  it('routes a link click through the SPA router', () => {
+    const navigateSpy = spyOn(Navigation, 'navigateTo').andCallFake(() => {});
+    const component = mount();
+    try {
+      component.getElement().querySelector('[href="/docs/api/a"]').click();
+    } finally {
+      navigateSpy.restore();
+    }
+    expect(navigateSpy.lastCall[0]).toBe('/docs/api/a');
+    component.destroy();
+  });
+
+  it('accepts its own template, built from the exported render helpers', () => {
+    const component = mount({}, (config) => html`<ul class="my-nav">${config.sections.map((section) => renderNavSection(section, config))}</ul>`);
+    const element = component.getElement();
+    expect(element.querySelector('.my-nav .markdown-nav__section-title').textContent).toBe('API');
+    expect(element.querySelector('nav.markdown-nav')).toBe(null);
+    component.destroy();
+  });
+});

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

@@ -0,0 +1,72 @@
+import { Component, Navigation, html, raw, SafeHtml } from '../../../../core/index.js';
+import { IMarkdownGroup, IMarkdownSection, MarkdownManifest } from '../../markdown-manifest.js';
+import { markdownText } from '../../markdown-i18n.js';
+
+export interface IMarkdownNavConfig {
+  sections: IMarkdownSection[];
+  manifest: MarkdownManifest;
+  currentSlug: string;
+  pageHref: (slug: string) => string;
+}
+
+// The nav's building blocks, exported so a custom template can reuse them.
+// Links route through the component's _navigateTo (data-event).
+export function renderNavLink(slug: string, config: IMarkdownNavConfig): SafeHtml | string {
+  const page = config.manifest.getPage(slug);
+  if (!page) return '';
+
+  const current = slug === config.currentSlug;
+  return html`
+    <li>
+      <a
+        href="${config.pageHref(slug)}"
+        class="markdown-nav__link${current ? ' markdown-nav__link--active' : ''}"
+        ${current ? raw('aria-current="page"') : ''}
+        data-event="click:_navigateTo:@attr:href"
+      >${page.title}</a>
+    </li>
+  `;
+}
+
+export function renderNavGroup(group: IMarkdownGroup, config: IMarkdownNavConfig): SafeHtml {
+  const title = group.title ? html`<span class="markdown-nav__group-title">${group.title}</span>` : '';
+  return html`
+    <li class="markdown-nav__group">
+      ${title}
+      <ul class="markdown-nav__pages">${group.pages.map((slug) => renderNavLink(slug, config))}</ul>
+    </li>
+  `;
+}
+
+export function renderNavSection(section: IMarkdownSection, config: IMarkdownNavConfig): SafeHtml {
+  const items = section.groups
+    ? section.groups.map((group) => renderNavGroup(group, config))
+    : (section.pages ?? []).map((slug) => renderNavLink(slug, config));
+
+  return html`
+    <li class="markdown-nav__section">
+      <span class="markdown-nav__section-title">${section.title}</span>
+      <ul class="markdown-nav__groups">${items}</ul>
+    </li>
+  `;
+}
+
+export const markdownNavTemplate = (_config: IMarkdownNavConfig) => html`
+  <nav class="markdown-nav" aria-label="${markdownText('pages', 'Pages')}">
+    <ul class="markdown-nav__sections">
+      ${_config.sections.map((section) => renderNavSection(section, _config))}
+    </ul>
+  </nav>
+`;
+
+export class MarkdownNavComponent extends Component<HTMLElement, IMarkdownNavConfig> {
+  // templateFn: your own template, e.g. built from the render helpers above.
+  constructor(mountTarget: HTMLElement, config: IMarkdownNavConfig, templateFn: (config: IMarkdownNavConfig) => Nutin.Template = markdownNavTemplate) {
+    // Mounting replaces the placeholder element, so its class is re-applied here.
+    super({ templateFn, mountTarget, config, props: { className: 'markdown-nav__container' } });
+  }
+
+  protected _navigateTo(href: string): void {
+    Navigation.navigateTo(href);
+  }
+}

package/templates/features/markdown/src/app/markdown/locales/en.json.hbs

@@ -0,0 +1,6 @@
+{
+  "pages": "Pages",
+  "onThisPage": "On this page",
+  "empty": "Nothing here yet.",
+  "loadError": "This page couldn't be loaded."
+}