# Статический сайт и генераторы (SSG)

> Статический сайт — набор готовых HTML-файлов, которые сервер отдаёт без вычислений; генераторы статических сайтов (SSG) собирают такие файлы из Markdown, шаблонов и данных.

Источник: https://llmdocs.ru/wiki/static-site-generators/ · обновлено 2026-11-09 · лицензия CC BY-SA 4.0

- **Принцип**: страницы собираются заранее, а не при каждом запросе
- **Источники**: Markdown, шаблоны, данные (YAML, JSON), API
- **Генераторы**: Jekyll, Hugo, Eleventy, Astro, MkDocs, Docusaurus, Sphinx
- **Хостинг**: GitHub Pages, Cloudflare Pages, Netlify, Vercel, любой веб-сервер
- **Плюсы**: скорость, безопасность, дешёвый хостинг, простое кэширование в CDN
- **Связанный термин**: Jamstack
**Статический сайт** — сайт, состоящий из заранее подготовленных файлов: [HTML](https://llmdocs.ru/wiki/html.md), [CSS](https://llmdocs.ru/wiki/css.md), [JavaScript](https://llmdocs.ru/wiki/javascript.md), изображений. Сервер просто отдаёт эти файлы, ничего не вычисляя при запросе, — в отличие от динамического сайта, который собирает страницу из базы данных для каждого посетителя. **Генератор статических сайтов** (англ. *Static Site Generator*, SSG) — программа, которая один раз собирает такие файлы из исходников: текстов в [Markdown](https://llmdocs.ru/wiki/markdown.md), шаблонов, данных и настроек.

Так устроено большинство сайтов документации, технических блогов и лендингов. Например, вики, в которой вы читаете эту статью, собирается собственным генератором из Markdown-файлов в HTML-страницы, копии в Markdown и файлы [llms.txt](https://llmdocs.ru/wiki/llms-txt.md).

## Как это работает

1. Автор пишет страницы в Markdown с метаданными во **front matter** — блоке YAML в начале файла (заголовок, дата, теги).
2. Генератор читает файлы, превращает Markdown в HTML, подставляет его в **шаблоны** (шапка, меню, подвал) и строит служебные страницы: списки, теги, поиск, RSS, карту сайта.
3. Результат — папка с готовыми файлами (`public/`, `dist/`, `site/`), которую можно выложить куда угодно.

```markdown
---
title: Установка
weight: 2
---

# Установка

Скачайте пакет и выполните `make install`.
```

Сборка обычно запускается автоматически при каждом push в [Git](https://llmdocs.ru/wiki/git.md): конвейер [CI/CD](https://llmdocs.ru/wiki/ci-cd.md) собирает сайт и публикует его на хостинге.

## Преимущества

- **Скорость.** Готовый файл отдаётся мгновенно и отлично кэшируется в [CDN](https://llmdocs.ru/wiki/cdn.md) по всему миру.
- **Безопасность.** Нет базы данных, серверного кода и админки — почти нечего взламывать.
- **Дешевизна.** Статику бесплатно размещают GitHub Pages, Cloudflare Pages, Netlify; подойдёт и обычный [nginx](https://llmdocs.ru/wiki/nginx.md).[6]
- **Контент как код.** Тексты лежат в репозитории, изменения проходят ревью через [pull request](https://llmdocs.ru/wiki/pull-request.md), история хранится в Git.
- **Переносимость.** Markdown не привязан к конкретной платформе и одинаково удобен людям и языковым моделям (см. [Markdown как формат для LLM](https://llmdocs.ru/wiki/markdown-for-llm.md)).

## Ограничения

Статический сайт не может сам по себе обработать форму, хранить комментарии или показывать персональные данные. Эти задачи решают внешние сервисы и API, вызываемые из браузера, или бессерверные функции хостинга. Этот подход — статическая разметка, JavaScript и API — называют **Jamstack**.[7] Ещё одно ограничение — время сборки: сайт из десятков тысяч страниц у медленных генераторов собирается минутами, поэтому появились инкрементальная сборка и частичная пересборка.

## Популярные генераторы

| Генератор | Язык | Год | Особенности |
|---|---|---|---|
| Jekyll | Ruby | 2008 | встроен в GitHub Pages, породил моду на SSG[1] |
| Hugo | Go | 2013 | один бинарник, очень быстрая сборка[2] |
| Sphinx | [Python](https://llmdocs.ru/wiki/python.md) | 2008 | документация Python и многих библиотек, reStructuredText |
| MkDocs | Python | 2014 | документация из Markdown; популярная тема Material for MkDocs[5] |
| Docusaurus | JavaScript (React) | 2017 | сайты документации с версиями и переводами |
| Eleventy | JavaScript | 2018 | минимализм, любые шаблонизаторы[3] |
| Astro | JavaScript | 2021 | «острова» интерактивности, по умолчанию ноль JS на клиенте[4] |

Фреймворки вроде Next.js, Nuxt и SvelteKit тоже умеют генерировать статические страницы, совмещая их с серверным рендерингом там, где он нужен.

## Пример: MkDocs

```bash
pip install mkdocs-material
mkdocs new my-docs && cd my-docs
mkdocs serve              # локальный сервер с автообновлением на http://127.0.0.1:8000
mkdocs build              # готовый сайт в папке site/
```

```yaml
# mkdocs.yml
site_name: Моя документация
theme:
  name: material
  language: ru
nav:
  - Введение: index.md
  - Установка: install.md
```

## Документация для людей и машин

Статические сайты документации всё чаще публикуют не только HTML, но и машиночитаемые версии: Markdown-копию каждой страницы, файл [llms.txt](https://llmdocs.ru/wiki/llms-txt.md) с картой сайта и полный текст одним файлом. Это позволяет языковым моделям и агентам читать документацию без разбора вёрстки и рекламы. Практические советы собраны в статье [Документация для ИИ: как подготовить](https://llmdocs.ru/wiki/docs-for-ai.md).

## См. также

- [Markdown](https://llmdocs.ru/wiki/markdown.md)
- [HTML](https://llmdocs.ru/wiki/html.md)
- [llms.txt](https://llmdocs.ru/wiki/llms-txt.md)
- [CDN](https://llmdocs.ru/wiki/cdn.md)
- [CI/CD](https://llmdocs.ru/wiki/ci-cd.md)

## Источники

1. [Jekyll — документация](https://jekyllrb.com/docs/)
2. [Hugo — документация](https://gohugo.io/documentation/)
3. [Eleventy — документация](https://www.11ty.dev/docs/)
4. [Astro — документация](https://docs.astro.build/)
5. [MkDocs — Project documentation with Markdown](https://www.mkdocs.org/)
6. [GitHub Docs — About GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages)
7. [Jamstack](https://jamstack.org/)