О, они сделали скринкаст про то как начать работать с документацией. https://www.youtube.com/watch?v=oJsUvBQyHBs

Впрочем, нет, не они, просто какой-то парень с ютуба

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

этот ролик семилетней давности действительно до сих пор актуален?

Товарищи, такой вопрос. Какой легковесный язык разметки поддерживает нормальную нумерацию рисунков и пунктов. MD всем хорош, но в больших документах уже возникают сложности с ручным проставлением номеров. Да, есть плагины на VSCode для автоматической нумерации, но хотелось бы нативное решение.

Asciidoc. Можно попробовать понадеяться на автонумерацию, а если документ сильно сложный, то лучше использовать итераторы.  {counter:risunok}.  Каждый вызов будет увеличивать на единицу и отображать. Если надо увеличить без отображения, то  {counter2:steps}.  После двоеточия - это название счётчика. Может быть сколько угодно в документе

Спасибо

У меня техписы сначала сильно ворчали когда я пересаживал их из ворда. Говорили именно про автонумерацию. Но когда распробовали asciidoc, согласились, что уж лучше вручную, чем надеяться на ворд

интересная конечно картина мира. Я вообще не могу понять, как можно выстроить хоть какой-то системный повторяемый интроспектируемый процесс с вордом

Внутри рабочего коллектива в режиме правки документ крутится несколько итераций пока не начнёт адово тормозить. Если надо куда-то выдать в смежное подразделение, то начинается учёт замечаний в отдельном эксельном файле - реестр замечаний. Жесть, да

сильно сопротивляютс тому же гиту?

В моей команде все в гите. Но смежные даже в конфлюенс не хотят.  Onedrive отключён.

Привет всем! Такая проблема, маркдауны лежат в одной директории, картинки тоже, при генерации пдф и ворд, картинки добавляются в исходный документ, но не добавляются на сайт, меняешь путь к картинкам, добавляются на сайт, но не добавляются в пдф и ворд. Как все таки правильно нужно прописывать путь? Для текстовых документов использую pandoc, для генерации html - Sphinx c парсером для markdown(extensions = ['myst_parser'])

могу предположить что вам надо объявить переменную, вида {imagedir}
Также, посмотрите путь до картинки в html.

Вот так собираются

http://localhost:63342/MyProject/build/html/source/pic/1.png
C:\Users\username\Desktop\MyProject\build\html\_images

source/pic/1.png это путь в markdown, а в сборку попадают вот сюда  MyProject\build\html\_images

в нем файлы для разработки - маркдаун файлы и папка с картинками pic

Отталкиваться надо от путей в html уже при верстке на сайте

А потом смотреть пути для докх и пдф