Плагины, без которых техническим писателям жить можно, но сложно. В подборке — линтеры, форматирование, работа с git, проектирование API, подготовка схем и милота для удобной разработки.
Линтеры
Markdownlint
Самый популярный линтер для разметки Markdown. Подсвечивает распространенные проблемы.
Markdown All in One
Поддержка разметки Markdown в Visual Studio Code. Форматирование таблиц, оглавление, рендеринг в HTML.
LTeX – LanguageTool grammar/spell checking
Проверка орфографии и стилистики английского и русского языка по правилам LanguageTool.
Code Spell Checker + Russian - Code Spell Checker
Проверка опечаток в английском и русском тексте и коде. Находит опечатки даже в названиях переменных в коде. Можно использовать расширение совместно с LTeX.
Proselint
Расширение линтера англоязычной прозы Proselint. Создатели сервиса вдохновлялись Чаком Палаником, Марком Твеном, Джоржем Оруэллом и другими писателями.
Textlint
Расширение open source сервиса Textlint, написанного на JS.
Vale
Семантический линтер с возможностью задавать свои правила, настройки и конфигурации проверок на то, что вам нужно.
Форматирование и форматы
Prettier - Code formatter
Расширение помогает так хорошо отформатировать текст в Markdown, что на него не ругается линтер.
OpenAPI (Swagger) Editor
Расширение для редактирования, форматирования спецификации OpenAPI (Swagger) в YAML или JSON.
MdTableEditor
Расширение исключительно для таблиц Markdown. Подсвечивает строки, столбцы и добавляет кнопки для операций с таблицами на командную панель.
GitHub Markdown Preview
Предварительный просмотр файлов Markdown в формате и стилистике GitHub.
Markdown Checkboxes
Расширение добавляет поддержку флажков и списков задач с предварительным просмотром.
PlantUML
Расширенная поддержка PlantUML.
Asciidoc
Расширение поддерживает предварительный просмотр в реальном времени, подсветку синтаксиса и cниппеты для формата AsciiDoc.
reStructuredText Language
Расширение для полноценной работы с языком разметки reStructuredText.
Работа с системой контроля версий
GitLens
GitLens поддерживает операции с git и визуализирует всю историю кода — когда была изменена строка или блок кода, как код менялся. Можно проследить эволюцию кодовой базы.
Git Graph
Визуализирует весь таймлайн с коммитами и ветками. Позволяет работать с git через интерфейс.
Git Project Manager
Расширение позволяет открывать новое окно с репозиторием git из окна VS Code и быстро переключаться между репозиториями.
Удобство и милота
Markdown Emoji
✨
HTTP/s and relative link checker
Поиск битых ссылок в Markdown-тексте.
Settings Sync
Синхронизирует настройки и конфигурации VSCode. Для синхронизации используется Github Gist.
Расширение конвертирует файлы Markdown в файлы PDF, HTML, PNG, JPEG.
Markdown Paste
Расширение делает скриншоты и сразу же ссылки на них в файлах Markdown.
Word Count
Подсчет символов в документе.
Auto Close Tag
Добавляет закрывающий тег.
Rainbow bracket
Каждой паре всех видов скобок расширение дает свой цвет радуги. Красным цветом подсвечены незакрытые скобки.
Live Server
Локальный сервер разработки с функцией перезагрузки в реальном времени для статических и динамических страниц. Рендеринг по кнопке.
Material Theme Icons
Иконки к файлам и папкам.
Комментарии (14)
roqin
11.11.2022 09:46Хм, а ведь определенно должно уже что-то существовать для поддержи LaTeX'а в VS Code… А я об этом раньше и не думал.
honor8
11.11.2022 09:49+1GitHub Markdown Preview
Начиная с версии 1.63 добавлено автообновление для открытых страниц встроенного просмотрщика. Просмотр
Ctrl+Shift+VRainbow bracket
Начиная с версии 1.60 определяется настройкой
"editor.bracketPairColorization.enabled": true,
Elena_Yanovich
11.11.2022 15:43Попробовала и MdTableEditor, и Markdown All in One и еще несколько не упомянутых в статье расширений, а так и не могу найти вариант для объединения столбцов в таблице (не строк).
Автор, если сталкивались, подскажите
Svetafo Автор
11.11.2022 15:46Толкового решения до сих пор так и нет https://stackoverflow.com/questions/46621765/can-i-merge-table-rows-in-markdown
dyadyaSerezha
Не знал, что документация пишется в markdown-формате. Думал, что это только короткие readme и мануальчики.
Svetafo Автор
Ни дня без открытий) Вот целая лекция про его возможности https://habr.com/ru/company/yandex/blog/342192/
dyadyaSerezha
Единственный вопрос - а зачем? Старый добрый Word не катит? Зачем поддержка LaTeX, например?
Urub
как тебе удобно в word историю изменений смотреть ?
а статик сайт (html) документаци сделать ?
latex требует высокого порога вхождения, я попробовал, сделал, но возвращаться нет желания
потому выбираю markdown на текущий момент
dyadyaSerezha
Хм... Ну, пожалуй...
Svetafo Автор
Так неудобно же в ворде. Особенно при Docs as code.
Angry_Vedmed
Тут такое дело.
Как верно заметили ниже - историю изменений не посмотреть, это раз. Второе - вставить кусок кода, чтобы это не было тошнотворно.
И вообще, зависит от задачи.
P.S.
Была несколько лет назад халтура - "собрать" из нескольких сотен вордовых текстов и картинок из Bizagi альбом формата А3. У каждого из исполнителей (большей частью почтенные дамы и, без ёрничанья, действительно специалисты) было "Своё Представление О Прекрасном" (с) в смысле оформления документов. Заказчику нужно было красиво для "Предоставления Куда Надо" (с) ;)
За рабочую неделю "слепил" конвеййер, который
1) "разбирал" тексты по параграфам и темам (шапка, краткое описание, формальное наполнение, нормативные ссылки, ссылка на картинку из Bizagi). Питоном и башем "разбирал", "складывал" в CSV.
2) При помощи не-помню-уже-какого "кликера" запускал этот адовый Bizagi (на отельной машине, в виртуалке он не жил) и "заставлял" его экспортировать диаграмму в SVG (а не PNG).
3) Написал и отладил в LaTeX шаблоны для титульной страницы, оглавления (номера страниц были с пропусками, типа, после 200 легко могло быть и 210) и содержательной части. Соственно, основная часть затраченного времени и ушла на изучение этого чудесного продукта.
Не могу представить, как это можно было бы сделать в любом ворд-процессоре.
Angry_Vedmed
М-да, поглотили воспоминания, а то, ради чего начал излагать всё это, так и не написал. ;)
Короче.
Любой инструмент он для своих задач. Использовать ворд-процессор для документации - явный перебор. Всякие нарядные свистелки просто мешают. А возможность "играться" шрифтами/цветами/форматированием в любом месте документа - безусловное зло.
"Плоский" текст же таких вольностей не позволяет. Форматирование в Markdown-редакторах (в известных мне, по крайней мере) тупо "приколочено гвоздями" к экрану. Если совсем невмоготу - меняй тему (а это .CSS практически везде). Немногим это необходимо и ещё меньшее количество способно это сделать без ошибок (я - не могу, ибо не надо ;) ). И это хорошо.
Далее.
С "плоским" же текстом легко работать. Даже с таблицами markdown и вставками кода, т.к. это просто текст. Можно весь процесс на bash написать и это будет работать и работать хорошо.
Конечно же есть масса библиотек и тулов, которые из почти любого формата вытащат содержимое и позволят либо использовать его либо сослаться на него. Но зачем так сложно?
Busla
Справедливости ради — в word встроено как сравнение двух (версий) документов, так и сохранение истории изменений внутри самого документа с авторами, аппрувом или отклонением изменений и т.п. Из какого-нибудь vscode код вставляется в той же подсветке и «теме» и шрифте, что был в самом редакторе — результат гораздо предсказуемее, чем попытки распарсить неполный код сторонним раскрашивателем.
А если бы почтенные дамы в markdown или latex претворили бы каждая своё видение прекрасного? — например, ссылки как код, списки бы и заголовки через эмидзи оформили бы — вы бы markdown и latex забраковали?
Word и (la)tex — системы семантической разметки текста: можно разметить заранее согласованными стилями/классами термины, имена файлов, клавиатурные сочетания и затем «лёгким движением руки» получить глоссарий терминов, файлов, справочник по комбинациям клавиш, общий список авторов и т.п. Да, это требует некоторой прилежности от всех участников и связано с другими попоболями, но в итоге из набора word/latex документов реально собрать единую документацию с перекрёстными ссылками и прочими прелестями. "Плоский" текст же таких вольностей не позволяет.