Markdown, Source, Books, Sites
-----------------------------------------------------------
https://giga.chat/link/gcsBZLhmRq
Awesome Markdown GitHub
https://giga.chat/link/gcsBZLhmRq
daringfireball.net/projects/markdown
https://akawah.ru/linux/markdown.html
Books
1. «The Markdown Guide» (Мэтт Коун) (akawah.ru)
Ваш метод изучения — сначала обзор всей структуры, а затем погружение в детали — идеально подходит для работы с документацией. В программной индустрии Markdown ценится именно за то, что позволяет быстро сканировать текст глазами, не отвлекаясь на визуальный шум WYSIWYG-редакторов.
Ниже приведены ресурсы, которые помогут вам систематизировать знания, от базового синтаксиса до профессиональной автоматизации.
Интернет-источники (для быстрого старта и справочника)
- The Markdown Guide (markdownguide.org) Это золотой стандарт документации. Ресурс создан техническим писателем Мэттом Коуном. Он структурирован именно по вашему методу: есть раздел «Basic Syntax» для беглого ознакомления и «Extended Syntax» для изучения таблиц, списков задач и подсветки кода. Сайт работает как быстрый справочник (cheat sheet).
- Оригинальная спецификация Джона Грубера (daringfireball.net/projects/markdown/) Первоисточник. Поскольку Markdown был создан для максимальной читаемости без рендеринга, чтение этой страницы помогает понять саму философию языка: «документ должен выглядеть как обычный текст, даже если его не обрабатывать».
- Awesome Markdown (на GitHub) Агрегатор всех существующих инструментов. Если вам понадобится конвертировать Markdown в PDF, Word, слайды или ePub, там собраны ссылки на все необходимые утилиты (Pandoc, grip, mdbook).
- Ресурсы для практики в браузере:
- StackEdit (stackedit.io) — мощный онлайн-редактор, который работает офлайн и синхронизируется с Google Drive/GitHub. Отлично подходит, чтобы протестировать сложный синтаксис, не настраивая VSCode.
- Dillinger (dillinger.io) — простой редактор с разделением экрана «Код слева — Результат справа».
Книги (для глубокого понимания и рабочих процессов)
Поскольку вы работаете в VSCode и пишете архитектурную документацию, вам подойдут книги, ориентированные на разработчиков, а не на гуманитарную верстку.
1. «The Markdown Guide» (Мэтт Коун)
- Формат: Книга и бесплатный сайт.
- Почему стоит прочитать: Это самое четкое и лаконичное описание синтаксиса. Автор отсекает всё лишнее. Книга идеально подходит для вашего первого этапа — «быстрого пробега», так как занимает около 60 страниц и дает полное понимание того, что умеет язык.
- Где найти: Русский перевод доступен на профильных ресурсах (например, на сайте akawah.ru), оригинал — на markdownguide.org.
2. «R Markdown: The Definitive Guide» (Ихуэй Се, Кристоф Дервье, Эмили Ридере)
- Формат: Книга и онлайн-документация.
- Почему стоит прочитать: Это книга для перехода на следующий уровень. Она учит не просто писать текст, а превращать его в автоматизированные отчеты. Вы научитесь вставлять в Markdown результаты выполнения кода, динамические графики и таблицы. Для архитектора это полезно тем, что описание системы может автоматически дополняться актуальными метриками или схемами.
- Особенности: Охватывает работу с Pandoc — «швейцарским ножом» для конвертации документов, который лежит в основе многих генераторов документации.
3. «Modern Technical Writing: An Introduction to Software Documentation» (Эндрю Дэвис)
- Формат: Электронная книга.
- Почему стоит прочитать: Здесь Markdown рассматривается не как язык, а как часть индустриального процесса. Книга объясняет, как организовать репозиторий с документацией, как настроить автоматическую сборку сайта из ваших
.mdфайлов (DocFX, MkDocs) и как внедрить процесс ревью документации (как код-ревью).
Практический совет по вашему методу изучения
Чтобы закрепить знания в VSCode, создайте один файл sandbox.md. Используйте его как черновик:
- Этап 1 (Синтаксис): Скопируйте туда примеры из «The Markdown Guide» и воспроизведите их.
- Этап 2 (Инструментарий): Попробуйте вставить туда блок Mermaid (диаграмму) и убедитесь, что расширение
Markdown Preview Mermaid Supportее отрисовало. - Этап 3 (Автоматизация): Попробуйте написать в файле таблицу и нажать
Ctrl+K, затемCtrl+T(если установлен Markdown All in One), чтобы автоматически сгенерировать оглавление (TOC) в начале файла.
Это позволит вам за один день пройти путь от «знаю синтаксис» до «умею собирать документацию как профессионал».
---------------------------------------------
------------------------------------------------------
GNU/Linux
Переводил для себя. Английского не знаю. Если есть замечания, предложения, исправления — пишите:
Комментариев нет:
Отправить комментарий