Это да, не совсем бесплатная задача

Ещё из сложностей, это переезд на другой генератор статики и переобучение людей

Скоуп возможных манипуляций с md rst asciidoc не так велик, чтобы не смочь быстро выбрать подходящее. Картинки, списки, инклюды, графика, оценить такое совсем не проблематично

Два вечера тыканий хватит, чтобы понять в целом как пользоваться, но за этим следует ещё период адаптации

Привык, допустим, писатель главную мысль выделять в тексте жирным, а в asciidoc есть более подходящее с точки зрения семантики средство

Нужно ж задуматься, подобрать

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

Но, конечно, YMMV, это я по нашему опыту говорю

На 7м Гипербатоне был хороший доклад от команды техписов Яндекса про то, как у них появился маркдаун, насколько он по факту оказался беден для работы техписателей, и как команда решала эти проблемы. Доклад в принципе неплохо глянуть, если есть сомнения в выборе легковесных языков разметки.
Начало записи доклада тут: https://youtu.be/Uo-W9glG1pc?t=11898

Я уже так глубоко и давно ушел в md, а тут в последнее время столько всего про asciidoc интересного, что сам засматриваюсь и задумываюсь, но так ментально сложно отказаться от md :(

У нас от объема это вообще почти константа. У меня один код переносит 18 гайдов на 10 языках примерно за 10 минут. Но в код вложена тысяча часов разработки и он исправляет огромный список ошибок в исходнике. Там куча преобразований до pandoc и после него.

Таргет это конечный документ?
Если так, то на выходе мы используем в основном PDF, очень редко docx. На будущее есть мысль вести базу знаний техподдержки в гите и генерировать оттуда статичный сайт для показа клиентам.
Возможно в будущем придётся сделать несколько документов по госту

Markdown в его истинном виде, нам не подошел из-за бедности форматирования.  На сколько я понял существует несколько вариантов расширить Markdown, но я не копал в эту сторону и мне, как новичку, кажется это какими-то костылями.

как по мне, сильная завязка на одну конкретную тулзовину - плохо. Доки перестают быть гибкими

Это тулзовина для переезда контента. Она гибкости не мешает

Можно не расширять, а сразу выбрать сорт маркдауна, который обладает набором возможностей. Не упущу момента напомнить про один из самых живых и развивающихся flavour'ов — Markdeep

А не будет проблем с генерацией документов из этого диалекта маркдауна?

Ну, тоесть, на сколько он поддерживается?

в PDF точно не будет, за это начинает отвечать уже браузер, вот на счет docx — не уверен, с ним всегда и везде есть и будут проблемы, т.к это закрытая микрософтичья штука

Идеально не выйдет что-то более-менее сложное конвертить

Ну вот я сейчас сделал пару документов. Мне нужно было задавать размеры колонок таблиц, масштаб вставляемых изображений, вставлять содержание и  указывать разрывы страниц для pdf. Я смог сделать с помощью asciidoc
Markdeep сможет это всё?

размеры колонок - маркдаун не могёт, он по самому широкому всё ровняет, вроде как
масштаб можно через html теги (это ок), за содержание у меня, например, отвечает IDE в которой я пишу всё, а разрывы да, классические ———- (тут много тире, телега конветитт в длинные) сработают

Всем привет!

У нас есть интересная внутренняя задача, связанная с системой распространения знаний. Может быть у кого-то есть подобный опыт? Общался с @Nick_Volynkin он навел на Атлас у Авито, пошли узнавать по знакомым что там за штука и как используется, но это их внутренний инсструмент, который скорее всего никак не достать.

В общем, наша боль: есть потребность в инструменте, который бы автоматизированно собирал информацию из git-репозиториев в какое-то место (например wiki), которым было бы удобно пользоваться всем - техписам, сервисной службе, тестироващикам, девопс и т.д. Мы собрали требования и задача в общем звучит как некая матричная структура, где по горизонтали описаны все микросервисы (как раз та часть, которая хранится в git-e) с changelog, версиями, версиями api по гайдам, которые мы сами сделали, readme. По вертикали были бы описаны бизнес-функции, где и как эти сервисы участвуют - эта часть уже не автогенерируемая, скорее всего. Бонус ко всему этому - структура взаимосвязей всех сервисов - тут есть понятные опенсорсные инструменты, которыми можно сделать такую карту, взяв связи из конфига или package.json (для nodeJS приложений). Ну и горизонталь и вертикаль это абстракция, а не конкретное представление в виде таблицы :)

С чем нужно помочь:
Есть ли у вас опыт построения подобных систем? Есть ли какие-то инструменты, подходящие под задачу?
Сходу хочется написать несколько микросервисов, которые мы встроим в пайплайн гитлаба, просто подавая информацию в нужном виде, а они сами будут все переваривать и перепубликовать. Но выглядит как костыль, который возможно кто-то писал и как-то до нас прошел. Писать в целом не долго такую штуку, но ее же потом поддерживать и развивать нужно.

Спасибо, надо позырить поглубже.

Но мне всё же кажется нужно заранее перезаложиться в функциональности языка разметки, чтобы потом не заставлять переучиваться всех людей, которые пишут документы.
Собственно я поэтому и спросил разницу между rst и asciidoc, чтобы лучше понять минусы каждого из них и оценить критичность этих минусов в нашей работе.

Может есть где-нибудь подробное сравнение rst и asciidoc между собой? Никто не видел?

А это не оно?:
https://antora.org/