docs: ввести DEVELOP.md как точку входа архива
- Удалена автогенерация 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:
@@ -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`,
|
||||
|
||||
Reference in New Issue
Block a user