@ozdao/scriptorium 0.1.4 → 0.1.6

package/README.md

@@ -81,7 +81,8 @@ export default {
   skipped_names: ['node_modules', 'builds'], // папки, пропускаемые на любой глубине
   skipped_paths: [],                         // пути от корня репозитория; documentation/ пропускается всегда
   nav: [{ text: 'Обзор', link: '/' }],
-  sidebar: { priority: ['AGENTS.md'], folders_to_bottom: true, collapse_depth: 2, hidden: [] },
+  sidebar: { priority: ['AGENTS.md'], folders_to_bottom: true, collapse_depth: 2, hidden: [],
+             sort_by_date: [] },                // пути папок: страницы в них по дате, новые сверху (date из frontmatter или ГГГГ-ММ-ДД в конце имени; при равной — по добавлению в git)
   outline: { level: [2, 3], label: 'На странице' },
   labels: { menu: 'Меню', theme: 'Тема', top: 'Наверх', prev: 'Назад', next: 'Дальше', not_found: 'Страница не найдена', home: 'На главную' },
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ozdao/scriptorium",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",

package/src/content/markdown.js

@@ -32,10 +32,14 @@ const control_characters = /[\u0000-\u001f]/g;
 const special_characters = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'“”‘’<>,.?/]+/g;
 const combining_marks = /[̀-ͯ]/g;
 
+// Диакритика снимается только с латиницы (é → e), как у VitePress. Кириллица
+// остаётся целой: «й» и «ё» — отдельные буквы, а не «и» и «е» с надстрочным
+// знаком; без NFC обратно якорь «#семейства» не совпадал бы с заголовком.
 function slugify(text) {
   return text
     .normalize('NFKD')
-    .replace(combining_marks, '')
+    .replace(new RegExp(`(?<=[A-Za-z])${combining_marks.source}+`, 'g'), '')
+    .normalize('NFC')
     .replace(control_characters, '')
     .replace(special_characters, '-')
     .replace(/-{2,}/g, '-')

package/src/content/pages.loader.js

@@ -25,6 +25,7 @@ export default function pagesLoader() {
     file: ${JSON.stringify(page.file)},
     title: ${JSON.stringify(page.title)},
     frontmatter: ${JSON.stringify(page.frontmatter)},
+    added: ${JSON.stringify(page.added ?? null)},
     load: () => import(${JSON.stringify(`@docs/${page.file}`)}),
   }`);
 

package/src/content/scan.js

@@ -1,10 +1,12 @@
 // Обход репозитория документации: какие .md становятся страницами и по каким
 // адресам. Работает в node (loader'ы сборки), в бандл сайта не попадает.
+import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import matter from 'gray-matter';
 
+import { insideFolders } from './sidebar.js';
 import { resolveSiteConfig } from './site-config.js';
 
 // CLI запускается из папки documentation/ (как vitepress из папки сайта): она же
@@ -66,14 +68,45 @@ export function listMarkdown(docs_root, config) {
   return walk(docs_root, '');
 }
 
+// Время добавления файлов папок sidebar.sort_by_date, мс: коммит, которым файл
+// появился по этому пути в git — добавлен или перенесён (один вызов git log на все
+// папки); файл вне git или без git — время создания файла.
+function addedTimes(docs_root, files, folders) {
+  const added = new Map();
+  if (folders.length > 0) {
+    try {
+      const log = execFileSync('git', ['log', '--diff-filter=AR', '--relative', '--name-only', '--format=@%at', '--', ...folders], {
+        cwd: docs_root,
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+      });
+      let time = 0;
+      for (const line of log.split('\n')) {
+        if (line.startsWith('@')) time = Number(line.slice(1)) * 1000;
+        else if (line && !added.has(line)) added.set(line, time);
+      }
+    } catch {
+      // git нет или папка не в репозитории — время создания файла ниже
+    }
+  }
+  for (const file of files) {
+    if (!added.has(file)) added.set(file, fs.statSync(path.join(docs_root, file)).birthtimeMs);
+  }
+  return added;
+}
+
 // Страницы сайта: файл, адрес, подпись в сайдбаре (frontmatter.title, иначе имя
-// файла) и frontmatter. Два файла на один адрес (AGENTS.md и index.md одной
-// папки) — ошибка: какая из страниц настоящая, решает автор, а не порядок обхода.
+// файла), frontmatter и, для папок sidebar.sort_by_date, время добавления (added, мс).
+// Два файла на один адрес (AGENTS.md и index.md одной папки) — ошибка: какая из
+// страниц настоящая, решает автор, а не порядок обхода.
 export function scanPages(docs_root, config) {
   const pages = [];
   const file_of_url = new Map();
+  const files = listMarkdown(docs_root, config);
+  const sort_by_date = config.sidebar.sort_by_date;
+  const added = addedTimes(docs_root, files.filter((file) => insideFolders(file, sort_by_date)), sort_by_date);
 
-  for (const file of listMarkdown(docs_root, config)) {
+  for (const file of files) {
     const url = pageUrl(file);
     if (file_of_url.has(url)) {
       throw new Error(`[scriptorium] два файла на один адрес ${url}: ${file_of_url.get(url)} и ${file} — оставь один`);
@@ -94,6 +127,7 @@ export function scanPages(docs_root, config) {
         ? String(frontmatter.title)
         : path.posix.basename(file, '.md'),
       frontmatter,
+      ...(added.has(file) ? { added: added.get(file) } : {}),
     });
   }
 

package/src/content/sidebar.js

@@ -9,7 +9,11 @@
 //    корневой AGENTS.md — «Обзор» в шапке, в сайдбаре его нет;
 //  - папки из sidebar.hidden (по имени, на любой глубине) — страницы сайта, но
 //    не пункты сайдбара;
-//  - папка глубины collapse_depth и глубже изначально свёрнута.
+//  - папка глубины collapse_depth и глубже изначально свёрнута;
+//  - в папках sidebar.sort_by_date (пути от корня, на любой глубине) страницы
+//    идут по дате, новые сверху: date из frontmatter, иначе дата ГГГГ-ММ-ДД в конце
+//    имени файла; при равной дате — по времени добавления (added); без даты —
+//    после датированных, по имени.
 //
 // Узел: { text, url?, items?, collapsed }. url папки — адрес её AGENTS.md.
 
@@ -17,6 +21,29 @@ function isFolderIndex(file_name) {
   return file_name === 'AGENTS.md' || file_name === 'index.md';
 }
 
+// файл лежит в одной из папок (пути от корня репозитория) или глубже
+export function insideFolders(file, folders) {
+  return folders.some((folder) => file.startsWith(folder.replace(/\/$/, '') + '/'));
+}
+
+// дата страницы, мс: date из frontmatter, иначе ГГГГ-ММ-ДД в конце имени файла; нет — NaN
+function pageDate(page) {
+  const date = page.frontmatter?.date;
+  if (date !== undefined && date !== null && date !== '') return Date.parse(String(date));
+  const match = page.file.match(/(\d{4}-\d{2}-\d{2})\.md$/);
+  return match ? Date.parse(match[1]) : NaN;
+}
+
+// новые сверху: по дате, затем по времени добавления; без даты — в конец, по имени
+function newestFirst(a, b) {
+  const date_a = pageDate(a);
+  const date_b = pageDate(b);
+  if (Number.isNaN(date_a) !== Number.isNaN(date_b)) return Number.isNaN(date_a) ? 1 : -1;
+  if (!Number.isNaN(date_a) && date_a !== date_b) return date_b - date_a;
+  if ((a.added ?? 0) !== (b.added ?? 0)) return (b.added ?? 0) - (a.added ?? 0);
+  return a.file < b.file ? -1 : a.file > b.file ? 1 : 0;
+}
+
 function prioritize(names, priority) {
   const rank = new Map(priority.map((name, index) => [name, index]));
   const first = names.filter((name) => rank.has(name)).sort((a, b) => rank.get(a) - rank.get(b));
@@ -44,6 +71,15 @@ function folderTree(pages, hidden) {
 
 function folderItems(folder, depth, options) {
   const names = prioritize([...folder.files.keys(), ...folder.folders.keys()].sort(), options.priority);
+  const dated = [...folder.files.values()].filter((page) => insideFolders(page.file, options.sort_by_date)).sort(newestFirst);
+  if (dated.length > 0) {
+    // датированные страницы встают на места своих имён в порядке по дате
+    const slots = names.filter((name) => folder.files.has(name) && dated.includes(folder.files.get(name)));
+    let next = 0;
+    for (let index = 0; index < names.length; index += 1) {
+      if (slots.includes(names[index])) names[index] = dated[next++].file.split('/').pop();
+    }
+  }
   const items = [];
 
   for (const name of names) {
@@ -77,8 +113,8 @@ function folderItems(folder, depth, options) {
 }
 
 export function buildSidebar(pages, config) {
-  const { priority, folders_to_bottom, collapse_depth, hidden } = config.sidebar;
-  return folderItems(folderTree(pages, hidden), 1, { priority, folders_to_bottom, collapse_depth });
+  const { priority, folders_to_bottom, collapse_depth, hidden, sort_by_date } = config.sidebar;
+  return folderItems(folderTree(pages, hidden), 1, { priority, folders_to_bottom, collapse_depth, sort_by_date });
 }
 
 // Плоский порядок ссылок сайдбара для «Назад / Дальше»: ссылка папки идёт

package/src/content/site-config.js

@@ -79,6 +79,8 @@ export function resolveSiteConfig(raw) {
       folders_to_bottom: sidebar.folders_to_bottom ?? true,
       collapse_depth: sidebar.collapse_depth ?? 2,
       hidden: stringList(sidebar.hidden, 'sidebar.hidden'),
+      // пути папок от корня репозитория: файлы в них (на любой глубине) идут по дате, новые сверху
+      sort_by_date: stringList(sidebar.sort_by_date, 'sidebar.sort_by_date'),
     },
     outline: {
       level,