Если вы пишете техническую документацию на Markdown, вы уже знаете эту дилемму: одни части вашего документа — это написанный от руки текст, а другие — оглавление, включенный фрагмент кода, отрисованная диаграмма — сгенерированы откуда-то еще. То, как вы управляете этой границей, многое говорит о вашем рабочем процессе. Большинство инструментариев для документации решают эту проблему так же, как препроцессоры вроде PET или Jamal: разделяют исходный код и результат. Вы поддерживаете файл шаблона, запускаете этап сборки и получаете в результате отрисованный документ. Чисто, предсказуемо и легко для понимания — но это добавляет этап сборки, а выходной файл — это не то, что вы на самом деле редактируете или передаете.