На моей работе для написания док используются три формата: Markdown — для текста и PlantUML и Mermaid — для диаграмм.

Мне удобнее писать такие доки локально на ноуте в Vim или в Sublime Text, а потом уже загружать готовую доку куда-нибудь. Чтобы генерировать диаграммы, я настроил алиасы в терминале, о которых расскажу ниже.

Содержание:

Markdown

Для начала нужно установить npm-пакет marked:

npm install -g marked

Можно открыть конфиг терминала ~/.bashrc или ~/.zshrc, и вписать туда такой алиас:

make-markdown() {
  marked "$1" -o "${1%.*}".html --gfm && echo '<style>body { font: 16px sans-serif; width: 720px; margin: 1em auto; } img { width: 100%; }</style>' >> "${1%.*}".html
}

Пример использования:

make-markdown test.md
open test.html

Откроет HTML-страницу в браузере.

Автоперегенерация

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

Сначала установить fswatch:

brew install fswatch