"коробочное" всегда приходится дорабатывать под свои нужды

В том-то и вопрос: есть ли что-то коробочное под мой кейс? Хотя бы что-то близкое. Описание кейса повторю, извините:
"Репозиториев у нас сотни, ибо продукт большой.
Репозитории лежат на GitLab (self-hosted) и на Github.
Технические документы пишутся на markdown и лежат в репах так же, как код. Документы по конкретному сервису лежат именно в его репе."

Выше мне предложили Аскидоктор + антора. Нормально, но это для asciidoc. А существует ли аналог для markdown?

Sphinx?

вопрос тогда в том, что входит в слово нормально, какие элементы разметки и иные возможности нужны?

Никто не пишет. Видимо, хороших примеров нет. )

Я даже не знаю что это ))

Абзацы, заголовки, списки, цитаты, код, картинки, ссылки, таблицы, выделение текста, автоссылки. Всё это есть в документах.

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

Это в целом почти стандартный набор, может ref только не везде, берите почти любой ssg из ссылки выше (staticgen.com), просто отсортировать те, что исходником умеют md: Jekyll, gatsby, Hugo, mkdocs, foliant, docusaurus

Насколько я вижу из описаний, mkdocs, docusaurus, hugo, gatsby не умеют публиковать контент сразу из нескольких репозиториев (а это нужно в моём случае). Есть ли среди всего этого моря тулов умеющий это делать? Т.е. как Antora, но для маркдауна.

публикуйте отдельными приложениями с одинаковой версткой и сделайте им схожие URL через cname. docs.site.com/api, docs.site.com/guides, docs.site.com/db и т.п. docs.site.com будет разводящей со ссылками на остальные доки. поиск можно через Algolia например настроить, но нужно смотреть, как будет работать с разными приложениями.

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

вот это самое разумное кажется. но тогда должен быть и редирект на редактирование сорса

сделайте себе отдельный master repository и подключите все остальные в него как submodules

сами по себе ssg не особо умеют ходить в репозитории удаленные, они работают с тем, что есть в файловой системе

Gatsby вроде умеет, там есть source-git, но я не тестировала

foliant.org, подробнее:

https://foliant-docs.github.io/docs/preprocessors/includes/

https://foliant-docs.github.io/docs/config/from/

Если заинтересуетесь, есть чатик: https://t.me/foliantdocs

Судя по описанию, очень крутая штуковина. Кто реально пользуется?

Мы пользуемся, прекрасная вещь

ТЗ пишем в markdown'е в git'е, один файл - одна фича.
Для совместимости с чужими процессами можно выгрузить docx и залить в Google Docs

Единственное, там нужно явно указывать все исходники в foliant.yml, а нам удобнее чтоб файловая структура отражала оглавление (тогда дерево папок и файлов в любом редакторе даёт работать с файлами как с обычным оглавлением в Word'е)

Но это решает скрипт с find, который по файлам собирает пути и кладёт в foliant.yml

Мы пользуемся :)

Привет. А нет ли у кого хорошего подробного описания работы с какими-то плейбуками Ansible?

Хочется посмотреть, кто как описывает работу со своими плейбуками. В качестве шаблона.

Чтоб для новичков. Кроме очевидных.

Спасибо.