Сохраняю для истории фрагмент обсуждения в телеге:
Q: Хочу попробовать цеттель для написания учебного пособия по электронике + немного кодинга, в идеале — чтобы цеттель был такой базой знаний, из которой по кускам можно было бы (полу)автоматически собирать документацию к проектам (а если и шаблонный код то вообще ух!)
A: Если хочется писать именно в Obsidian, то нужно ориентироваться на Markdown. В этом случае можно попробовать следующий путь:
markdown → Pandoc → любой другой формат
Можно попробовать вместо Obsidian использовать другой редактор, например VSCode, плагином к нему подключить удобную разметку и тем самым исключить pandoc как промежуточный этап.
Если речь идет о учебном пособии, то я бы всё же ориентировался на более богатые чем markdown языки разметки, и менее упоротые чем LaTeX. Например RST или Asciidoc
Мы в компании используем именно Asciidoc для создания документации. Выбирали осмысленно и не сразу. Поэтому лично я рекомендую его.
В Asciidoc уже писали учебники. Примером служит руководство по гиту - ProGit (GitHub - progit/progit2: Pro Git 2nd Edition) полностью написанное в asciidoc.
Так же существует генератор статических сайтов - Antora, с помощью которой можно отобразить книгу в виде красивого web-портала. Её плюс в том, что она может собирать кусочки документов не только из разных репозиториев, но и из разных веток этих репозиториев. Поэтому у такой документации сохраняется не только преемственность информации, но и появляется контроль версий и даже возможность работы с разными языками.
Q: По личному опыту чем asciidoc богаче маркдауна?
A: Сам язык разметки богаче. Предоставляет множество возможностей, которые в markdown можно сделать только костылями.
Например нормальные, человеческие таблицы с форматированием, нумерация разделов, подписи под иллюстрациями. Вставки управляющих команд, например о запрещении переноса куска текста на следующую страницу.
При этом базовая часть языка разметки остаётся простой в понимании и применении, не сложнее Markdown. Получается что порог вхождения писателя не высокий, а с накоплением опыта работы с разметкой увеличиваются возможности.
Направление называется “doc-as-code”, документация-как-код. Если хочется пообсуждать, то можно создать тему на форуме с таким заголовком. Но только вопрос придумайте. Точнее конечную цель которую хотите достичь. (Возможно для вашей цели все эти инструменты могут быть избыточными)