Декабрь'19 в Docops чате

Участников чата на день публикации: 558

Это краткое резюме дискуссий и полезных ссылок в чате Docops в декабре 2019.

выбор SSG

фильтры pandoc

сбор фидбека к документации (CSAT)

метатеги в Markdown

генерация документации в PDF при использовании MkDocs

сравнение двух текстовых pdf-файлов

Docusaurus 2

1.12

Что обсуждали: выбор SSG

  • @murgut спросил, существует ли либа, которая будет соответствовать этим требованиям: подсветка кода, вывод документа единым списком, подсветка аннотаций, встраивание движка для интерактивных примеров, мобильная версия, поддержка <head> тегов, пререндер html.
  • @NickVolynkin ответил, что подсветка синтаксиса обычно реализовывается отдельными библиотеками (pygments, rouge, т.д.), пререндер html есть почти везде, теги в head также почти везде, где можно редактировать шаблон, мобильная версия зависит от темы. В остальном, лучше выбрать что-то из http://staticgen.com лучше на JS, если это ваш основной язык. @DarthVader добавил, что есть еще highlight.js.
  • Сайт reactjs сделан на движке Gatsby https://github.com/reactjs/reactjs.org#running-locally.

10.12

  • @ligurio порекомендовал тьюториал по написанию документации для Unix - https://manpages.bsd.lv/mdoc.html
  • @ArinaBallerina поделилась, как решала проблему генерации документации в PDF при использовании MkDocs, пробовала md2pdf, typora, foliant, голый pandoc. Ссылка на сообщение и последующий тред: https://t.me/docsascode/11631

12.12

У Gatsby есть стартер паки для быстрого поднятия под разные нужды, вот например для блога: там всё сводится к gatsby new gatsby-starter-blog https://github.com/gatsbyjs/gatsby-starter-blog

16.12

  • Обсуждали, кто как делал фидбек для документации. Варианты: можно использовать events в Google Analytics, подключить сторонний макрос, использовать typeform, создавать ишью в репозитории или Джире. @filhodejaneiro поделился ссылкой на туториал для SSG+GA https://www.docsy.dev/docs/adding-content/feedback/ Пример из Plesk: https://docs.plesk.com/en-US/obsidian/administrator-guide/about-plesk.70559/
  • @SirEdvin поделился ссылкой на release notes https://vector.dev/releases/0.6.0/, сделанные на Docusaurus 2 (https://github.com/timberio/vector/tree/master/website). Темная тема включается при соответствующей настройке в системе. параметр prefers-color-scheme. Ссылка на релиз новой версии Docusaurus: https://deploy-preview-2100--docusaurus-2.netlify.com

18.12

Что обсуждали: фильтры для pandoc, работа с linux под windows, как анализировать фидбек на документацию.

20.12

  • @oplatonova задала вопрос про Markdown, можно ли в исходном файле md (который будет конвертирован в html) ввести дополнительные теги - например, указывать ключевые слова, которые будут конвертированы в вид <META Name="keywords" Content="keywor1, keyword2">. Ответы: https://www.markdownguide.org/extended-syntax/#definition-lists && or https://www.markdownguide.org/extended-syntax/#footnotes
  • pandoc может из YAML metadata block. Это не чистый markdown, конечно, но и не HTML внутри markdown, с помощью такого ключа можно добавить параметры title и keywords, которые экспортируются в HTML-документ, или записать тоже самое в YAML metadata block.
  • Можно ли в исходном файле tex. при конвертации в docx исключить из вывода некоторые блоки? Например, из блока \begin{ figure} и begin{tcolorbox} вывести figure. Можно написать фильтр (pandoc lua filters).

24.12

30.12

Обзор HAT решений: https://www.indoition.com/online-help-authoring-tools-survey.htm