docs: ввести DEVELOP.md как точку входа архива
All checks were successful
CI/CD Pipeline / docker (push) Successful in 1m18s
CI/CD Pipeline / deploy (push) Successful in 7s

- Удалена автогенерация README.md архива (buildArchiveReadme).
- Добавлен DEVELOP.md — точка входа с обязательным порядком
  чтения: архитектура → базовые правила → прикладные по задаче.
- Добавлен MAP.md — статичная карта со ссылками на все разделы.
- DEVELOP.md и MAP.md исключены из веб-сборки (srcExclude).
- DEVELOP.md исключён из копирования в docs/public/docs/.
- Удалено копирование llms-full.txt в архив (только для сайта).
- В CONTRIBUTING.md ссылка README.md заменена на MAP.md.
This commit is contained in:
2026-04-28 20:28:01 +03:00
parent 1195c7b75d
commit a6cd14585b
5 changed files with 180 additions and 79 deletions

View File

@@ -241,13 +241,20 @@ const copyDirSync = (
/**
* Скопировать все `.md`-файлы документации в `docs/public/docs/`,
* чтобы они попали в build `dist/` и были доступны по URL `/docs/path.md`.
*
* `DEVELOP.md` исключается — это точка входа архива, ссылается
* на офлайн-файлы (`MAP.md`), которых нет на сайте.
*/
const copyMdFiles = (): void => {
const srcDir = 'docs/docs';
const destDir = path.join(PUBLIC_DIR, 'docs');
if (!fs.existsSync(srcDir)) return;
const copied = copyDirSync(srcDir, destDir, (name) => name.endsWith('.md'));
const copied = copyDirSync(
srcDir,
destDir,
(name) => name.endsWith('.md') && name !== 'DEVELOP.md',
);
console.log(`скопировано ${copied} .md-файлов в ${destDir}`);
};
@@ -304,98 +311,31 @@ const transformLinksInDir = (rootDir: string): void => {
walk(rootDir);
};
/**
* Сгенерировать `README.md` — точка входа архива. Карта документации
* с относительными ссылками, описаниями из frontmatter/первого абзаца
* и метаинфо сборки.
*/
const buildArchiveReadme = (rootDir: string): void => {
const sidebar = cfg.themeConfig.sidebar;
const blockquote = cfg.llmsBlockquote ?? cfg.description ?? '';
const context = cfg.llmsContext;
const entries = flattenSidebar(sidebar).filter(
// «Главная» из sidebar — это страница раздела для веба, в архиве не нужна.
(e) => e.section !== 'Главная',
);
const grouped = groupBySection(entries);
const lines: string[] = [];
lines.push(`# ${cfg.title}`);
lines.push('');
if (blockquote) {
lines.push(`> ${blockquote}`);
lines.push('');
}
if (context) {
lines.push(context);
lines.push('');
}
lines.push('## Содержание');
lines.push('');
for (const [section, items] of grouped) {
lines.push(`### ${section}`);
lines.push('');
for (const entry of items) {
const targetRel = './' + linkToArchiveRel(entry.link);
const filePath = path.join(rootDir, linkToArchiveRel(entry.link));
let description: string | null = null;
if (fs.existsSync(filePath)) {
const raw = fs.readFileSync(filePath, 'utf8');
const { data, body } = parseFrontmatter(raw);
description = data.description || firstParagraphAfterH1(body);
}
const display = entry.prefix
? `${entry.prefix}: ${entry.text}`
: entry.text;
const descPart = description ? `${description}` : '';
lines.push(`- [${display}](${targetRel})${descPart}`);
}
lines.push('');
}
lines.push('---');
lines.push('');
lines.push(`Версия: ${VERSION} · Сборка: ${BUILD_DATE}`);
lines.push('');
fs.writeFileSync(path.join(rootDir, 'README.md'), lines.join('\n'), 'utf8');
};
/**
* Собрать `nextjs-style-guide.zip`. Внутри — папка `nextjs-style-guide/`
* с `.md`-файлами, README, `llms-full.txt` и `VERSION`. Внутренние ссылки
* преобразуются в относительные.
* с `.md`-файлами, DEVELOP.md (точка входа), MAP.md (навигационная карта)
* и `VERSION`. Внутренние ссылки преобразуются в относительные.
*
* Точка входа архива — `docs/docs/DEVELOP.md`, навигационная карта —
* `docs/docs/MAP.md`. Оба файла редактируются вручную и копируются
* в архив как есть.
*/
const buildZip = (): void => {
const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'nsg-'));
const stage = path.join(tmpRoot, 'nextjs-style-guide');
fs.mkdirSync(stage, { recursive: true });
// 1. Копируем все .md в staging.
// 1. Копируем все .md в staging (включая DEVELOP.md и MAP.md).
copyDirSync('docs/docs', stage, (name) => name.endsWith('.md'));
// 2. Удаляем веб-index.md — в архиве его роль выполняет README.md.
// 2. Удаляем веб-index.md — в архиве его роль выполняет DEVELOP.md.
const indexPath = path.join(stage, 'index.md');
if (fs.existsSync(indexPath)) fs.unlinkSync(indexPath);
// 3. Преобразуем абсолютные ссылки `/docs/...` в относительные.
transformLinksInDir(stage);
// 4. Генерируем точку входа README.md.
buildArchiveReadme(stage);
// 5. Кладём llms-full.txt — удобно для одноразового чтения LLM.
const llmsFullSrc = path.join(PUBLIC_DIR, 'llms-full.txt');
if (fs.existsSync(llmsFullSrc)) {
fs.copyFileSync(llmsFullSrc, path.join(stage, 'llms-full.txt'));
}
// 6. Метаинформация сборки.
// 4. Метаинформация сборки.
fs.writeFileSync(
path.join(stage, 'VERSION'),
`${VERSION}\n${BUILD_DATE}\n`,