Изучите Markdown: инструмент написания для разработчиков программного обеспечения

Если вы инженер-программист, вы, вероятно, потратили много времени на усовершенствование своей среды, чтобы повысить свою производительность. У вас есть любимая IDE. У вас есть любимый отладчик. У вас есть любимый инструмент для мониторинга производительности. А как насчет вашего инструмента для написания документации, руководств и отчетов? В конце концов, написание занимает нетривиальное количество вашего времени, не так ли? Действительно, пришло время серьезно отнестись к вашему инструменту для письма.

И давайте помнить, что вы технический специалист , поэтому редакторы WYSIWYG могут быть для вас лучшим вариантом, а могут и не быть. Вы не обязательно хотите (или даже хотите!) Навигация по меню, панелям инструментов и лентам для форматирования текста.

Что, если вместо этого вы могли бы легко добавить все свои стили форматирования прямо в текст в виде простого встроенного синтаксиса, чтобы получить полностью отформатированный текст?

Ну, на самом деле, вы можете. Это Markdown, и это то, о чем этот урок.

Когда больше значит меньше…

Программное обеспечение для обработки текстов написано для удовлетворения чрезвычайно широкого круга пользователей и вариантов использования и, как таковое, должно обеспечивать все виды функций. Но очевидно, что только небольшое подмножество этой функциональности, вероятно, будет иметь отношение к каждому отдельному пользователю. А для большинства пользователей, которые просто хотят создать документ (и им не нужно разрабатывать маркетинговую брошюру или плакат), уместно очень небольшое подмножество из множества доступных вариантов.

На самом деле Microsoft четко осознала это несколько лет назад, когда они переработали пользовательский интерфейс Microsoft Word в отдельные функциональные группы, которые они назвали «лентами». Тем не менее, что интересно, большинство пользователей скажут вам, что они нашли новый интерфейс более запутанным и трудным для навигации, чем его предшественник.

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

… и когда меньше значит больше

Признайте это, вы инженер-программист, а не графический дизайнер. Вы просто хотите написать это руководство, или технический документ, или отчет, и покончить с этим. Вы будете очень довольны некоторыми базовыми возможностями форматирования, такими как заголовки, маркированные или нумерованные списки и блоки кода. И, о да, форматирование шрифта (полужирный, курсив и т.д.) тоже было бы полезно. Вот об этом. (И если бы вы могли просто сделать это в vi, это было бы действительно здорово!)

Введите уценку.

Что такое уценка?

Джон Грубер (при существенном содействии технического гуру и интернет-активиста Аарона Шварца) создал язык Markdown в 2004 году с целью дать людям возможность «писать, используя простой для чтения и написания простой текстовый формат и, при необходимости, преобразовать его в структурно допустимый XHTML (или HTML)».

Markdown был разработан таким образом, чтобы его можно было читать как есть, и при этом он не выглядел так, как будто он был размечен тегами или инструкциями по форматированию (в отличие от текста, отформатированного с помощью языка разметки, такого как RTF или HTML, который может быть сложно создавать и трудно читать в необработанном формате). ).

Markdown позволяет вам писать в удобном для чтения и записи текстовом формате, который затем можно преобразовать в структурно допустимый HTML. Итак, если быть совсем точным, Markdown на самом деле состоит из двух вещей:

1. Синтаксис форматирования простого текста
2. Программный инструмент (первая версия которого была написана на Perl), преобразующий форматирование простого текста в формат HTML.

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

Изучите Markdown: начало работы

Маркдаун прост в освоении. Супер легко. Вы можете изучить основы за пять минут, и это быстро станет вашей второй натурой. И — точно так же, как взаимосвязь между CSS и препроцессорами CSS — вы можете использовать столько, сколько хотите.

Если вы привыкли к любым соглашениям о написании простого текста, возможно, вы уже знакомы с некоторыми соглашениями о разметке, такими как числа или тире в начале предложения для создания списка, звездочки вокруг слова для выделения и т. д. на. Так, например, если вы хотите отобразить что-то курсивом, просто оберните его звездочками, например *this* (в отличие от более неуклюжего синтаксиса HTML, такого как <span>this</span> ).

Точно так же вы можете указать заголовок H1, просто добавив к строке префикс '#' (например, # Section Heading вместо <h1>Section Heading</h1> ).

Еще одно полезное применение для изучения Markdown, особенно для нас, инженеров-программистов, — использовать его для документации по репозиториям исходного кода. Большинство репозиториев включают файл README.md ( .md — стандартное расширение для файла Markdown). Github, например, имеет свой собственный Markdown со вкусом Github, который добавляет дополнительные функции специально для документации по разработке. Это, безусловно, может сэкономить время по сравнению с необходимостью писать эту документацию в HTML.

В качестве простого примера предположим, что вы хотите включить в свою документацию следующий фрагмент:

<h2 style=color:#3863a0;font-size:1.5em;font-weight:600;margin-top:2em;margin-bottom:1em;line-height:1.3em;>Инициализация плагинов</h2>

Инициируйте pluginName в вашем контейнере с помощью jQuery следующим образом:

$(function() { $('#container').pluginName(); }); Используя идентификатор нашего контейнера, мы можем инициировать pluginName с помощью метода jQuery .pluginName() .

Вот сравнение того, как это будет сделано в HTML и Markdown:

Для получения дополнительной помощи по началу работы в Интернете есть множество руководств по Markdown, которые помогут вам освоиться, включая обзор Markdown от Джона Грубера (создателя Markdown), а также онлайн-руководство по Markdown.

Парсеры и инструменты Markdown

После того, как вы написали свою статью в Markdown, вам понадобится приложение для анализа синтаксиса в HTML. Есть несколько отличных бесплатных , в том числе:

• StackEdit — браузерный редактор Markdown, который имеет несколько вариантов синхронизации с популярными сервисами, такими как Google Диск и Dropbox.
• Онлайн-редактор Kramdown — еще один браузерный редактор Markdown с очень простым интерфейсом.
• Mou — лучший инструмент для записи Markdown для Mac, с которым я сталкивался, как более гиковский вариант для разработчиков; множество функций и бесплатно (пока в бета-версии) [это то, что я использовал для написания этой статьи]
• MarkdownPad — отличный редактор Markdown для Windows
• Texts — приятный кроссплатформенный (Mac и Windows) редактор; экспорт в несколько форматов, таких как PDF, .doc и ePub

Некоторые крупные платформы уже приняли (или, по крайней мере, разрешили) использование Markdown в своих редакторах для тех, кто хочет его использовать. В других, таких как WordPress, Evernote и Google Docs, встроенная поддержка (на момент написания этой статьи) еще не реализована, но сторонние разработчики представили собственные решения. Это включает:

• Популярная новая платформа для ведения блогов Ghost, стремясь упростить онлайн-письмо, использует Markdown для своего редактора контента.
• Для WordPress плагин Jetpack теперь официально поддерживает Markdown, который можно включить в разделе « Настройки» > «Обсуждение» , если вы используете плагин. Или вы можете использовать плагин, такой как WP-Markdown, который будет преобразовывать содержимое уценки вашего поста в HTML и обратно в Markdown, когда вам нужно его отредактировать.
• Для Evernote некоторые приложения Markdown, такие как онлайн-редактор Markable или редактор Mac Byword, позволяют экспортировать и публиковать непосредственно в заметки. Или, если вы предпочитаете использовать веб-приложение Evernote напрямую, вы можете использовать расширение браузера под названием Markdown Here, которое преобразует выбранную заметку, написанную в формате Markdown, в форматированный текст одним нажатием кнопки на панели инструментов.
• Документы Google еще не поддерживают Markdown, но некоторые редакторы (например, StackEdit) будут экспортировать/синхронизировать напрямую с Диском.

Недостатки

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

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

Возможно, самым большим недостатком — особенно для нас, инженеров, помешанных на контроле изменений, — является невозможность совместной работы в Markdown и отслеживания изменений (одно заметное исключение — плагин StackEdit для Google Docs). И, конечно же, с минимальными усилиями можно просто совместно работать над документом Markdown через репозиторий git и, таким образом, получить все отслеживание изменений и совместную работу, которые обычно необходимы.

Заключение

Итак, изучение Markdown доступно всем? Конечно, нет. Ни один инструмент никогда не является.

Но если вы инженер-программист, это вполне может быть именно тот инструмент для письма, который вы искали. Так что, если вы еще не пробовали, вам действительно стоит попробовать.