Генераторы статичных сайтов, такие как Jekyll, Hugo и Sphinx, являются одним из наиболее распространенных инструментов создания и публикации, используемых в сценариях docs-as-code. Генераторы статичных сайтов создают все файлы для сайта, помещая файлы Markdown в определенные макеты, запуская сценарии для автоматизации необходимой логики и многое другое по мере генерации файлов HTML. Этот раздел посвящен исключительно генераторам статичных сайтов. В следующих разделах рассмотрим также варианты хостинга и развертывания, а также автономные CMS, которые тесно связаны со генераторами статичных сайтов.
Что такое: генератор статичных сайтов?
Генераторы статичных сайтов - это приложения, которые можно запускать в командной строке (или, возможно, через какой-то другой интерфейс) для компиляции веб-сайта из более простых исходных файлов. Например, у нас могут быть различные файлы, определяющие макет, некоторые «включаемые» файлы (содержащие повторно используемое содержимое), файл конфигурации и файлы содержимого в формате Markdown.
Генератор статичных сайтов считывает файл конфигурации и помещает контент в файлы макетов, добавляет все ссылки, на которые есть ссылки (например, боковую панель, footer или повторно используемые фрагменты), и записывает HTML-страницы из источников Markdown. Каждая страница обычно имеет боковую панель и другую навигацию, включенную непосредственно в страницу (предварительно созданную), как и остальной код макета, готовый для просмотра в Интернете.
Кроме того, генераторы статичных сайтов могут использоваться программно в скриптах сборки, которые выполняются как часть процесса на сервере. Что позволяет использовать их в процессах обновления, которые запускаются определенным событием, таким как фиксация в определенной ветви в репозитории управления версиями, или как часть скрипта.
С помощью системы управления контентом (CMS), (например WordPress), контент сохраняется в отдельной базе данных и динамически извлекается из базы данных на веб-страницу при каждом посещении пользователя. Генераторы статичных сайтов не имеют баз данных - весь контент уже находится на странице, и ничего не собирается динамически на лету с помощью PHP или других серверных скриптов. Все страницы на статическом сайте были созданы до запроса браузера, что позволяет получать мгновенный ответ; ничего не меняется динамически в зависимости от профиля пользователя (если это не сделано с JS на стороне клиента).
Отсутствие модели базы данных делает генераторы статичных сайтов гораздо более портативными и независимыми от платформы. У нас просто есть коллекция текстовых файлов. В отличие от этого, переход от одной CMS к другой обычно включает миграцию базы данных, и многие поля базы данных из одной CMS обычно не точно отображаются в других базах данных, не говоря уже об уникальных конфигурациях сервера и другой инфраструктуре, требуемой для каждого решения. Генераторы статичных сайтов устраняют такие сложности, делая текстовые файлы более легкими, более переносимыми и менее подверженными ошибкам из-за проблем с базой данных и сервером.
До переноса блога idratherbewriting.com в Jekyll, автор курса использовал WordPress (и даже пять лет был консультантом по WordPress в качестве дополнительной работы). Блог WordPress падал или имел другие проблемы несчетное количество раз. Обычно приходилось связываться с Bluehost (веб-хостинг), чтобы выяснить, почему сайт внезапно закрывался. Создавались резервные копии базы данных, применялись исправления безопасности и методы повышения безопасности, оптимизировались базы данных с помощью других инструментов и многое другое. И со всеми этими хлопотами по обслуживанию сайт работал очень медленно, доставляя страницы за 2+ секунды вместо 0,5 секунды от Jekyll. Часто приходилось устранять проблемы с взломанными базами данных многих клиентов WordPress.
При использовании генераторов статичных сайтов, при разработке контента на локальном компьютере, предварительный просмотр веб-сервера доступен обычно на http://127.0.0.1:4000, предоставляемый генератором статичных сайтов. Многие генераторы статичных сайтов перестраивают сайт на сервере предварительного просмотра каждый раз при внесении изменений. Время на восстановление сайта может занять меньше секунды, или несколько минут, если у сайта тысячи страниц.
Поскольку все компилируется локально из текстовых файлов, не нужно беспокоиться о взломах безопасности баз данных. Весь сайт - это человеко читаемые текстовые файлы, от файлов с содержимым, до кода приложения. Также невероятно легко работать с пользовательским кодом, таким как специальные библиотеки JavaScript, расширенный HTML или другой сложный код, который можно использовать на странице. Можно создавать свой контент в Markdown или HTML, добавлять примеры кода внутри блоков кода, которые обрабатываются с помощью подсветки синтаксиса кода, и многое другое. Открытость и гибкость генераторов статичных сайтов позволяют делать с ними что угодно.
Большинство генераторов статичных сайтов позволяют использовать шаблоны и скриптовые языки, такие как Liquid или Go, внутри контента. Можно использовать операторы if-else, запускать циклы, вставлять переменные и выполнять намного более сложную обработку контента с помощью языка шаблонов.
Работа в основном с текстовыми файлами подразумевает, что файлы проекта (но не выходные данные встроенного сайта) обычно хранятся в хранилище кода, например GitHub. Обработка файлов содержимого происходит с помощью того же рабочего процесса, что и программный код: фиксация в хранилище, загрузка и извлечение обновлений, ветвление и слияние и т.д.
Готовый сайт можно запускать непосредственно из своего репозитория Git, без создания его локальной копии, а затем загружать файлы на веб-сервер. То есть репозиторий кода становится отправной точкой конвейера публикации и развертывания сайта документации. Continuous delivery, как ее называют, избавляет от необходимости вручную создавать сайт и развертывать сборку. Вместо помещается коммит в репозиторий, и механизм непрерывной доставки его создает и разворачивает.
Хотя существуют сотни генераторов статических сайтов (полный список можно посмотреть на Staticgen.com), только несколько из них, имеют отношение к документации. Например:
Можно рассматривать еще много - Hexo, Vue, Middleman, Gitbook, Pelican и так далее. Но реальность такова, что только несколько генераторов статичных сайтов используются для проектов документации.
Jekyll
На этом курсе Jekyll отведен целый раздел, дополненный примерами рабочих процессов Git, поэтому здесь короткое описание этого инструмента. Jekyll - это генератор статичных сайтов на основе Ruby, изначально созданный соучредителем GitHub. Jekyll создает веб-сайт путем преобразования Markdown в HTML, добавления страниц в определенные макеты, запуска любых сценариев и логики Liquid, сжимая стили и записи результатов в папку сайта, которую можно развернуть на веб-сервере.
Есть несколько веских причин использовать Jekyll:
- Большое сообщество. Сообщество Jekyll, возможно, самое большое среди сообществ разработчиков статичных сайтов, включает и веб-разработчиков, а не только группы, ориентированные на документацию. Такой широкий фокус привлекает больше внимания разработчиков и помогает продвигать более широкое использование.
- Контроль. Jekyll предоставляет множество мощных функций (часто с помощью скриптового языка Liquid), которые позволяют делать практически все с платформой. Такая возможность создания сценариев дает невероятный контроль над абстрагированием сложного кода от пользователей с помощью простых шаблонов и макетов. Jekyll соответствует любым навыкам веб-разработки, JS, HTML или CSS-фреймворкам. Даже без опыта разработки довольно легко вычислить и закодировать нужные сценарии. (См. пост автора Jekyll против DITA для получения подробной информации о том, как делать в Jekyll то, привыкли делать в DITA.)
- Интеграция с GitHub и AWS S3. Тесная связь Jekyll с самым популярным хранилищем контроля версий на планете (GitHub) уже гарантирует его успех. Чем больше GitHub используется, тем больше Jekyll также используется, и наоборот.GitHub Pages автоматически создает сайт Jekyll (непрерывная доставка), что позволяет без труда автоматизировать рабочий процесс публикации. Если GitHub не подходит для проекта, можно публиковать в корзину AWS S3 с помощью плагина s3_website, который синхронизирует вывод Jekyll с корзиной S3, только добавляя или удаляя измененные файлы.
В качестве темы Jekyll предлагает возможность упаковывать тему как Rubygem и распределять ее по нескольким проектам Jekyll. Rubygems - это менеджер пакетов, что означает, что он является хранилищем плагинов. Необходимые гемы (плагины) извлекаются из Rubygems при помощи командной строки, используя Bundler. Распределение темы как Rubygem - это один из подходов, который можно использовать для разбиения проекта на более мелкие проекты, чтобы обеспечивать более быстрое время сборки.
Hugo
Hugo - это генератор статичных сайтов, популярность которого быстро растет. Основанный на языке Go, Hugo создает сайт значительно быстрее, чем большинство других генераторов статических сайтов, включая Jekyll. Существует впечатляющее количество тем, в том числе предназначенных для документации. В частности, стоит ознакомиться с темой Learn и темой документации по многоязычному API.
Как и Jekyll, Hugo позволяет писать в Markdown, добавлять содержимое frontmatter в YAML (или TOML или JSON) вверху страниц Markdown и многое другое. В этом смысле Hugo очень похож на Jekyll.
У Hugo есть надежный и гибкий язык шаблонов (Golang), который делает его привлекательным для дизайнеров, которые могут создавать более сложные веб-сайты на основе глубины платформы (см. документацию Hugo). У шаблонов Go больше возможностей для изучения, чем у шаблонов с Liquid в Jekyll, и документация может потребовать больше технических знаний. Тем не менее, главное преимущество Hugo в скорости создания сайта. Этого фактора может быть достаточно для компенсации более крутого обучения.
Сравнивание скорости Hugo и Jekyll
Скорость может стать не первым показателем, при первых оценках генераторов статичных сайтов. Столкнуться с проблемой скорости можно, наверное имея сайт с большим количеством страниц (например, тысяча страниц).
Хотя все зависит от того, как закодирован сайт (например, от количества циклов for, которые перебирают страницы), в целом если у проекта, порядка 1000 страниц, то на создание сайта может уйти около минуты или двух. Таким образом, если сайт одержит 5000 страниц, придется ждать 5 минут или больше для создания сайта. Вся функция автоматического восстановления становится практически неактуальной, и становится сложно определить форматирование или другие ошибки до завершения сборки. (Однако есть обходные пути, которые рассмотрим позже.)
Если Hugo может создать сайт намного быстрее, это дает преимущество в выборе генераторов статичных сайтов. Smashing Magazine недавно выбрал Hugo и создал множество дополнительных инструментов для управления своим сайтом.
Подробное сравнение Hugo и Jekyll в статье Hugo vs. Jekyll: Comparing the leading static website generators. В одном из комментариев читатель делает несколько интересных комментариев о скорости:
Время сборки - серьезное преимущество в скорости, которое позволит масштабировать сайт документации надежными способами. Автор (чьи документы находятся на https://docs.mendix.com) переключился с Jekyll на Hugo (см. Обзор документов в GitHub). Его переход предполагает, что скорость, возможно, является основной характеристикой для оценки в генераторах статичных сайтов.
Разница между Hugo и Jekyll потребует от подумать о размере проекта - насколько большим должен быть проект? Должен ли быть один гигантский проект с контентом для всей документации/продуктов, хранящихся в одном репозитории? Или это будут несколько небольших репозиториев? Вот некоторые из соображений, с которыми Том Джонсон сталкивался при реализации инструментов docs-as-code. Он пришел к выводу, что иметь один масштабный проект предпочтительнее, потому что он позволяет упростить повторное использование контента, адаптацию, валидацию и проверку ошибок, управление развертыванием и многое другое.
Что касается скорости сборки, в Jekyll есть обходные пути для ускорения сборки. В своих рабочих проектах документации (где 1500 страниц или около того в разных наборах документации) были реализованы ярлыки сборки. Каскадными файлами конфигурации можно ограничить сборки одним конкретным каталогом документов. Есть один файл конфигурации (например, _config.yml, по умолчанию), который устанавливает все содержимое как publish: true, и другой файл конфигурации (например, config-acme.yml), который устанавливает все содержимое как publish: false, за исключением конкретного документа. каталог (тот, с которым я работаю, например, acme). При работе с каталогом acme doc, Jekyll собирается следующим образом:
jekyll serve --config _config.yml,config-acme.yml
Config-acme.yml перезапишет _config.yml по умолчанию, чтобы включить один конкретный каталог документов как publish: true, при отключении всех остальных. В результате Jekyll быстрее сработает. Такой метод имеет довольно хорошую тенденцию и также используется другими пользователями в больших проектах Jekyll. В компании автора настроена непрерывная доставка с сервером, поэтому, когда приходит время отправить полную сборку (где publish: true применяется ко всем каталогам и файл config-acme.yml не используется), полный процесс сборки происходит на сервере , а не на локальной машине. Полная сборка занимает пару минут. (Сервер использует другую конвейерную логику в том смысле, что он проверяет, принимает и разворачивает файлы, которые в общей сложности требуют около 10 минут.)
Хотя генераторы статичных сайтов, быстро меняются, одному инструменту, такому как Hugo, труднее обогнать другой, например Jekyll, из-за того, что разработчики обычно делают с платформой. Если просто использовать чью-то тему с общими страницами Markdown, отлично, переключение будет простым. Но если создать собственные макеты и добавить пользовательский frontmatter на своих страницах Markdown, который обрабатывается макетами уникальными способами, а также другими пользовательскими сценариями или кодом, которые созданы в своей теме специально для вашего контента, изменение платформ будет более тяжелым. Придется изменить все сценарии Liquid на Golang. Или, при работе с другой платформой, возможно потребуется изменить сценарии Golang на шаблоны Jinja и т.д.
Sphinx
Sphinx - это популярный генератор статичных сайтов, основанный на Python. Первоначально он был разработан сообществом Python для документирования языка программирования Python (и он имеет некоторую прямую возможность документировать классы Python), но теперь Sphinx используется и для многих проектов документации, не связанных с Python. Частично популярность Sphinx обусловлена его основой Python, поскольку Python хорошо работает для многих скриптовых сценариев, связанных с документацией.
Поскольку Sphinx изначально разрабатывался как инструмент для документирования, а не просто как инструмент для создания веб-сайтов (такие как Jekyll и Hugo), Sphinx обладает более специфичной для документации функциональностью, которая часто отсутствует в других инструментах генерации статичных сайтов. Некоторые из этих специфических для документации функций включают в себя надежный поиск, более сложные ссылки (ссылки на разделы, автоматизацию заголовков на основе ссылок, перекрестные ссылки и т.д.) и использование reStructuredText (rST), который является более семантически богатым, стандартным и расширяемый, чем Markdown. (См. Как насчет reStructuredText и Asciidoc?, где сравниваются rST и Markdown.)
Для непрерывного развертывания на любом хостинге Sphinx можно использовать с платформой Read the Docs. В целом, у Sphinx есть преданная фанатская база среди тех, кто его использует, особенно среди сообщества Python. Однако, поскольку Sphinx был специально разработан как инструмент документирования, сообщество может быть не таким большим, как некоторые другие сообщества генераторов статичных сайтов (которые используют генераторы статичных сайтов для создания общих веб-сайтов, а не только сайтов документации).
По состоянию на декабрь 2018 года Staticgen.com показал количество звезд, копий и выпусков следующим образом:
На сайте Staticgen.com значок звездочки показывает количество пользователей, которые «помечали» проект (в основном следивших за его деятельностью). Значок с веткой отображает количество существующих копий репозитория, зарегистрированных на их платформе (GitHub и т.д.). Значок ошибки отображает количество открытых проблем, зарегистрированных в проекте. Зеленые цифры указывают на тенденции с этими числами.
Jekyll, Next и Hugo являются наиболее распространенными генераторами статичных сайтов. Если посмотреть на Staticgen.com, то можно увидеть, что между Hugo и Sphinx существует около 24 других генераторов статических сайтов (Gatsby, Hexo, Gitbook, Nuxt, Vuepress, Docusaurus, Pelican, Metalsmith, MkDocs, Brunch, Middleman, React Static, Harp, Expose, Assemble, Wintersmith, Cactus, Phenomic, Docpad, Lektor, HubPress, а затем Sphinx). Но здесь, на этом курсе Sphinx упомянут из-за его популярности среди групп документации и его интеграции с Read the Docs.
MkDocs
MkDocs - это генератор статичных сайтов, основанный на Python и предназначенный для документации проектов. Подобно Jekyll, в MkDocs документация пишется в Markdown, навигация по страницам хранится в файлах YAML. Можно настроить CSS и другой код (или создать свою собственную тему). В частности, MkDocs предоставляет некоторые темы, которые более специфичны для документации, такие как тема Material. MkDocs также предлагает тему («ReadtheDocs»), которая напоминает платформу Read the Docs.
Есть и другие темы. MkDocs использует шаблоны Jinja, предоставляет переменные шаблонов для кастомизации тем и многое другое.
Хотя существует множество генераторов статичных сайтов с похожими функциями, MkDocs более ориентирован на документацию. Например, он включает в себя поиск. (Однако можно включить поиск в Algolia в любую из этих платформ, поэтому встроенный поиск - если он действительно феноменальный - вероятно, не должен быть отличительным фактором.)
Наверное, ориентирование платформы на документацию было бы выгодно для технических писателей, но такой подход может иметь неприятные последствия, поскольку сокращает сообщество. Число общих веб-дизайнеров и дизайнеров документации, вероятно, составляет 100: 1. Таким образом, MkDocs остается небольшой нишевой платформой, которая, не увидит большого роста и долгосрочного развития сверх потребностей оригинального дизайнера.
Такой компромисс среди инструментов - инструменты и платформы с наибольшим сообществом и использованием обычно не являются инструментами для документации. Инструменты документации имеют больше функций, разработанных для технических писателей, но им не хватает динамики и глубины более популярных инструментов для создания веб-сайтов.
Какой инструмент выбрать?
Сейчас, вероятно, есть много читателей, которые опускают брови в гневе от упущения своего инструмента: А как же … Docpad !! ??? Как насчет Nikola ?? !! Где Docusaurus? !!
Эй, есть множество инструментов, и наверное, каждый нашел для себя идеальное соответствие между потребностями в контенте и инструментом. Кроме того, экосистема инструментов для документации для разработчиков является надежным, сложным и, казалось бы, бесконечным.
Кроме того, признаем, что здесь только рекомендации того, что автор курса считает наиболее популярными вариантами. Множество инструментов для разработчиков разнообразно и постоянно меняется, и то, что может оказаться актуальным в один прекрасный день, может оказаться неуместным на следующий. Инструменты Docs-as-code - это сложное пространство для навигации, и выбор правильного инструмента для своих нужд - сложный вопрос. Выбранный инструмент повлияет как на производительность, так и на возможности, поэтому к выбору стоит подойти очень осознано.