Статический сайт и генераторы (SSG)
| Принцип | страницы собираются заранее, а не при каждом запросе |
|---|---|
| Источники | Markdown, шаблоны, данные (YAML, JSON), API |
| Генераторы | Jekyll, Hugo, Eleventy, Astro, MkDocs, Docusaurus, Sphinx |
| Хостинг | GitHub Pages, Cloudflare Pages, Netlify, Vercel, любой веб-сервер |
| Плюсы | скорость, безопасность, дешёвый хостинг, простое кэширование в CDN |
| Связанный термин | Jamstack |
Статический сайт — сайт, состоящий из заранее подготовленных файлов: HTML, CSS, JavaScript, изображений. Сервер просто отдаёт эти файлы, ничего не вычисляя при запросе, — в отличие от динамического сайта, который собирает страницу из базы данных для каждого посетителя. Генератор статических сайтов (англ. Static Site Generator, SSG) — программа, которая один раз собирает такие файлы из исходников: текстов в Markdown, шаблонов, данных и настроек.
Так устроено большинство сайтов документации, технических блогов и лендингов. Например, вики, в которой вы читаете эту статью, собирается собственным генератором из Markdown-файлов в HTML-страницы, копии в Markdown и файлы llms.txt.
Как это работает
- Автор пишет страницы в Markdown с метаданными во front matter — блоке YAML в начале файла (заголовок, дата, теги).
- Генератор читает файлы, превращает Markdown в HTML, подставляет его в шаблоны (шапка, меню, подвал) и строит служебные страницы: списки, теги, поиск, RSS, карту сайта.
- Результат — папка с готовыми файлами (
public/,dist/,site/), которую можно выложить куда угодно.
---
title: Установка
weight: 2
---
# Установка
Скачайте пакет и выполните `make install`.
Сборка обычно запускается автоматически при каждом push в Git: конвейер CI/CD собирает сайт и публикует его на хостинге.
Преимущества
- Скорость. Готовый файл отдаётся мгновенно и отлично кэшируется в CDN по всему миру.
- Безопасность. Нет базы данных, серверного кода и админки — почти нечего взламывать.
- Дешевизна. Статику бесплатно размещают GitHub Pages, Cloudflare Pages, Netlify; подойдёт и обычный nginx.[6]
- Контент как код. Тексты лежат в репозитории, изменения проходят ревью через pull request, история хранится в Git.
- Переносимость. Markdown не привязан к конкретной платформе и одинаково удобен людям и языковым моделям (см. Markdown как формат для LLM).
Ограничения
Статический сайт не может сам по себе обработать форму, хранить комментарии или показывать персональные данные. Эти задачи решают внешние сервисы и API, вызываемые из браузера, или бессерверные функции хостинга. Этот подход — статическая разметка, JavaScript и API — называют Jamstack.[7] Ещё одно ограничение — время сборки: сайт из десятков тысяч страниц у медленных генераторов собирается минутами, поэтому появились инкрементальная сборка и частичная пересборка.
Популярные генераторы
| Генератор | Язык | Год | Особенности |
|---|---|---|---|
| Jekyll | Ruby | 2008 | встроен в GitHub Pages, породил моду на SSG[1] |
| Hugo | Go | 2013 | один бинарник, очень быстрая сборка[2] |
| Sphinx | Python | 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
pip install mkdocs-material
mkdocs new my-docs && cd my-docs
mkdocs serve # локальный сервер с автообновлением на http://127.0.0.1:8000
mkdocs build # готовый сайт в папке site/
# mkdocs.yml
site_name: Моя документация
theme:
name: material
language: ru
nav:
- Введение: index.md
- Установка: install.md
Документация для людей и машин
Статические сайты документации всё чаще публикуют не только HTML, но и машиночитаемые версии: Markdown-копию каждой страницы, файл llms.txt с картой сайта и полный текст одним файлом. Это позволяет языковым моделям и агентам читать документацию без разбора вёрстки и рекламы. Практические советы собраны в статье Документация для ИИ: как подготовить.