Compare commits
2 Commits
74cbd43a23
...
7965ec2a96
| Author | SHA1 | Date | |
|---|---|---|---|
| 7965ec2a96 | |||
| 7c224fed99 |
@@ -56,11 +56,6 @@ const sidebar = [
|
||||
{ text: 'Структура проекта', link: '/docs/usage/project-structure' },
|
||||
{ text: 'Компоненты', link: '/docs/usage/components' },
|
||||
{ text: 'Страницы (App Router)', link: '/docs/usage/page-level' },
|
||||
{ text: 'Шаблоны и генерация кода', link: '/docs/usage/templates-generation' },
|
||||
{ text: 'Стили', link: '/docs/usage/styles' },
|
||||
{ text: 'Изображения', link: '/docs/usage/images-sprites' },
|
||||
{ text: 'SVG-спрайты', link: '/docs/usage/svg-sprites' },
|
||||
{ text: 'Видео', link: '/docs/usage/video' },
|
||||
{
|
||||
text: 'Данные',
|
||||
collapsed: true,
|
||||
@@ -91,10 +86,17 @@ const sidebar = [
|
||||
{ text: 'Realtime', link: '/docs/usage/data/realtime' },
|
||||
],
|
||||
},
|
||||
{ text: 'Stores', link: '/docs/usage/stores' },
|
||||
{ text: 'Хуки', link: '/docs/usage/hooks' },
|
||||
{ text: 'Шрифты', link: '/docs/usage/fonts' },
|
||||
{ text: 'Локализация', link: '/docs/usage/localization' },
|
||||
{ text: 'Шаблоны и генерация кода', link: '/docs/usage/templates-generation' },
|
||||
{ text: 'Стили', link: '/docs/usage/styles' },
|
||||
// Неактивные разделы: страницы существуют, но пока пустые.
|
||||
// Оставляем в sidebar без `link`, чтобы видеть план, но без перехода.
|
||||
{ text: 'Изображения · в разработке' },
|
||||
{ text: 'SVG-спрайты', link: '/docs/usage/svg-sprites' },
|
||||
{ text: 'Видео · в разработке' },
|
||||
{ text: 'Stores · в разработке' },
|
||||
{ text: 'Хуки · в разработке' },
|
||||
{ text: 'Шрифты · в разработке' },
|
||||
{ text: 'Локализация · в разработке' },
|
||||
],
|
||||
},
|
||||
|
||||
|
||||
65
README.md
65
README.md
@@ -2,34 +2,24 @@
|
||||
|
||||
Соглашения по разработке Next.js проектов: архитектура и слои приложения, структура кода, организация модулей, стилизация, типизация и инфраструктура.
|
||||
|
||||
Сайт: https://nextjs-style-guide.gromlab.ru
|
||||
|
||||
## Использование
|
||||
|
||||
**Для AI-агентов:**
|
||||
|
||||
- [llms.txt](/llms.txt) — Карта разделов, оглавление со ссылками на разделы.
|
||||
- [llms-full.txt](/llms-full.txt) — Вся документация одним файлом.
|
||||
- [llms.txt](https://nextjs-style-guide.gromlab.ru/llms.txt) — Карта разделов, оглавление со ссылками на разделы.
|
||||
- [llms-full.txt](https://nextjs-style-guide.gromlab.ru/llms-full.txt) — Вся документация одним файлом.
|
||||
|
||||
**Для проекта:**
|
||||
|
||||
- [nextjs-style-guide.zip](/nextjs-style-guide.zip) — Набор Markdown-файлов для распаковки в `./ai/nextjs-style-guide/` или другую папку проекта.
|
||||
- [nextjs-style-guide.zip](https://nextjs-style-guide.gromlab.ru/nextjs-style-guide.zip) — Набор Markdown-файлов для распаковки в `./ai/nextjs-style-guide/` или другую папку проекта.
|
||||
|
||||
## Структура документации
|
||||
|
||||
### Workflow
|
||||
|
||||
**Что делать и в каком порядке** — пошаговые инструкции.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Начало работы | Что нужно знать перед началом разработки? |
|
||||
| Создание проекта | Как начать новый проект? |
|
||||
| Генерация кода | Какие модули должны генерироваться из шаблонов? |
|
||||
| Добавление страницы | Как добавить новую страницу в проект? |
|
||||
| Добавление UI-модуля | Как создать компонент, бизнес-модуль, виджет или layout? |
|
||||
| Стилизация | Как стилизовать компоненты в проекте? |
|
||||
| Получение данных | Как получать данные с сервера? |
|
||||
| Управление состоянием | Как работать с состоянием? |
|
||||
| Локализация | Как добавлять переводы и подключать локализацию? |
|
||||
[Workflow](docs/docs/workflow.md) — пошаговая карта типовых задач: с чего начать, как добавить страницу/компонент, как подключить данные, стили, локализацию.
|
||||
|
||||
### Базовые правила
|
||||
|
||||
@@ -38,32 +28,53 @@
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Технологии и библиотеки | Какой стек используем? |
|
||||
| Архитектура | Как устроены слои SLM, зависимости, публичный API? |
|
||||
| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
|
||||
| Именование | Как называть файлы, переменные, компоненты, хуки? |
|
||||
| Архитектура: Обзор | Что такое SLM и зачем она нужна? |
|
||||
| Архитектура: Слои | Какие слои есть и как между ними устроены зависимости? |
|
||||
| Архитектура: Модули | Что такое модуль и как он устроен? |
|
||||
| Архитектура: Сегменты | Какие сегменты есть внутри модуля? |
|
||||
| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
|
||||
| Документирование | Как писать JSDoc: что документировать, а что нет? |
|
||||
| Типизация | Как типизировать: type vs interface, any/unknown? |
|
||||
|
||||
### Прикладные разделы
|
||||
### Установка и настройка
|
||||
|
||||
**Как это настроить и использовать** — конфигурация, структура и примеры кода для конкретных областей.
|
||||
**Как поднять и сконфигурировать проект** — пошаговая настройка инструментов и инфраструктуры.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Создание проекта: Из шаблона | Как начать проект из готового шаблона? |
|
||||
| Создание проекта: Вручную | Как поднять проект с нуля без шаблона? |
|
||||
| Next.js | Как настроить Next.js под проект? |
|
||||
| Алиасы | Как настроить путевые алиасы импортов? |
|
||||
| Biome | Как настроить Biome (линтер и форматер)? |
|
||||
| Стили | Как подключить и настроить стили проекта? |
|
||||
| PostCSS | Какие плагины PostCSS нужны и как их настроить? |
|
||||
| SVG-спрайты | Как настроить генерацию SVG-спрайтов? |
|
||||
| Шаблоны генерации | Как подключить шаблоны для кодогенерации? |
|
||||
| VS Code | Как настроить редактор для проекта? |
|
||||
|
||||
### Использование
|
||||
|
||||
**Как это устроено и как этим пользоваться** — структура, примеры и правила для конкретных областей.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Настройка VS Code | Как настроить редактор для проекта? |
|
||||
| Структура проекта | Как организованы папки и файлы по SLM? |
|
||||
| Компоненты | Как устроен компонент: файлы, пропсы, clsx? |
|
||||
| Page-level компоненты | Как описывать layout, page, loading, error, not-found? |
|
||||
| Страницы (App Router) | Как описывать layout, page, loading, error, not-found? |
|
||||
| Данные: Введение | Как устроена работа с данными в проекте? |
|
||||
| Данные: REST: Клиенты: Автоматическая генерация | Как сгенерировать REST-клиент автоматически из OpenAPI? |
|
||||
| Данные: REST: Клиенты: Ручная генерация | Как написать REST-клиент вручную? |
|
||||
| Данные: REST: Получение данных: Серверные компоненты | Как получать данные в серверных компонентах? |
|
||||
| Данные: REST: Получение данных: Клиентские компоненты | Как получать данные в клиентских компонентах (SWR)? |
|
||||
| Данные: Realtime | Как работать с realtime-каналами и сокетами? |
|
||||
| Шаблоны и генерация кода | Как работают шаблоны, синтаксис и инструменты генерации? |
|
||||
| Стили | Как писать CSS: PostCSS Modules, вложенность, медиа, токены? |
|
||||
| Изображения | _(не заполнен)_ |
|
||||
| SVG-спрайты | _(не заполнен)_ |
|
||||
| SVG-спрайты | Как использовать SVG-спрайты в коде? |
|
||||
| Видео | _(не заполнен)_ |
|
||||
| API | _(не заполнен)_ |
|
||||
| Stores | _(не заполнен)_ |
|
||||
| Хуки | _(не заполнен)_ |
|
||||
| Шрифты | _(не заполнен)_ |
|
||||
| Локализация | _(не заполнен)_ |
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -17,19 +17,7 @@
|
||||
|
||||
### Workflow
|
||||
|
||||
**Что делать и в каком порядке** — пошаговые инструкции.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Начало работы | Что нужно знать перед началом разработки? |
|
||||
| Создание проекта | Как начать новый проект? |
|
||||
| Генерация кода | Какие модули должны генерироваться из шаблонов? |
|
||||
| Добавление страницы | Как добавить новую страницу в проект? |
|
||||
| Добавление UI-модуля | Как создать компонент, бизнес-модуль, виджет или layout? |
|
||||
| Стилизация | Как стилизовать компоненты в проекте? |
|
||||
| Получение данных | Как получать данные с сервера? |
|
||||
| Управление состоянием | Как работать с состоянием? |
|
||||
| Локализация | Как добавлять переводы и подключать локализацию? |
|
||||
[Workflow](/docs/workflow) — пошаговая карта типовых задач: с чего начать, как добавить страницу/компонент, как подключить данные, стили, локализацию.
|
||||
|
||||
### Базовые правила
|
||||
|
||||
@@ -38,32 +26,53 @@
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Технологии и библиотеки | Какой стек используем? |
|
||||
| Архитектура | Как устроены слои SLM, зависимости, публичный API? |
|
||||
| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
|
||||
| Именование | Как называть файлы, переменные, компоненты, хуки? |
|
||||
| Архитектура: Обзор | Что такое SLM и зачем она нужна? |
|
||||
| Архитектура: Слои | Какие слои есть и как между ними устроены зависимости? |
|
||||
| Архитектура: Модули | Что такое модуль и как он устроен? |
|
||||
| Архитектура: Сегменты | Какие сегменты есть внутри модуля? |
|
||||
| Стиль кода | Как оформлять код: отступы, кавычки, импорты, early return? |
|
||||
| Документирование | Как писать JSDoc: что документировать, а что нет? |
|
||||
| Типизация | Как типизировать: type vs interface, any/unknown? |
|
||||
|
||||
### Прикладные разделы
|
||||
### Установка и настройка
|
||||
|
||||
**Как это настроить и использовать** — конфигурация, структура и примеры кода для конкретных областей.
|
||||
**Как поднять и сконфигурировать проект** — пошаговая настройка инструментов и инфраструктуры.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Создание проекта: Из шаблона | Как начать проект из готового шаблона? |
|
||||
| Создание проекта: Вручную | Как поднять проект с нуля без шаблона? |
|
||||
| Next.js | Как настроить Next.js под проект? |
|
||||
| Алиасы | Как настроить путевые алиасы импортов? |
|
||||
| Biome | Как настроить Biome (линтер и форматер)? |
|
||||
| Стили | Как подключить и настроить стили проекта? |
|
||||
| PostCSS | Какие плагины PostCSS нужны и как их настроить? |
|
||||
| SVG-спрайты | Как настроить генерацию SVG-спрайтов? |
|
||||
| Шаблоны генерации | Как подключить шаблоны для кодогенерации? |
|
||||
| VS Code | Как настроить редактор для проекта? |
|
||||
|
||||
### Использование
|
||||
|
||||
**Как это устроено и как этим пользоваться** — структура, примеры и правила для конкретных областей.
|
||||
|
||||
| Раздел | Отвечает на вопрос |
|
||||
|--------|-------------------|
|
||||
| Настройка VS Code | Как настроить редактор для проекта? |
|
||||
| Структура проекта | Как организованы папки и файлы по SLM? |
|
||||
| Компоненты | Как устроен компонент: файлы, пропсы, clsx? |
|
||||
| Page-level компоненты | Как описывать layout, page, loading, error, not-found? |
|
||||
| Страницы (App Router) | Как описывать layout, page, loading, error, not-found? |
|
||||
| Данные: Введение | Как устроена работа с данными в проекте? |
|
||||
| Данные: REST: Клиенты: Автоматическая генерация | Как сгенерировать REST-клиент автоматически из OpenAPI? |
|
||||
| Данные: REST: Клиенты: Ручная генерация | Как написать REST-клиент вручную? |
|
||||
| Данные: REST: Получение данных: Серверные компоненты | Как получать данные в серверных компонентах? |
|
||||
| Данные: REST: Получение данных: Клиентские компоненты | Как получать данные в клиентских компонентах (SWR)? |
|
||||
| Данные: Realtime | Как работать с realtime-каналами и сокетами? |
|
||||
| Шаблоны и генерация кода | Как работают шаблоны, синтаксис и инструменты генерации? |
|
||||
| Стили | Как писать CSS: PostCSS Modules, вложенность, медиа, токены? |
|
||||
| Изображения | _(не заполнен)_ |
|
||||
| SVG-спрайты | _(не заполнен)_ |
|
||||
| SVG-спрайты | Как использовать SVG-спрайты в коде? |
|
||||
| Видео | _(не заполнен)_ |
|
||||
| API | _(не заполнен)_ |
|
||||
| Stores | _(не заполнен)_ |
|
||||
| Хуки | _(не заполнен)_ |
|
||||
| Шрифты | _(не заполнен)_ |
|
||||
| Локализация | _(не заполнен)_ |
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -547,6 +547,29 @@ const buildSitemap = (): void => {
|
||||
console.log(`${PUBLIC_DIR}/sitemap.xml создан`);
|
||||
};
|
||||
|
||||
/**
|
||||
* Преобразовать абсолютные ссылки `index.md` в рабочие при открытии
|
||||
* README в репозитории:
|
||||
* - `/docs/foo` → относительный путь `docs/docs/foo.md`;
|
||||
* - корневые ресурсы (`/llms.txt`, `/llms-full.txt`, `*.zip`, `/manifest.json`,
|
||||
* `/sitemap.xml`, `/robots.txt`) — генерируемые, в репозитории отсутствуют,
|
||||
* поэтому ссылки переписываются на абсолютный `SITE_URL`.
|
||||
*/
|
||||
const transformReadmeLinks = (content: string): string => {
|
||||
const linkRe = /\]\((\/[^)\s]*)\)/g;
|
||||
return content.replace(linkRe, (match, href: string) => {
|
||||
const [pathPart, hash = ''] = href.split('#');
|
||||
const hashPart = hash ? `#${hash}` : '';
|
||||
|
||||
if (pathPart.startsWith(DOC_PREFIX)) {
|
||||
const rel = linkToArchiveRel(pathPart);
|
||||
return `](docs/docs/${rel}${hashPart})`;
|
||||
}
|
||||
|
||||
return `](${SITE_URL}${pathPart}${hashPart})`;
|
||||
});
|
||||
};
|
||||
|
||||
/** Скопировать `index.md` документации в корневой README без frontmatter. */
|
||||
const buildReadme = (): void => {
|
||||
const indexPath = 'docs/docs/index.md';
|
||||
@@ -556,7 +579,15 @@ const buildReadme = (): void => {
|
||||
}
|
||||
const raw = fs.readFileSync(indexPath, 'utf8');
|
||||
const { body } = parseFrontmatter(raw);
|
||||
fs.writeFileSync('README.md', body.trimStart(), 'utf8');
|
||||
const transformed = transformReadmeLinks(body.trimStart());
|
||||
|
||||
// Порядок: H1 → описание (первый абзац) → ссылка на сайт.
|
||||
const withSiteLink = transformed.replace(
|
||||
/^(#\s[^\n]*\n\n[^\n]+\n)/,
|
||||
`$1\nСайт: ${SITE_URL}\n`,
|
||||
);
|
||||
|
||||
fs.writeFileSync('README.md', withSiteLink, 'utf8');
|
||||
console.log(`README.md обновлён из ${indexPath}`);
|
||||
};
|
||||
|
||||
|
||||
Reference in New Issue
Block a user