Другой подход к написанию и оформлению текстов при помощи Markdown
Я очень давно пишу заметки на разные темы. За более чем 10 лет это были рассуждения о политике, музыке, культуре, путешествиях, программировании, менеджменте и т. д. Публиковался я на различных блоговых платформах, включая собственный сайт на WordPress (удален за ненадобностью).
Как правило, редко кто пишет тексты сразу же в визуальных редакторах платформ для публикации. Пользователи используют привычные и популярные инструменты – текстовые процессоры, такие как Microsoft Word, LibreOffice или Google Docs. Они прекрасны для оформления обычных, не инженерных материалов, в них есть проблемы с поддержкой специальных символов, вставкой примеров программного кода или математических формул. В связи с тем, что я частенько пишу тексты на программистскую тематику и хочу показывать примеры кода, для меня это критичный недостаток. Другая проблема заключается в том, что при копировании материала из обычного текстового процессора в визуальный редактор платформ копируются и стили написанного, которые не всегда корректно отображаются и требуют дополнительных усилий для приведения к нужному внешнему виду.
Подкованный в теме читатель спросит: "Раз у тебя такие проблемы, то почему ты не используешь LaTeX?". Мой ответ прост: эта система занимает достаточно много места на жестком диске, и она ориентирована на верстку книг, а мне нужно всего лишь написать заметку и выложить её в интернет. К тому же, как я упомянул выше, разные платформы имеют неодинаковые алгоритмы оформления текста и мне нужны максимально чистые исходники для публикации. Долгое время я искал золотую середину между несовершенством обычных текстовых процессоров и тяжестью систем типа LaTeX. Выход был найден случайно и лежал на поверхности.
Некоторое время назад я стал систематизировать полезную информацию, которую я нахожу в различных источниках, и создавать базу знаний. Для этих целей прекрасно подошла программа Obsidian, которая предлагает писать заметки в формате Markdown и соединять их между собой системой тегов. Благодаря этому можно визуализировать взаимосвязи этих записей и быстрее находить информацию в базе. Кстати, этот подход оказался весьма эффективным. Многое из того, что мне нужно нечасто, но тяжело ищется в интернете, теперь всегда под рукой. Каждая заметка представляет собой текстовый Markdown-файл, который не требует дополнительного софта для редактирования, можно использовать простой блокнот или редактор, встроенный в Obsidian. Также каждая заметка может быть выгружена в формат html, а в дальнейшем уже преобразована в docx, pdf или тот, который вам больше нравится.
Этот подход написания заметок мне крайне приглянулся и я решил его транспонировать на написание статей, ведь формат Markdown прекрасно поддерживает вставку кода и математических формул, при этом он не привязан ни к одному редактору типа LaTeX, и редактировать тексты, как я отметил выше, можно в простом блокноте. В качестве среды для написания материала я решил использовать Visual Studio Code. Во-первых, этот редактор программного кода установлен на всех компьютерах, которыми я пользуюсь, а во-вторых, для него написаны плагины, которые помогают работать с Markdown. Ну и можно свои заметки сразу же выгружать в разные форматы, например html или pdf.
На момент написания этой заметки я использую следующие плагины:
- Markdown Fiction Writer – позволяет увидеть статистику по документу: количество слов, букв, страниц, время прочтения и т. д. Также можно соединить несколько Markdown-документов в один и выгрузить, например, в pdf. Помимо этого, есть инструменты для упорядочивания файлов и добавления метаинформации.
- Markdown All in One – базовый плагин для работы с этим форматом. Включает подсветку синтаксиса, автодополнение и многое другое
- Markdown Preview Enchanced – позволят увидеть превью файла и прикинуть, как он будет выглядеть после выгрузки в другие форматы.
- Markdown to PDF – экспорт файлов в pdf, html, jpeg, png.
- vscode-pdf – этот плагин не обязателен, но очень полезен для предпросмотра pdf-файлов в Visual Studio Code
Плагины к Visual Studio Code, которые я использую для работы с Markdown. Просто добавьте их в файл extension.json, который должен находиться в папке .vscode. Если файла или папки нет, то просто создайте их.
Упомянутый выше подкованный читатель может сказать: "Ну экспортируешь ты все это дело в pdf, но как на платформу для публикаций вставлять примеры исходного кода и формулы?". На это у меня есть ответ. Если платформа для публикации не поддерживает подсветку кода, то практически всегда можно создать gist и вставить его в текст. Если не получается вставить формулу, то можно сделать обычный скриншот с её изображением и поместить между параграфами. В этом нет ничего сложного.
Помимо трудностей с оформлением, существует и другая проблема, которая есть в привычных текстовых процессорах, – это отсутствие внятной версионности файлов. Используя эти системы, непросто отслеживать изменения в текстах: кто и когда их вносил, какие строки были изменены и т. д. Я как инженер привык использовать систему контроля версий Git. Она очень удобна для поиска и отслеживания изменений в файлах. Но она хорошо работает только с простыми текстовыми сущностями, не перегруженными метаинформацией, как, например, .docx файлы от Microsoft Word. В случае сравнения версий для такого типа записей Git отмечает больше различий, чем нужно, так как при внесении изменений в текст меняется и метаинформация, которая не интересна для пользователя и усложняет анализ изменений. Подход с написанием заметок в формате Markdown решает и эту проблему. Так как структуры файлов очень просты и содержат в себе практически чистый текст без дополнительной информации, используя систему контроля версий, мы видим чистую историю изменений, которую легко читать и понимать.
Теперь несколько слов о минусах использования Markdown и Git. Первый и самый критичный – высокий порог входа. Для написания текстов надо знать специфический синтаксис и уметь им пользоваться. Но если вы когда-нибудь добавляли или редактировали статьи в Википедии или подобных системах, то у вас не будет сложностей, так как там используется именно он, если нет, то придется потратить время на изучение. Второй минус – для использования версионности надо уметь пользоваться системой контроля версий Git. Она сложна в освоении, и особенно понимании, но, к счастью, есть клиенты для различных операционных систем, которые позволяют пользоваться Git без использования консоли, – просто нажимая на кнопки в программе. Ну и если вам не критично, можно обойтись и без версионности или заливать файлы на Google Drive, он её поддерживает из коробки.
Написание заметок с помощью Markdown избавило меня от головной боли, связанной с оформлением текстов и поддержкой версионности. Я бы рекомендовал его всем, кто не боится различных технических трудностей и хочет иметь больше контроля над тем, как выглядит его текст. Исходный текст данной заметки написан с использованием Visual Studio Code + Markdown + Git.