Введение в Markdown: главное, что вы хотели знать о разметке, но стеснялись спросить

Разбираемся, как программисты оформляют обычный текст и зачем вам уметь так же.

Содержание

Перед погружением в гайд представьте (или попробуйте вспомнить — вдруг у кого-то получится) интернет начала двухтысячных. Чтобы выйти в сеть были нужны городской телефон и модем, которые работали от одной розетки: отключаете телефонный провод, подсоединяете кабель модема — и вы онлайн. На связи можно было оставаться только пока мама отдыхала от разговора с подругой — если работал телефон, модем приходилось выключать. Чтобы скачать файл в 3-4 мегабайта приходилось терпеть медленную прерывистую связь. Интересные были времена — Масяня их помнит. 

Кстати, интернет нулевых был не только медленным, но и дорогим. Чтобы сэкономить, пользователи отключали картинки в Internet Explorer и обходились текстом. А некоторые даже верили, что если не использовать окно браузере в полноэкранном режиме, можно снизить расход трафика. 

В те годы текст был основным инструментом коммуникации в интернете. Блогосфера развилась, но удобных платформ для размещения контента не было — авторы вынужденно использовали разметку HTML, чтобы публиковать форматированный текст. Этот язык многим не нравился: нужно было вручную прописывать множество тегов, поскольку до плагинов автозаполнения и онлайн-конвертеров программисты еще не добрались. Теги создавали барьер для мыслей автора — было неудобно писать и править текст.

Больше остальных оказался недоволен Джон Грубер — техноблогер, дизайнер пользовательского интерфейса и главный разработчик языковой разметки Markdown. Грубер придумал для основных элементов HTML сокращенный синтаксис и написал Perl-скрипт, который делал две вещи: заменял сокращенный синтаксис тегами и обрамлял текст между пустыми строками в абзацы. Скрипт Джона Грубера подарил веб-авторам предварительный просмотр — с этого момента в текстовом редакторе можно было увидеть отформатированный текст до его публикации в интернете. 

Джон Грубер придумал Markdown в 2004 году, но разметка актуальна до сих пор — ей пользуются практически все программисты, которые пишут в интернете. Разберемся, почему так произошло и как освоить актуальную версию Markdown с минимумом трудозатрат. 

Что такое Markdown и как он работает

Markdown — это разметка документа простыми текстовыми символами, которые умеют преобразовываться в HTML-формат и одинаково выглядят в любом браузере. Тексты оформленные в Markdown легко читать и писать, поскольку они создаются без кода. 

У Markdown есть даже собственная философия, вроде Zen of Python — полный текст можно найти на сайте автора Daring Fireball. Ниже — пара тезисов для лучшего понимания языковой разметки:

По теме
Сервисы для усложнения работы: какие корпоративные инструменты не любят программисты
Сервисы для усложнения работы: какие корпоративные инструменты не любят программисты
  • Markdown должен быть простым для чтения и письма, насколько только возможно.
  • Приоритет — удобству чтения. Markdown-документ должен публиковаться как есть и напоминать обычный текст — без тегов или сложных элементов форматирования.
  • Источник вдохновения для синтаксиса Markdown — обычное текстовое сообщение электронной почта из 2004. Точнее: знаки пунктуации, которые в нем помещаются.

Если суммировать, то практический смысл Markdown в простоте: чтобы каждому веб-автору было как можно проще готовить тексты для публикации в интернете. Например, вы пишете текст и добавляете к словам различные символы: решетки, звездочки, подчеркивания и прочие элементы. Разметка готова — текст по-прежнему удобно читать, а на сайте он будет выглядеть, как отформатированная HTML-страница. 

Ниже видео рабочего процесса от разработчиков iA Writer — в левой части текст набранный в формате Markdown; в правой — отформатированный вариант (то, как текст выглядит в браузере): 

Программисты обычно используют Markdown для подготовки тех. документации, оформления баз знаний или добавления комментариев на площадки вроде Reddit, GitHub или Stack Overflow. Тексты, созданные в Markdown, везде выглядят одинаково:

  • Вы открываете браузер и начинаете описывать проект в README-файле на GitHub. Затем можете скопировать содержимое в десктопный Markdown-редактор и продолжить — текст будет также выглядеть и форматироваться.
  • Далее можно перекинуть оформленный файл коллеге, чей браузере или редактор отличается от вашего — Markdown и у него будет работать так же.
  • А вот если этот же документ подготовить в любом другом популярном формате, могут  возникнуть проблема. Например, у вас программа Pages от Apple, а у коллеги — офисные пакеты Microsoft Word или LibreOffice. В этом случае могут сбиться стили и некоторые части документа будут некорректно отображаться.

Если использовать более экзотические форматы и разные операционные системы, то можете случиться так, что документ вообще не отобразит содержимое. 

Markdown удобен своей универсальностью. Именно поэтому 2004 год давно позади, а язык разметки никуда не исчез и помогает в работе многим программистам. Если вы не уверены, столкнетесь с текстами или нет, — посмотрите лекцию Виталия Езепчука о документировании в ИТ-отрасли.

Два момента оттуда, к которым стоит обязательно прислушаться: 

  • Специализированный софт для документированная существует, но он дорогой. Поэтому для ведения записей удобно и выгодно использовать разметку Markdown.
  • Документация нужна для большинства проектов, но технических писателей нанимают в основном крупные компании. Если без документации не обойтись и бюджет проекта ограничен, работа тех. писателей перейдет к программистам.

Так что если не знаете, учить Markdown или нет — учите. Лишним он точно не будет. Да и по времени это занимает меньше часа. Подробности — в следующем разделе.

Возьмите любой Markdown-редактор, браузер или операционную систему — разметка Markdown будет везде одинаково отображаться и форматироваться 

Как запомнить нужные элементы разметки

Изучить Markdown несложно: достаточно посмотреть техническую документацию по синтаксису и потренироваться обрамлять текст в интерактивном тренажере. Нюанс в том, что после 2004 года Джон Грубер не обновлял разметку и не захотел развивать проект совместно с другими разработчиками. Поэтому сейчас у Markdown нет единого стандарта и каждая крупная площадка публикует свою инструкцию. Вот популярные для айтишников: 

Базовый синтаксис во многих инструкциях совпадает, но специфические способы форматирования текста могут отличаться. Еще нюанс: правила одной площадки необязательно будут работать на другой. Чтобы было понятно — рассмотрим некоторые специфические функции разметки Markdown, которые есть на GitLab и Stack Overflow. 

Диалект Markdown для GitLab:

Вы можете добавлять цвета в форматах: HEX, RGB, или HSL:

Можете описывать диаграммы и блок-схемы. Например, прописать схему «Русалочка»: 

Визуальное отображение схемы «Русалочка»:  

Можете добавить в текст эмодзи: 

Результат: 

Вот еще несколько опций, которые доступны в Markdown-версии GitLab: вы можете автоматически добавлять метаданные к страницам, использовать встроенные теги, математические формулы и символы, списки задач, оглавления, ссылки и другое. 

Чтобы реализовать описанный функционал, команда GitLab разработала собственную версию Markdown, которая называется GitLab Flavored Markdown. В техдокументации GitLab указано, где заканчивается стандартная часть и начинается специфический синтаксис Markdown. Другие площадки тоже обычно дают подобные пояснения. 

Диалект Markdown  для Stack Overflow: 

На Stack Overflow  расширения GitLab Flavored Markdown не работают — вы не можете добавлять цвета в разных форматах, использовать схему «Русалочка», эмодзи и прочую красоту. Дополнительные возможности Markdown ограничены тут лишь несколькими опциями форматирования текста. Например, можно настроить подсветку синтаксиса для кода, обрамить текст в спойлер, привязать страницу к тегам, настроить таблицы и добавить сокращенные ссылки в комментарии. 

По теме
Как запомнить все: сохраняем заметки в майнд-мэпах и остаемся продуктивными
Как запомнить все: сохраняем заметки в майнд-мэпах и остаемся продуктивными

Stack Overflow никак не называют свою версию Markdown — для них это просто расширения стандартного синтаксиса. При этом, расширенная версия Stack Overflow не работает на GitLab. То есть с помощью разметки Markdown от Stack Overflow вы не сможете добавить сокращенные ссылки к комментариям на GitLab.

Фрагмент документации по Markdown с сайта Stack Overflow. Здесь расписано, как делать сокращенные ссылки с помощью дополнительного синтаксиса

Чтобы не утонуть в многообразии инструкций — в первую очередь изучите справочник и интерактивный тренажер на сайте CommonMark. После — знакомьтесь с чем угодно. 

CommonMark — это ответвление от классической версии Markdown Джона Грубера. Проект появился потому, что классическая версия оказалось сырой и не получала обновлений — неизвестно точно почему, но Джон Грубер не хотел второй версии. 

Рассмотрим проблему на примере. Напишем в Markdown неупорядоченный список: 

Теперь Markdown переводит нашу запись в HTML:

В теории, после такой процедуры мы должны получить список. Но проблема классической версии Markdown в том, что при переводе в HTML к абзацам автоматически добавляется тег <p>. Чтобы тег не добавлялся — между пунктами списка должна находиться пустая строка. Если ее нет — синтаксический анализатор может дать сбой и вместо списка отобразить каждый пункт списка в виде отдельного абзаца. Этот пример обсуждался на форуме и есть 15 вариантов отображения данного фрагмента. 

Эта и множество подобных ошибок делали Markdown непредсказуемым инструментом: веб-авторы и программисты не могли заранее знать, как поведет себя разметка и каким будет текст после публикации в интернете. Плюс, это создавало неудобство на техническом уровне: если несколько пользователей писали Markdown-документы в разных редакторах, то при слиянии или обмене файлами не всегда соблюдался единый стиль оформления — слетали списки, ссылки, цитаты, изображения и прочие элементы.

Разные варианты отображения списков в классической версии Джона Грубера — одна из многих ошибок, из-за которой Markdown нуждался в доработке. Изображение: johnmacfarlane.net

CommonMark можно считать версией Markdown 2.0. Это форк, который развивается группой разработчиков и поддерживается всеми крупными площадками, начиная с GitHub. В нем нет ошибок вроде непредсказуемого отображения списков, а все новые проблемы постепенно дорабатываются. Можно сказать, что CommonMark стандартизирует базовый синтаксис, на который остальные площадки накладывают свои дополнения. Полистайте примеры выше с GitLab и Stack Overflow: все общее на этих площадках от CommonMark, а различия — личная инициатива. 

👉 История развития CommonMark

Если выучите синтаксис CommonMark, считайте, вы знаете 80% современной разметки Markdown. Еще 20% — это специфический синтаксис тех площадок, на которых вам придется работать. Специфика нужна не всегда, а база обязательна. 

Фрагмент из справочника по Markdown от CommonMark. Изображение: commonmark.org
Урок по Markdown из тренажера CommonMark. Изображение: commonmark.org

Как выбрать первый текстовый редактор 

Разметку Markdown можно использовать в любом редакторе кода. Например, в VS Code: достаточно открыть нужный файл и из доступных форматов выбрать Markdown. Это не сложно для опытных программистов, но может стать проблемой для новичков — дело в системе контроле версий Git, которая нужна для хранения файлов в облаке. 

По теме
Что такое Low Tech Web-сообщество и как оно поможет выиграть войну против платформ
Что такое Low Tech Web-сообщество и как оно поможет выиграть войну против платформ

Если вы еще не успели изучить Git — это раздел для вас. Мы рассмотрим, как выбрать обычный текстовый редактор для работы с Markdown. Фишка обычных редакторов в том, что они автоматически сохраняют файлы на собственных облачных сервисах или позволяют подключать внешние хранилища. Например, Dropbox или Google Диск

Дальше вы узнаете, какие редакторы бывают, стоит ли их покупать и с чего начать знакомство.

Пример отображения разметки Markdown в VS Code

Есть три вида текстовых Markdown-редакторов: платные, условно платные и бесплатные. Платные — это программы, которые вы не можете использовать, пока не купите. Условно платные — это редакторы с ограниченными функциями. Например, вы можете сделать 50 бесплатных заметок, а если захотите больше — оформляйте подписку. В бесплатных редакторах за все функции и обновления платить не нужно. 

У платных редакторов два преимущества: дизайн и фишки от разработчиков. За счет этого работа с текстом упрощается, но это все тот же Markdown. Дальше примеры. 

IA Writer

Начнем с платного редактора iA Writer, который заточен на сфокусированную работу с текстом. Вы получаете пустую страницу и скрытые из вида настройки. Можно включить режим печатной машинки и Focus Mode, чтобы оттенить ненужные предложения или абзацы. Перед вами будет текущая строка — то, на чем важно сфокусироваться.

Bear и UPNote

Теперь рассмотрим два условно бесплатных редактора: Bear и UPNote. В Bear никаких особых фишек нет, но это приложение многие пользователи выбирают из-за дизайна и типографики. Еще фишка — редактор Bear позволяет рядом с текстом смотреть изображения. В iA Writer изображения доступны в режиме предварительного просмотра. 

Вот дизайн и отображение заметок с изображениями в Bear:

А так нужно просматривать изображения в iA Writer: 

UPNote — это не самый популярный, но один из самых продвинутых Markdown-редакторов. Он подходит тем, кого раздражают решетки, звездочки и прочие элементы разметки во время письма. В UPNote Markdown замаскирован под обычный отформатированный текст — такой же, какой вы видите в Microsoft Word или другом текстовом процессоре. 

Кстати, черновик предыдущего раздела написан в UPNote. Для сравнения скриншоты UPNote,  iA Writer и Bear:

Во всех трех приложениях один и тот же Markdown, но отображается по-разному: в UPNote разметка замаскирована, в iA Writer нет, в Bear — частично: заголовки, ссылки и прочие элементы выделяются и занимают свободное пространство редактора.

Среди прочих функций UPNote можно выделить:

Киллер-фича UPNote — возможность отправить ссылку на заметку другим пользователям. Если вы перейдете по ссылке, то увидите весь черновик предыдущего раздела. К сожалению, его пока нельзя совместно редактировать, как это умеет Google Docs.

По теме
Чем заменить сервисы Google: почта, аналитика, облачные хранилища, карты и не только
Чем заменить сервисы Google: почта аналитика облачные хранилища карты и не только
Фрагмент черновика предыдущего раздела, который создан в UPNote и доступен по внешней ссылке. Изображение: getupnote.com

Мы не рекомендуем платные редакторы новичкам, поскольку большинство их возможностей доступны бесплатно. Например, в программах Obsidian или Zettlr. 

Zettlr

В  редакторе Zettlr меньше функций, но вот сравнение с некоторыми популярными приложениями: 

Изображение: zettlr.com

Zettlr — программа, созданная для обработки больших объемов документации. Для этого в редактор встроен гибкий поиск, функция одновременной работы с несколькими текстами и система внутренних ссылок для организации файлов по методу Zettelkasten.

Obsidian

Obsidian — одна из мощнейших программ для работы с Markdown. В бесплатной версии вам без ограничения доступны все функции, а платить нужно за следующее: 

  • Если понравился продукт и вы хотите поблагодарить разработчиков.
  • Если вы корпоративный пользователь и планируете использовать редактор в коммерческих целях. 
  • Если хотите запускать Obsidian на разных устройствах, но предпочитаете не подключать Dropbox, Google Диск или другие бесплатные облачные хранилища. В этом случаях команда Obsidian может защитить заметки сквозным шифрованием и разместить их на своих серверах. Вместе с этой функции работает история версий. 
  • Если вам настолько понравился Obsidian, что на его основе вы хотите получить движок на сайт и прямо из приложения публиковать свои заметки в интернете. 

Дополнительное преимущество Obsidian — бесплатные плагины, которые расширяют базовые возможности приложения. С помощью плагинов вы можете использовать VIM для русскоязычной раскладки, добавить канбан-доску, интеллект-карту, инструменты для рисования и многое другое. На выбор доступно более 600 плагинов, которые постоянно обновляются за счет активности сообщества (около 66 000 человек на момент обзора). 

Чтобы познакомиться с возможностями Obsidian — рекомендуем начать с бесплатного курса Obsidian for Beginners, опубликованного на ютуб-канале Linking Your Thinking.

Если ничего не понравилось и вы хотите выбрать Markdown-редактор самостоятельно — ниже несколько рекомендации, которые помогут во всем разобраться. 

1. Не выбирайте облачные приложения

Старайтесь не использовать приложения, которые хранят информацию на сторонних серверах и недоступны офлайн. В любой момент времени файлы должны находиться на вашем компьютере в работоспособном состоянии. Bear и UPNote хранят заметки на внешних серверах и поэтому эти редакторы мы не рекомендуем для работы.

Прецедент: история приложения Roam Research. После выпуска разработчики активно рекламировали продукт, предлагали много бесплатных возможностей и хранили данные пользователей в облаке на сторонних серверах. Через время разработчики передумали, ввели платную подписку и оставили клиентов без доступа к записям. Повезло, что можно было заплатить и перенести заметки в другое хранилище. А если бы сервис закрылся? 

Блогер Anton Maslak о Roam Research. Источник: medium.com

2. Обращайте внимание на формат хранения

Данные должны храниться в читаемом и надежном формате — это совет на тот случай, если захотите поэкспериментировать с редакторами без поддержки Markdown. Например, OneNote от Microsoft — бесплатное кроссплатформенное приложение с множеством функций, которые работают в браузере, смартфоне и десктопном формате. 

Проблема: файлы OneNote сохраняются в «‎Формате записной книжки» разных годов выпуска приложения. Поэтому если вы поделитесь файлом, но у получателя не будет OneNote или он воспользуется несовместимой версией, то содержимое не удастся прочесть.

По теме
Как запоминать сотни задач и не сойти с ума: Getting Things Done и Zettelkasten
Как запоминать сотни задач и не сойти с ума: Getting Things Done и Zettelkasten
Выдержка из техдокументации OneNote. Источник: microsoft.com

3. Всегда выбирайте кроссплатформенность

Отдавайте предпочтение приложениям, которые одинаково выглядят и работают в любой операционной системе. Это подстраховка на случай, если когда-то придется поработать за чужим компьютером. Здесь проигрывают приложения вроде Bear, где разработчики ограничиваются рамками одной экосистемы.

Bear работает на Mac, iPad, iPhone и нигде больше. Источник: bear.app

Что дальше

Когда выберете приложение — инвестируйте время в его изучение и не гонитесь за функциями. Новинки выходят постоянно и ошибка — пытаться найти идеальный вариант. Здесь работает один из Законов Мерфи: принцип, согласно которому соседняя очередь всегда движется быстрее.

Погоня за функциями скорее всего приведет в петлю прокрастинации — вместо реальной работы вы будете зациклены на инструменте. Помните, что мастерское владение инструментом нивелирует нехватку опций. Доказательство: история Эрика Рота, который написал весь сценарий к «Дюне» Вильнева в программе Movie Master 1981 года, способной держать в памяти не более 40 страниц.

article widget img
«‎‎Главная ошибка собеса — подгонять ответы»‎. Рекрутеры рассказали о найме в IT
Откуда берутся IT-рекрутеры, с какими трудностями они сталкиваются в попытках закрыть позиции и какие ошибки сами совершают на интервью — полезно знать перед тем, как искать работу.
Телеграм-канал про Образо­вание, карьеру и жизнь в IT
Телеграм-канал про Образо­вание, карьеру и жизнь в IT

Читайте по теме

Цифровой быт
Цифровой быт
17

Цифровой быт

Как навести порядок на своих девайсах, в аккаунтах и в жизни
nerd head nerd letter

Мир содрогнулся, когда узнал, что читают разработчики по ночам...

Ничего криминального — только полезная еженедельная рассылка от Bubble. Тренды в айти, лайфхаки и советы экспертов.

Подписывайся!

Ты — котик! Проверяй почту
Нам нужен настоящий адрес эл. почты
Спецпредложения
Курсы со скидками для пользователей Bubble
Выбрать курс
Освоить за выходные
Экспресс-курсы программирования
Выбрать курс
Баг пофиксил
Курсы для QA-инженеров
Выбрать курс
Звездочка к резюме
Курсы по карьерному росту
Выбрать курс
Подписывайся на Bubble в соцсетях
Подписывайся на BUBBLE в социальных сетях
Телеграм-канал про Образование, карьеру и жизнь в IT
Только полезный контент и ничего лишнего.