SSG

SSG

---

Концепция Docs as code реализована в решениях ля подготовки документации, которые относятся к категории "SSG" (Static site generator). В результате работы SSG появляются неизменяемые файлы. И сам процесс поход на компиляцию программы из исходного кода.

SSG-решения

• Sphinx. Используется в Read the Docs.
• Docusaurus - использует node.js, для кастомизации React
• Hugo с системой шаблонизации Go. пример (Cloudflare)
• Jekyll с системой шаблонизации liquid. Используется в GitHub Pages.
• Doxygen - извлекает текст из программного кода и генерит документацию. Ряд платформ имеют встроенные такие функции, например, dart doc
• Antora пример, 2
• Foliant (для генерации pdf and docx, использует Pandoc или md-to-pdf, для веб-сайтов MkDocs, Aglio или Slate.)
• Material for MkDocs

Готовые к использованию реализации

Эти реализация не требуют установки и можно пользоваться, выполнив инструкции по быстрому старту. Функционал можно увидеть в бесплатной версии.

• Read the Docs готовое веб-решение (использован Sphinx или [[w:en:MkDocs]MkDocs|])
• GitHub Pages - готовое решение от Github, штатно поддерживает Jekyll, но через Github actions можно подключить другие SSG - Hugo, Gatsby, Next.js, Nuxt.js, MkDocs, VuePress, Docusaurus.
• Netlify - из коробки готов к использованию Hugo. Тема docsy (от Google) для Hugo имеет документацию на Netlify.
• Gitlab имеет сервис Gitlag Pages аналогичный тому что на Github

Какие SSG используется в крупных проектах

• Fedora Linux использует Antora
• Linux Mint использует Read the Docs,
• Dart использует Eleventy , до него использовался Jekyll.
• Spring использует ASCIIDoctor ,
• GitLab для свой документации - использует Nanoc,

Какие SSG из коробки поддерживают Asciidoc-форматирование

• Antora
• Список прочих

См. также

• w:en:Documentation_generator - программные инструменты, генерящие документацию для конечных пользователей или для разработчиков (описание АПИ)

Ссылки

• Список из 300 различных SSG
• Eleventy vs. Next.js
• Eleventy (11ty) vs. Gatsby