@ozdao/scriptorium 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+# @ozdao/scriptorium
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Сайт документации из папок markdown на @ozdao/martyrs (Vue 3, rspack, SSR). Все `.md` репозитория — страницы; `AGENTS.md` — индекс своей папки; адреса без `.md`.
+
+## Раскладка у пользователя
+
+Как у VitePress: сайт живёт в одной папке `documentation/` в корне репозитория документации, команды запускаются из неё. Страницы — все `.md` репозитория (папка над `documentation/`); сама `documentation/` в сайт не входит.
+
+```
+documentation/
+├── package.json     зависимости и скрипты сайта
+├── node_modules/    единственный node_modules репозитория документации
+├── config.js        конфиг сайта (обязателен)
+├── theme/           логотип, блок над страницей, стили (необязательно)
+├── public/          статика сайта: своё (favicon) + генерируемое сборкой
+└── builds/          сборка
+```
+
+Код сайта целиком в пакете (`node_modules/@ozdao/scriptorium`), туда при работе ничего не пишется. В корне репозитория документации `package.json` и `node_modules` нет.
+
+## Установка
+
+`documentation/package.json`:
+
+```json
+{
+  "name": "docs",
+  "private": true,
+  "type": "module",
+  "packageManager": "pnpm@10.8.0",
+  "scripts": {
+    "preinstall": "npx only-allow pnpm",
+    "dev": "scriptorium dev",
+    "build": "scriptorium build",
+    "start": "scriptorium start"
+  },
+  "devDependencies": {
+    "@ozdao/scriptorium": "0.1.0",
+    "@ozdao/martyrs": "0.2.609",
+    "vue": "3.5.42",
+    "vue-i18n": "11.4.10",
+    "vue-router": "5.3.0"
+  }
+}
+```
+
+`@ozdao/martyrs`, `vue`, `vue-router`, `vue-i18n` — peer-зависимости пакета, и указывать их обязательно. Сборка martyrs берёт `vue` из `documentation/node_modules/vue`, а шаблон service worker — из `documentation/node_modules/@ozdao/martyrs`. pnpm кладёт наверх `node_modules` только прямые зависимости проекта. Без явного указания этих пакетов там нет, и сборка падает.
+
+`packageManager: pnpm@10.8.0` нужен, как в шаблоне create-martyrs: pnpm 11 отказывается ставить git-зависимость martyrs (`uWebSockets.js`, `blockExoticSubdeps`) и передаёт установку pnpm 10.
+
+```bash
+cd documentation && pnpm install
+```
+
+## Запуск
+
+```bash
+cd documentation
+pnpm dev     # разработка, http://localhost:8200 (порт — PORT)
+pnpm build   # сборка в builds/
+pnpm start   # сервер по сборке
+```
+
+Команда запускается только из `documentation/`: там должны лежать `config.js` и `package.json`.
+
+## Конфиг
+
+`documentation/config.js` — обязателен:
+
+```js
+export default {
+  title: 'Docs', description: '', lang: 'ru-RU',
+  appearance: 'dark',                       // 'dark' | 'light' | 'auto'
+  skipped_names: ['node_modules', 'builds'], // папки, пропускаемые на любой глубине
+  skipped_paths: [],                         // пути от корня репозитория; documentation/ пропускается всегда
+  nav: [{ text: 'Обзор', link: '/' }],
+  sidebar: { priority: ['AGENTS.md'], folders_to_bottom: true, collapse_depth: 2, hidden: ['templates'] },
+  outline: { level: [2, 3], label: 'На странице' },
+  labels: { menu: 'Меню', theme: 'Тема', top: 'Наверх', prev: 'Назад', next: 'Дальше', not_found: 'Страница не найдена', home: 'На главную' },
+}
+```
+
+`documentation/theme/index.js` — необязателен: `export default { Logo, DocBefore }` (логотип в шапке, блок над содержимым страницы). Стили темы — импортом из этого файла. В компонентах темы:
+
+```js
+import { Badge, useDocs } from '@ozdao/scriptorium'
+const { page, frontmatter, config, pages } = useDocs()
+```
+
+`documentation/public/` отдаётся статикой раньше статики пакета: свой `favicon/` перекрывает умолчание.
+
+## Что генерируется
+
+Сборка martyrs пишет в `documentation/`. В `.gitignore` репозитория документации:
+
+```
+documentation/node_modules
+documentation/builds
+documentation/public/sw.js
+documentation/public/icon-sprite.svg
+documentation/public/fonts/
+documentation/.cache
+documentation/logs
+```
+
+- `builds/` — клиентская и серверная сборка;
+- `public/sw.js` — service worker в dev (в prod он лежит в `builds/web/client/`);
+- `public/icon-sprite.svg`, `public/fonts/` — спрайт иконок и шрифты martyrs; у документации своих исходников нет, файлы не появляются;
+- `.cache/martyrs-jit.css` — JIT-утилиты martyrs;
+- `logs/testid-duplicates.txt` — отчёт дублей `data-testid` dev-сборки.
+
+## Разработка пакета
+
+```bash
+pnpm install   # в корне пакета: pnpm-workspace.yaml разрешает install-скрипты
+```
+
+Подключение к репозиторию документации без публикации — `"@ozdao/scriptorium": "link:<путь к пакету>"` в `documentation/package.json`. При `link:` pnpm не ставит зависимости пакета в проект, поэтому peer-зависимости выше там тоже обязательны.
+
+Устройство: `bin/scriptorium.js` — CLI и сборка конфигов rspack поверх builder'а martyrs (корень приложения = `documentation/`, вход и сервер — файлы пакета); `src/` — приложение сайта (клиент, `server.js`, loader'ы markdown, списка страниц и индекса поиска).

package/bin/scriptorium.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+// CLI сайта документации: scriptorium <dev|build|start>, запуск из папки
+// documentation/ репозитория документации (как vitepress из папки сайта).
+//
+// documentation/ — корень приложения martyrs (builder/overlay.js берёт
+// process.cwd()): там package.json и node_modules с vue. Код сайта целиком
+// в пакете (src/), в node_modules ничего не пишется: сборка (builds/),
+// генерируемая статика (public/), кэш JIT (.cache/) — в documentation/.
+// Корень репозитория с .md — папка над documentation/.
+//
+// Этот же файл — скрипт dev-воркера бэкенда martyrs (builder/dev.js берёт
+// process.argv[1]). Воркер получает NODE_ENV и PORT в env от главного потока,
+// register — через --import; проверки и env ставит только главный поток.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isMainThread } from 'node:worker_threads';
+
+const environment_of_command = {
+  dev: 'development',
+  build: 'production',
+  start: 'production',
+};
+
+const command = process.argv[2];
+
+const docs_dir = process.cwd();
+const docs_root = path.resolve(docs_dir, '..');
+const public_dir = path.join(docs_dir, 'public');
+const theme_dir = path.join(docs_dir, 'theme');
+// Реальный путь: rspack сравнивает правила и include JIT с путями модулей
+// после разворота симлинков (pnpm, link:).
+const package_src = fs.realpathSync(fileURLToPath(new URL('../src', import.meta.url)));
+
+if (isMainThread) {
+  if (!environment_of_command[command]) {
+    console.error(`[scriptorium] неизвестная команда "${command ?? ''}". Запуск: scriptorium <${Object.keys(environment_of_command).join('|')}>`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(path.join(docs_dir, 'config.js'))) {
+    console.error(`[scriptorium] в ${docs_dir} нет config.js — запускай из папки documentation: cd documentation && pnpm ${command}`);
+    process.exit(1);
+  }
+
+  process.env.NODE_ENV = environment_of_command[command];
+  process.env.PORT = process.env.PORT || '8200';
+}
+
+// Бутстрап martyrs (env + резолв-хуки) — ПОСЛЕ NODE_ENV: register читает его
+// при загрузке. Хуки действуют на модули, загруженные после регистрации,
+// поэтому всё из martyrs — динамическими импортами.
+await import('@ozdao/martyrs/register');
+
+const { run, ssrClientConfig, ssrServerConfig } = await import('@ozdao/martyrs/builder');
+
+const configs = {
+  // Файл сервера — в пакете; раннер martyrs (builder/start.js) грузит его по
+  // абсолютному пути, корнем приложения остаётся documentation/.
+  server: path.join(package_src, 'server.js'),
+  ssr: {
+    client: ssrClientConfig(docs_dir, {
+      entry: path.join(package_src, 'client.js'),
+      output: path.join(docs_dir, 'builds/web/client'),
+    }),
+    server: ssrServerConfig(docs_dir, {
+      entry: path.join(package_src, 'client.js'),
+      output: path.join(docs_dir, 'builds/web/server'),
+    }),
+  },
+};
+
+const theme_file = path.join(theme_dir, 'index.js');
+
+for (const config of Object.values(configs.ssr)) {
+  // Loader'ы страниц и поиска следят за всем корнем репозитория (новые .md), а
+  // documentation/ лежит внутри него. Сборка сама пишет в builds/ (stats.json
+  // на каждую пересборку клиента), public/ и logs/ (отчёт testid) — без
+  // исключения клиент пересобирался бы по кругу. .cache/ не исключается:
+  // JIT-утилиты доезжают до сборки именно правкой файла .cache/martyrs-jit.css.
+  // node_modules и .git — умолчание rspack, при своём ignored его надо повторить.
+  config.watchOptions = {
+    ...config.watchOptions,
+    ignored: [
+      '**/node_modules/**',
+      '**/.git/**',
+      path.join(docs_dir, 'builds') + '/**',
+      path.join(docs_dir, 'public') + '/**',
+      path.join(docs_dir, 'logs') + '/**',
+    ],
+  };
+
+  // '@' базового конфига martyrs — <корень приложения>/src, у документации
+  // такой папки нет: алиас ведёт в исходники пакета.
+  config.resolve.alias['@'] = package_src;
+
+  // Тема потребителя необязательна: без файла импорт отдаёт пустой модуль, и
+  // сайт работает с текстовым заголовком вместо логотипа. Ключ — ДО
+  // '@docs-theme': алиасы проверяются в порядке объявления, и общий ключ
+  // перехватил бы запрос раньше («Cannot find module … for matched aliased key»).
+  if (!fs.existsSync(theme_file)) {
+    config.resolve.alias['@docs-theme/theme/index.js$'] = false;
+  }
+
+  // @docs — корень репозитория документации: страницы грузятся как '@docs/<файл>.md'.
+  // @docs-theme — конфиг и тема потребителя (documentation/).
+  config.resolve.alias['@docs'] = docs_root;
+  config.resolve.alias['@docs-theme'] = docs_dir;
+
+  config.module.rules.push(
+    // .md репозитория → Vue-компонент страницы + frontmatter и заголовки.
+    {
+      test: /\.md$/,
+      type: 'javascript/auto',
+      use: [{ loader: path.join(package_src, 'content/markdown.loader.js') }],
+    },
+    // Список страниц генерирует loader при сборке: модуль-заглушка pages.js
+    // получает код из скана папок документации.
+    {
+      test: path.join(package_src, 'content/pages.js'),
+      type: 'javascript/auto',
+      use: [{ loader: path.join(package_src, 'content/pages.loader.js') }],
+    },
+  );
+
+  // Индекс поиска — только в клиентской сборке: модуль-заглушка search-index.js
+  // получает JSON индекса по всем страницам. Render-бандл сервера берёт заглушку
+  // как есть — поиск открывается только в браузере.
+  if (config === configs.ssr.client) {
+    config.module.rules.push({
+      test: path.join(package_src, 'content/search-index.js'),
+      type: 'javascript/auto',
+      use: [{ loader: path.join(package_src, 'content/search-index.loader.js') }],
+    });
+  }
+
+  // Плагины martyrs узнаём по имени класса: экземпляры созданы builder'ом
+  // martyrs, а импорт классов отсюда мог бы дать другую копию модуля.
+  config.plugins = config.plugins.filter((plugin) => {
+    const name = plugin?.constructor?.name;
+
+    // Спрайт иконок и шрифты пишутся в documentation/public, а не в
+    // <корень приложения>/../public (корень репозитория). Исходников у
+    // документации нет (src/design-system/icons|fonts) — плагины ничего не
+    // пишут, путь нужен на случай, если появятся.
+    if (name === 'IconSpritePlugin' || name === 'FontsPlugin') plugin.options.publicDir = public_dir;
+
+    // JIT-утилиты martyrs собираются из файлов, путь которых содержит одну из
+    // строк include, и не содержит строк exclude (сравнение подстрокой).
+    // Умолчания рассчитаны на приложение с src/: 'src' и 'martyrs' в include,
+    // 'node_modules' в exclude. У документации код — в пакете, а пакет при
+    // установке из npm лежит в node_modules: исключение 'node_modules' убрало
+    // бы все его классы. Поэтому include — точные папки: исходники пакета,
+    // тема потребителя и сам martyrs; 'node_modules' из exclude убран. Весь
+    // documentation/ в include нельзя: туда входит documentation/node_modules.
+    if (name === 'MartyrsJitPlugin') {
+      plugin.options.include = ['@ozdao/martyrs', package_src, theme_dir];
+      plugin.options.exclude = plugin.options.exclude.filter((part) => part !== 'node_modules');
+    }
+
+    // Service worker сайту документации не нужен: его регистрирует только модуль
+    // notifications martyrs, которого здесь нет. Плагин в dev писал бы sw.js в
+    // <корень приложения>/../public — корень репозитория документации.
+    const is_service_worker = plugin?.constructor === Object && String(plugin.apply).includes('service-worker');
+    return !is_service_worker;
+  });
+}
+
+// Адреса ассетов (картинки .md, логотип темы) в SSR-HTML — от корня, как у
+// клиентской сборки (publicPath '/'). Без этого render-бандл печатал имя файла
+// относительным адресом: на /code/core/ картинка искалась в /code/core/, а
+// клиент при гидратации ставил другой адрес.
+configs.ssr.server.output.publicPath = '/';
+
+await run(command, configs);
+
+// Воркер бэкенда в dev (тот же файл, не главный поток) и сборка адрес не печатают.
+if (isMainThread && command !== 'build') {
+  console.log(`Docs: http://localhost:${process.env.PORT}`);
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@ozdao/scriptorium",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Documentation site generator on @ozdao/martyrs: markdown folders to an SSR site",
+  "author": "OZ DAO <hello@ozdao.com>",
+  "license": "GPL-3.0-or-later",
+  "type": "module",
+  "bin": {
+    "scriptorium": "./bin/scriptorium.js"
+  },
+  "exports": {
+    ".": "./src/main.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "public/",
+    "README.md"
+  ],
+  "dependencies": {
+    "@ozdao/martyrs": "0.2.609",
+    "@rspack/core": "2.2.2",
+    "@unhead/vue": "3.4.0",
+    "cookie-parser": "1.4.6",
+    "express": "5.2.1",
+    "gray-matter": "4.0.3",
+    "markdown-it": "15.0.2",
+    "markdown-it-anchor": "10.0.0",
+    "markdown-it-container": "4.0.0",
+    "minisearch": "7.2.0",
+    "shiki": "4.4.3",
+    "vue": "3.5.42",
+    "vue-i18n": "11.4.10",
+    "vue-router": "5.3.0"
+  },
+  "peerDependencies": {
+    "@ozdao/martyrs": "0.2.609",
+    "vue": "3.5.42",
+    "vue-i18n": "11.4.10",
+    "vue-router": "5.3.0"
+  }
+}

package/public/favicon/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#121212"/><path d="M9 8h11l3 3v13H9z" fill="none" stroke="#f5f5f5" stroke-width="2" stroke-linejoin="round"/><path d="M12 14h8M12 18h8M12 22h5" stroke="#f5f5f5" stroke-width="2" stroke-linecap="round"/></svg>

package/src/client.js

@@ -0,0 +1,29 @@
+// Дизайн-система сайта: база martyrs (слои @layer) + JIT-утилиты + тема сайта
+// + тема потребителя. Всё внутри design-system/index.js.
+import './design-system/index.js';
+
+import { createUniversalApp } from '@ozdao/martyrs/modules/core/client';
+
+import { getConfig } from './configs/client.config.js';
+import { getRouter } from './router/index.js';
+import { getLocales } from './localization/index.js';
+import { interceptLinks } from './router/links.js';
+
+const appPromise = createUniversalApp({
+  getConfig,
+  getRouter,
+  getLocales,
+  getHooks: {
+    // Ссылки внутри HTML страниц (markdown) и логотип потребителя — обычные <a>:
+    // переходы по ним внутри сайта идут роутером, без перезагрузки страницы.
+    afterInitialize: async (context) => {
+      if (typeof window !== 'undefined') interceptLinks(context.router);
+    },
+  },
+});
+
+export async function _renderApp({ url, cookies, headers, languages, ssrContext }) {
+  const { renderApp } = await appPromise;
+
+  return renderApp({ url, cookies, headers, languages, ssrContext });
+}

package/src/components/Badge.vue

@@ -0,0 +1,29 @@
+<script setup>
+// Бейдж как у VitePress (type: info | tip | warning | danger, text или слот) —
+// на бейдже дизайн-системы martyrs (.badge, elements.scss).
+import { computed } from 'vue';
+
+const props = defineProps({
+  type: {
+    type: String,
+    default: 'tip',
+  },
+  text: {
+    type: String,
+    default: '',
+  },
+});
+
+const modifier_of_type = {
+  info: 'info',
+  tip: 'success',
+  warning: 'warning',
+  danger: 'danger',
+};
+
+const modifier = computed(() => modifier_of_type[props.type] ?? 'default');
+</script>
+
+<template>
+  <span class="badge" :class="`badge--${modifier}`"><slot>{{ text }}</slot></span>
+</template>

package/src/components/HeaderNav.vue

@@ -0,0 +1,46 @@
+<script setup>
+// Ссылки nav из конфига — справа в шапке martyrs (header_right_component).
+// Активна ссылка текущего адреса, как у VitePress (точное совпадение). На
+// мобильном ссылки уходят в меню (SidebarTree).
+// Перед ссылками — кнопка поиска; окно поиска (SearchBox) живёт здесь же, как
+// VPNavBarSearch у VitePress: оно слушает горячие клавиши на любой странице.
+import { computed } from 'vue';
+import { useRoute } from 'vue-router';
+
+import site_config from '../configs/site.config.js';
+
+import SearchButton from './SearchButton.vue';
+import SearchBox from './SearchBox.vue';
+
+// Шапка martyrs передаёт theme — ссылкам он не нужен.
+defineOptions({ inheritAttrs: false });
+
+const route = useRoute();
+
+const current_url = computed(() => {
+  try {
+    return decodeURI(route.path);
+  } catch {
+    return route.path;
+  }
+});
+</script>
+
+<template>
+  <div class="flex flex-nowrap flex-v-center gap-medium">
+    <SearchButton />
+    <SearchBox />
+
+    <nav v-if="site_config.nav.length" class="docs-header-nav desktop-only">
+      <ul class="flex flex-nowrap flex-v-center gap-medium">
+        <li v-for="item in site_config.nav" :key="item.link">
+          <router-link
+            :to="item.link"
+            class="docs-header-nav__link"
+            :class="{ 'docs-header-nav__link--active': item.link === current_url }"
+          >{{ item.text }}</router-link>
+        </li>
+      </ul>
+    </nav>
+  </div>
+</template>

package/src/components/Layout.vue

@@ -0,0 +1,34 @@
+<script setup>
+// Раскладка страницы внутри layoutClient martyrs (шапку и сайдбар рисует он по
+// meta роута): колонка содержимого до 688px, оглавление справа на широком
+// экране, внизу «Назад / Дальше». Над содержимым — DocBefore темы потребителя.
+import theme from '@docs-theme/theme/index.js';
+
+import site_config from '../configs/site.config.js';
+
+import Outline from './Outline.vue';
+import PrevNext from './PrevNext.vue';
+
+const DocBefore = theme?.DocBefore ?? null;
+
+function scrollToTop() {
+  document.getElementById('scrollview')?.scrollTo({ top: 0, behavior: 'smooth' });
+}
+</script>
+
+<template>
+  <div class="docs-layout">
+    <article class="docs-layout__content">
+      <component v-if="DocBefore" :is="DocBefore" />
+      <slot />
+      <PrevNext />
+      <button type="button" class="docs-layout__top mobile-only mn-t-medium" @click="scrollToTop">
+        {{ site_config.labels.top }}
+      </button>
+    </article>
+
+    <aside class="docs-layout__outline">
+      <Outline />
+    </aside>
+  </div>
+</template>

package/src/components/Outline.vue

@@ -0,0 +1,74 @@
+<script setup>
+// Оглавление страницы: заголовки из loader'а (outline.level конфига, по
+// умолчанию h2–h3). Активный пункт — последний заголовок, верх которого уже
+// прошёл верхнюю кромку скроллера раскладки (#scrollview).
+import { ref, watch, onMounted, onBeforeUnmount, nextTick } from 'vue';
+
+import site_config from '../configs/site.config.js';
+import { useDocs } from '../content/use-docs.js';
+import { scrollToAnchor } from '../router/links.js';
+
+const { page } = useDocs();
+
+const active_slug = ref(null);
+let scrollview = null;
+
+// Заголовок считается прочитанным, когда он ближе этого к верху скроллера.
+const reading_offset = 96;
+
+function updateActive() {
+  if (!scrollview || !page.value) return;
+  const top = scrollview.getBoundingClientRect().top;
+  let current = null;
+
+  for (const header of page.value.headers) {
+    const element = document.getElementById(header.slug);
+    if (!element) continue;
+    if (element.getBoundingClientRect().top - top <= reading_offset) current = header.slug;
+    else break;
+  }
+
+  // Дочитали до конца — активен последний заголовок, даже если он не дошёл до верха.
+  if (scrollview.scrollTop + scrollview.clientHeight >= scrollview.scrollHeight - 2 && page.value.headers.length) {
+    current = page.value.headers[page.value.headers.length - 1].slug;
+  }
+
+  active_slug.value = current;
+}
+
+function openHeader(slug) {
+  if (scrollToAnchor(slug)) window.history.replaceState(window.history.state, '', `#${encodeURIComponent(slug)}`);
+}
+
+onMounted(() => {
+  scrollview = document.getElementById('scrollview');
+  scrollview?.addEventListener('scroll', updateActive, { passive: true });
+  updateActive();
+});
+
+onBeforeUnmount(() => {
+  scrollview?.removeEventListener('scroll', updateActive);
+});
+
+watch(() => page.value?.url, () => nextTick(updateActive));
+</script>
+
+<template>
+  <nav v-if="page && page.headers.length" class="docs-outline flex flex-column gap-thin" :aria-label="site_config.outline.label">
+    <p class="docs-outline__label">{{ site_config.outline.label }}</p>
+    <ul class="flex flex-column gap-thin">
+      <li
+        v-for="header in page.headers"
+        :key="header.slug"
+        :class="`docs-outline__level-${header.level - site_config.outline.level[0]}`"
+      >
+        <a
+          :href="`#${header.slug}`"
+          class="docs-outline__link"
+          :class="{ 'docs-outline__link--active': header.slug === active_slug }"
+          @click.prevent="openHeader(header.slug)"
+        >{{ header.title }}</a>
+      </li>
+    </ul>
+  </nav>
+</template>

package/src/components/Page.vue

@@ -0,0 +1,33 @@
+<script setup>
+// Страница документации по адресу. Модуль страницы уже загружен гардом роутера
+// (router/index.js) — и на сервере, и на клиенте до гидратации, — здесь только
+// рендер. Адреса без страницы — 404 со ссылкой на главную.
+import { computed } from 'vue';
+import { useHead } from '@unhead/vue';
+
+import site_config from '../configs/site.config.js';
+import { useDocs } from '../content/use-docs.js';
+import { pageComponent } from '../content/current-page.js';
+
+import Layout from './Layout.vue';
+
+const { page } = useDocs();
+
+const content = computed(() => (page.value ? pageComponent(page.value.url) : null));
+
+useHead({
+  title: computed(() => `${page.value ? page.value.title : '404'} — ${site_config.title}`),
+});
+</script>
+
+<template>
+  <Layout v-if="content" :key="page.url">
+    <component :is="content" />
+  </Layout>
+
+  <section v-else class="docs-not-found flex flex-column gap-medium pd-semi">
+    <h1>404</h1>
+    <p class="t-secondary">{{ site_config.labels.not_found }}</p>
+    <router-link to="/" class="docs-not-found__home">{{ site_config.labels.home }}</router-link>
+  </section>
+</template>

package/src/components/PrevNext.vue

@@ -0,0 +1,37 @@
+<script setup>
+// «Назад / Дальше» в порядке сайдбара — как у VitePress: плоский список ссылок
+// сайдбара (ссылка папки перед её содержимым). Страница вне сайдбара (главная,
+// скрытые папки) получает только «Дальше» — первый пункт сайдбара.
+import { computed } from 'vue';
+
+import site_config from '../configs/site.config.js';
+import { useDocs } from '../content/use-docs.js';
+import { buildSidebar, flattenSidebar } from '../content/sidebar.js';
+
+const { page, pages } = useDocs();
+
+const links = flattenSidebar(buildSidebar(pages, site_config));
+
+const neighbours = computed(() => {
+  const index = links.findIndex((link) => link.url === page.value?.url);
+  return {
+    prev: index > 0 ? links[index - 1] : null,
+    next: index === -1 ? links[0] ?? null : links[index + 1] ?? null,
+  };
+});
+</script>
+
+<template>
+  <nav v-if="neighbours.prev || neighbours.next" class="docs-prev-next mn-t-semi pd-t-medium gap-small">
+    <router-link v-if="neighbours.prev" :to="neighbours.prev.url" class="docs-prev-next__link flex flex-column gap-thin pd-small radius-small">
+      <span class="docs-prev-next__label">{{ site_config.labels.prev }}</span>
+      <span class="docs-prev-next__title">{{ neighbours.prev.text }}</span>
+    </router-link>
+    <span v-else />
+
+    <router-link v-if="neighbours.next" :to="neighbours.next.url" class="docs-prev-next__link docs-prev-next__link--next flex flex-column gap-thin pd-small radius-small">
+      <span class="docs-prev-next__label">{{ site_config.labels.next }}</span>
+      <span class="docs-prev-next__title">{{ neighbours.next.text }}</span>
+    </router-link>
+  </nav>
+</template>