что такое формат markdown
Шпаргалка Markdown синтаксис в 2021
🎧 Часто пишете, редактируете или оформляете контент? Попробуйте Markdown!
Это мощный инструмент для копирайтеров, веб-разработчиков и контент-менеджеров. С его помощью вы сможете быстро и красиво оформлять текст. Синтаксис встроен в Ghost, Trello, Slack, Хабр и еще множество сервисов. Мы покажем несколько полезных трюков, которые сделают вас суперпользователем Markdown.
🎧 Слушайте аудио-версию этой статьи!
Что такое Markdown
Вот простой пример использования Markdown:
Попробуйте сами! Онлайн-редактор откроется в новом окне.
Почему Markdown так хорош
Да, но задумайтесь: сколько времени вы тратите на нажатие этих самых кнопок? Может, секунду или даже меньше. А если вас настигло вдохновение и мысли идут потоком? Даже за секунду легко потерять нить своего повествования.
Просто попробуйте использовать Markdown, и вы удивитесь, насколько естественен его синтаксис. Этим языком пользоваться намного проще, чем чистым HTML.
Когда вы привыкнете к Markdown, вам будет очень сложно вернуться к прошлой жизни бесконечных лишних кликов.
Мы создали для вас шпаргалку, в которой описали основные функции Маркдаун.
Базовое форматирование
Заголовки
Markdown сделает всё сам и отобразит вот так:
Заголовок 2
Заголовок 3
Заголовок 4
Текст
курсив
жирный
жирный курсив
ссылка
Картинки
Чтобы вставить картинку, используется такой же синтаксис, как у ссылки, только со знаком восклицания:
Списки
Цитаты
Цитаты оформляются с помощью символа >.
Это цитата
Если продолжить писать дальше, это тоже будет цитата.
Надо дважды поставить «Enter».
Исходный код
Что ещё
Продвинутые техники Markdown
Освоив простое форматирование с помощью Маркдауна, вам непременно захочется узнать, как его еще можно использовать. Что ж, продолжим.
Горизонтальная черта
Ссылки
Можно не прописывать адрес ссылки напрямую, а указать её атрибуты отдельно. Получается очень компактно. В коде это выглядит так:
Пример один, пример два.
Такие сноски можно использовать и для картинок.
Если прописать тайтл в обычной ссылке, это тоже сработает:
Наведите мышку: Яндекс
Еще можно поставить ссылку [1] на объясняющую сноску, как в книге.
Как открывать ссылки в новом окне в Маркдаун
Все ссылки в стандартном редакторе Markdown открываются в этом же окне. Только HTML-разметка позволяет изменить это. Никакие другие способы не будут работать стабильно и всегда, и в этом есть некоторое неудобство. Но имея заготовленный шаблон (смотрите ниже), вы легко справитесь с этим.
Таблицы на Markdown
Тут у Markdown перед HTML огромное преимущество. В нем делать таблицы гораздо проще:
Заголовок таблицыДругой заголовокЯчейка 1Ячейка 2Ячейка 3Ячейка 4
Символом : можно выровнять столбцы:
В таблице работает любое форматирование:
ВлевоПо центруВправопервая ячейкатекст2зачеркнутая ячейкажирная ячейкакурсивнезачеркнутая ячейкапросто ячейка
Воспринимает ли Markdown HTML
Горячие клавиши для MacOC
Markdown понимает сочетания горячих клавиш и сам вставляет необходимые символы. Например:
Горячие клавиши для Windows
Редакторы Markdown
Кроме использования Маркдауна в поддерживающих его синтаксис сервисах, вы можете попробовать приложения-редакторы.
Markdown для MacOS
Для Apple существует большое количество удобных программ:
Markdown для Windows
Для «микромягких» окошек программ, к сожалению, поменьше:
Что делать дальше
После пары часов использования Маркдауна ваши пальцы начнут летать над клавишами. Вы будете писать очень быстро, на ходу форматируя написанное.
Практикуйтесь, и у вас получатся превосходные статьи:
Не забывайте попробовать Онлайн-редактор.
🎧 Слушайте аудио-версию этой статьи!
Подпишись на AX.digital
Получай на свой e-mail все наши новые публикации.
Введение в Markdown
Все, что вам нужно знать, чтобы начать свое путешествие с Markdown.
Что такое Markdown?
photo Определение Markdown из Википедии
На изображении ниже вы можете увидеть файл, отформатированный с помощью Markdown в текстовом редакторе Sublime Text.
photo Пример форматирования Markdown на Sublime Text
Файл Markdown или MD состоит из простого текста, прост для понимания и не содержит всей этой разметки HTML, загрязняющей содержимое.
С помощью Markdown вы можете добавить к документу форматирование с помощью разметки символов.
Например, в Microsoft Word, который является редактором WYSIWYG, форматирование текста происходит при выборе определенного содержимого и нажатии определенной кнопки, комбинации клавиш или некоторого пункта меню.
photo Окно Microsoft Word - WYSIWYG
Эти символы используются процессором Markdown, чтобы узнать, какие слова / фразы следует форматировать при преобразовании файла в HTML.
Слишком запутались? Немного упростим.
Как редактировать файл Markdown
photo Редактирование документа Markdown в Notepad.
Однако интересно принять во внимание:
Хорошая новость в том, что:
photo Параллельные текстовые редакторы: Notepad ++, Sublime Text & Visual Studio Code.
ПРИМЕЧАНИЕ: стоит помнить, что форматирование Markdown чрезвычайно простое, поэтому документ, отформатированный на этом языке, остается читаемым.
Markdown против WYSIWYG
Если редактор WYSIWYG (который предлагает форматирование в реальном времени) чрезвычайно удобен, зачем мне использовать Markdown?
photo Сравнение форматирования Markdown и форматирования WYSIWYG.
Если я использую редактор WYSIWYG, я могу нажать кнопку и получить желаемое форматирование, почему я собираюсь печатать документ с разметкой Markdown?
Давайте посмотрим на некоторые причины использования Markdown:
Практика
Интересно, что для изучения синтаксиса языка у вас есть редактор Markdown.
photo Редакторы online, StackEdit, Dillinger и Editor.md
ПРИМЕЧАНИЕ: откройте один из редакторов online на другой вкладке браузера, чтобы обучить синтаксис Markdown в реальном времени.
StackEdit
photo Интерфейс редактора Web Markdown StackEdit
См. Дополнительную информацию о StackEdit в разделе инструментов.
Dillinger
Dillinger имеет очень простой интерфейс, но предлагает несколько вариантов редактирования документа Markdown. Помимо преобразования в реальном времени, вы также можете экспортировать файл в форматы HTML и PDF.
photo Интерфейс редактора Web Markdown Dillinger
Для получения дополнительной информации о Dillinger [a1] нажмите здесь.
Editor.md (Markeditor)
photo Интерфейс редактора Web Markdown Editor.md
А потом?
Набравшись опыта, вы можете загрузить приложение для своей операционной системы и приступить к редактированию документов локально.
В разделе «Инструменты a1]» вы найдете обширный список приложений с инструкциями по их использованию и информацией о совместимости с элементами Markdown.
Что ж, теперь, когда у вас есть редактор для практики Markdown, давайте разберемся, как работает преобразование из одного формата в другой.
Как конвертировать файл Markdown
Давайте разберемся с процедурой, используемой приложениями Markdown для преобразования вашего файла md в другой формат, обычно HTML или PDF.
photo Как конвертировать файл Markdown
Простота Markdown
photo Расширения файлов Markdown
Файл Markdown представляет собой простой текст, не имеет форматирования, не является зашифрованным и, тем более, скомпилированным.
ПРИМЕЧАНИЕ: Эта простота позволяет программам анализировать ваш текст на предмет символов, которые идентифицируют элементы Markdown.
Несколько приложений Markdown, помимо редактора, также имеют встроенный конвертер. Конвертер отвечает за перевод синтаксиса Markdown в другой формат.
photo Файлы, созданные из форматированного Markdown
Как происходит преобразование
Конвертер Markdown использует Parser для сканирования своего содержимого на предмет маркировки, совместимой с Markdown; При нахождении совместимой разметки Parser проверяет, есть ли совпадение в выходном формате, например tag HTML, который производит такое же форматирование.
Ниже вы можете увидеть примерную таблицу соответствия между маркером Markdown и tag HTML.
photo Таблица сравнения синтаксиса Markdown и HTML.
Обратите внимание, что формат HTML является одним из наиболее часто используемых для преобразования Markdown. Ваш файл, преобразованный в HTML, можно просмотреть в любом браузере Web, таком как Google Chrome, Mozilla Firefox и Microsoft Edge.
На изображении ниже вы можете увидеть упрощенную версию процесса конвертации.
photo Простая схема создания крышки между Markdown и HTML.
Подведем итоги преобразования в четыре этапа.
Некоторые моменты следует выделить
Использование Markdown
photo Публикация в Reddit с помощью Markdown
Вы также можете форматировать списки задач, сообщения e-mails, списки покупок и многое другое.
Ниже вы можете увидеть несколько примеров документов, которые можно создать с помощью Markdown.
Сайты
Джон Грубер и Аарон Шварц разработали Markdown, думая о Internet, поэтому создание контента для Web стало одной из самых привлекательных сторон языка.
Многие приложения, совместимые с Markdown, уже автоматически конвертируют свое содержимое в HTML.
photo Автоматическое преобразование из Markdown в HTML
Вы можете создавать полные веб-сайты, используя в качестве основы форматирование Markdown. Если это то, что вы хотите сделать, вам могут помочь такие инструменты, как Jekyll и MkDocs.
GitHub Pages предоставляет бесплатный хостинг для вашего статического веб-сайта.
Если вам нужно что-то более надежное, например, менеджер контента, знаменитый CMS, взгляните на Ghost.
Вы пользуетесь WordPress? Сайты, размещенные на WordPress.com, уже поддерживают Markdown, но вы можете использовать plugin Jetpack для сайтов, находящихся на других серверах хостинга.
Форматировать текст
Простота Markdown обходится без всех ярких опций редактора WYSIWYG, таких как Microsoft Word, но при этом предлагает достаточно форматирования для редактирования ваших документов.
Язык поддерживает полужирный шрифт, курсив и зачеркивание, в дополнение к, конечно, спискам, заголовкам, blockquotes и многому другому.
photo Форматирование полужирным шрифтом, курсивом и зачеркиванием в Markdown
Еще одним преимуществом форматирования документов с помощью Markdown является возможность преобразования их практически в любой другой формат текстового файла.
Ниже представлен список приложений для создания / редактирования документов Markdown:
Примечания
Вот список приложений, совместимых с Markdown.
А Evernote? OneNote? Кто-нибудь.
Что касается приложений для создания заметок, то Evernote и OneNote, без сомнения, являются самыми популярными. К сожалению, эти две программы по умолчанию не поддерживают Markdown.
В случае Evernote вы можете использовать Markdown Here или Marxico.
Книги
Что вы имеете в виду при написании книг с помощью Markdown?
Правильно, такие службы, как Leanpub, используют файлы Markdown в качестве основы, преобразование выполняется для EPUB, MOBI и PDF.
Не очень любите электронные книги?
С файлом созданной вами электронной книги вы можете загрузить его в другие службы, такие как Kindle Direct Publishing, и создавать физические копии.
Презентации slides
Да, вы правильно прочитали, вы можете создавать презентации из slides, используя Markdown.
Предпочитаете использовать приложения? В macOS вы можете ссылаться на Marked или Deckset. В Windows мы можем преобразовать Markdown в slides, используя Pandoc.
Создание презентаций с использованием разметки Markdown может показаться пустой тратой времени, однако, немного попрактиковавшись, вы обнаружите, что это намного проще и быстрее, чем использование таких инструментов, как PowerPoint или Keynote.
E-mails
photo Интерфейс создания Gmail email
Да, Markdown Here бесплатен, имеет открытый исходный код и мгновенно конвертирует Markdown в HTML.
Техническая документация
Markdown и техническая документация идут рука об руку. Бесчисленные компании используют файлы квугвтовзл для хранения своей документации.
GitHub перенесли свои документы на Markdown с помощью инструмента Jekyll. Кроме того, один из самых известных архивов в мире, README.md из GitHub, состоит из Markdown.
photo Документация GitHub
ПРИМЕЧАНИЕ: GitHub использует небольшой вариант Markdown, называемый GitHub-flavored Markdown.
При создании технической документации вам могут помочь следующие инструменты:
Ароматы Markdown
Представьте себе все разные диалекты, существующие в одном языке, сленг, произношения, акценты. Даже носителям языка иногда бывает сложно понять некоторые вещи.
photo Варианты синтаксиса Markdown
Что ж, как и в случае с языками, реализации Markdown в разных программах также могут отличаться, даже если разница незначительна, она все равно может вызвать путаницу.
Варианты Markdown называются Flavors, например, GitHub использует немного более надежную версию Markdown, называемую GitHub-flavored Markdown или GFM.
Некоторые приложения используют только базовый синтаксис, другие используют комбинацию базового синтаксиса и расширенного синтаксиса, и, наконец, есть приложения, которые время от времени реализуют элементы обоих.
Вывод
В этой статье вы узнали об основных аспектах Markdown, о том, что вы можете с ним делать, и о различных его реализациях.
Следующим шагом является изучение основного синтаксиса языка или, если вы уже уверены, обратитесь к разделу tools, чтобы начать использовать Markdown.
Markdown: что это и кому нужно
Для всех, кто пишет контент, сайты и программы.
В вебе есть стандартный язык разметки — HTML. Его понимают браузеры, но человеку читать чистый HTML-код тяжело — мешают теги и обилие служебной информации. Например, наша главная страница в HTML выглядит как-то так:
Читать чистый HTML технически можно, но это сложно
Чтобы понять, почему так, нужно вспомнить истоки HTML. Когда его только создавали, у него была задача описывать гипертекстовые документы: то есть документы, в которых будет текст и гиперссылки. При этом передаваться он должен был по очень медленным каналам. Первые HTML-страницы были минималистичными: только текст, заголовки, таблицы и редкие ссылки.
Постепенно веб развивался, сайты становились всё сложнее: появлялся дизайн, меню, навигация, картинки, табличная вёрстка. Но всё это по-прежнему выражалось языком простых текстовых документов. В него добавлялись новые теги, он усложнялся, и вот дорос до тех джунглей, в которых нам приходится работать сейчас.
Весь веб, который вы сейчас видите, сделан на «костылях» от простого языка для разметки текста.
Что такое Markdown
Markdown — это язык текстовой разметки документов. Его придумали в 2004 году блогер Джон Грубер и интернет-активист Аарон Шварц, чтобы быстро форматировать статьи. Требования к языку у них были такие:
В результате у них получился простой язык, который активно используется до сих пор.
Смысл маркдауна в том, что вы делаете разметку своего документа минимальными усилиями, а уже какой-то другой плагин или программа превращает вашу разметку в итоговый документ — например в HTML. Но можно и не в HTML, а в PDF или что-нибудь ещё. Маркдаун — это как бы язык для других программ, чтобы они формировали документы на основе вашего текста.
Единственное, что вам может понадобиться, — настроить в этом плагине шрифты, отступы и цвета, чтобы результат выглядел красиво. Один раз настраиваете, а потом быстро пишете много материалов, которые на выходе превратятся в готовые статьи с хорошей разметкой.
Наша статья про дизайн и код в Markdown-редакторе Typora. Выглядит неплохо. 
А вот её исходный код — всё можно прочитать даже без красивого форматирования
Синтаксис
Для оформления заголовков используют решётку. Одна решётка — заголовок первого уровня, две — заголовок второго уровня, и так до пятого. Посмотрите на скриншотах выше, как это работает.
## Это будет заголовком второго уровня (как Синтаксис в этом разделе)
Чтобы выделить слово или абзац, используют одну звёздочку в начале и в конце:
Если нужно выделить сильнее, берут две звёздочки:
**выделяем текст сильнее** → выделяем текст сильнее
Зачёркивают двумя тильдами:
Для оформления кода используют обратный апостроф: `.
`Пример кода` → Пример кода
Если нужно оформить много строк кода, тогда перед каждой из них ставят 4 пробела или один таб. Ещё можно взять такой блок в три обратных апострофа подряд — в начале и конце кода:
Sir Markdown. Лекция Яндекса
При разработке документации мы руководствуемся не только стандартами, но и удобством её использования. Стандарты определяют состав и форму документации, а формат строится исходя из удобства. Разработчик Сергей Бочаров рассказывает о пути Markdown-документа и о проблемах, которые приходится решать в обмен на простоту использования этого формата.
У меня иногда складывается впечатление, что не он служит для нас, а мы служим для этого формата. Поэтому — сэр Markdown.
— Мы знаем, что ныне лежит на весах
И что совершается ныне.
Час мужества пробил на наших часах,
И мужество нас не покинет.
Не страшно под пулями мертвыми лечь,
Не горько остаться без крова.
И мы сохраним тебя, русская речь,
Великое русское слово.
Свободным и чистым тебя пронесем,
И внукам дадим, и от плена спасем —
Навеки.
Добрый вечер, друзья, меня зовут Сергей Бочаров. Я начал со стихотворения Анны Ахматовой «Мужество». Оно было написано в 1942 году, в период Великой Отечественной войны, и уже тогда поэтесса понимала, что вернуть, выстроить разбитые бомбежкой заводы и фабрики будет гораздо легче, чем вернуть духовное богатство, растраченное и фактически растоптанное за годы войны.
Поэзия является одним из немногих средств, которое помогает нам научиться чувствовать прекрасное. Сегодня мы говорим о технической документации — казалось бы, такой далекой области от поэзии, но сохранение прекрасного, сохранение единого стиля очень актуально, особенно при работе с данным форматом. Markdown де факто стал стандартом написания технической документации в мире открытого ПО. И объединил людей разных специальностей.
У меня тяжелая и одновременно приятная миссия. Я хочу, чтобы у вас осталось полное ощущение сборки Markdown-документации в Яндексе, а также поделюсь инструментами, которые мы разработали. Надеюсь, вы тоже будете их использовать в своих проектах.
Инструменты, которые разработаны, написаны на JS, потому что мы в Яндексе любим JavaScript. И вся разработка ведется вокруг этого языка. Тут не стоит расстраиваться, если у вас другая среда разработки или хайповый React — думаю, можно найти аналоги на GitHub.
Наверное, многие задаются вопросом, почему же Markdown стал сэром? Это метафора, и она связана с тем, что мы в Яндексе стараемся роботизировать любой процесс.
Вокруг Markdown тоже разрабатывается большое количество инструментов. На сегодняшний день мы уже разработали очень много инструментов, продолжаем разрабатывать. У меня иногда складывается впечатление, что не он служит для нас, а мы служим для этого формата. Поэтому — сэр Markdown.
В первой глобальной части мы поговорим о том, зачем мы пишем в этом формате, зачем разрабатываем для него какие-то инструменты. Во второй части поговорим более детально на примере нашей библиотеки о том, как сохранять качество контента, как переводить его и как из множества репозиториев собирать один сайт.
Markdown был создан в 2004 году Джоном Грубером и Аароном Шварцом. Идея заключалась в том, чтобы иметь простой текстовый синтаксис и затем его конвертировать в более богатый и валидный HTML.
У нас есть заголовок первого уровня, второго уровня и какой-то абзац текста.
Зачем новый формат, когда есть DITA с более богатыми тулзами? Зачем создавать новые инструменты для Markdown? Давайте попробуем ответить вместе.
У DITA более сложный синтаксис, и для работы с ней желательно иметь определенную среду разработки. Понятно, что это XML-формат, он также открывается в текстовом редакторе. Но SVG тоже в нем открывается, при этом никто там не рисует — все используют Photoshop или Sketch.
Markdown с точностью до наоборот имеет более легкий синтаксис, поэтому он так полюбился многим разработчикам. Как следствие, документация в Markdown пишется и поддерживается техническим писателем с активным участием контрибьюторов и разработчиков, а документация в DITA часто разрабатывается только техническим писателем, активного участия разработчики и контрибьюторы не принимают.
Ярким примером сайта с документацией Markdown является сайт npm, на сегодняшний день он содержит 475 тысяч модулей, и с каждым днем их становится все больше. 
Вот самые популярные из них. Если зайти на сайт любого, например Gulp, и перейти в раздел документации, мы сразу попадаем на GitHub, где видим, что API gulp.js описано в Markdown.
Поэтому если вы по каким-то причинам еще не используете Markdown или обходите его стороной — пожалуйста, используйте и сделайте ваших разработчиков счастливыми.
Стиль и синтаксис. Предлагаю рассмотреть на примере нашей внутренней библиотеки Лего, суперсекретной. Сейчас продемонстрирую.
Неожиданно, правда? Все эти блоки различны. Вот блок logo, teaser и т. д. И хранятся они на GitHub, стандарт де факто. 
Здесь есть общее описание библиотеки, также есть директории блоков, и в каждой директории есть описание этого блока. Документацию мы рассматриваем как часть кода, поэтому называем соответствующим именем. Это также удобно в случае замены, search & replace. Когда-то над каждым документом поработал технический писатель. Над англоязычными версиями также поработал переводчик, и в идеале документация, русская и англоязычная версии, должны быть консистентны, то есть структура и содержание у них должны быть одинаковыми.
Над документацией также активно работают сами разработчики, их очень много. Процесс, который мы стараемся выстроить в компании, выглядит следующим образом: разработчик, разработав новую функциональность или новый блок, ставит задачу техническому писателю в виде пул-реквеста или issue.
Технический писатель эту функциональность описывает, после чего отдает на перевод, если нужна языковая версия документа. И все счастливы, но это идеальный мир. А в реальном мире часто ситуация следующая: разработчик сам приходит и вносит правки в документацию. 
Здесь мы сталкиваемся с первой проблемой — потерей консистентности. Следующая проблема — также изменяется стиль написания документации. 
Кажется — подумаешь, главное-то, что функциональность описана. Оказывается, нет. После того, как документ написал технический писатель, разработчики были счастливы.
Потом, когда туда со своими коммитами пришли еще несколько десятков разработчиков, они уже подрасстроились и в итоге заплакали. Говорят — нужно переписать документ, он стал непонятный, его невозможно читать, там очень много различных непонятных конструкций, мертвяков, маркеров проблемного текста.
С ними нужно как-то уметь бороться. Технические писатели знают и умеют с ними бороться, а разработчики часто допускают их в документации, и такую документацию некомфортно читать. 
Например, тут всем комфортно? Все понимают, о чем речь? Очевидно, речь идет о git, и такое встречается в нашей документации. Вот более понятный вариант. 
Разработчики, которые имеют небольшой опыт работы с GitHub, иногда встречают сложности, когда читают документацию, которую написали гуру-разработчики. Поэтому мы добавляем следующую проблему — сохранение стиля и терминологии. Разработчики очень много коммитят, и технического писателя уже практически не видно, единство стиля нарушено.
Следующая проблема при таком подходе — у нас нарушается синтаксис. Markdown позволяет писать совершенно по-разному и получать один и тот же результат. У разработчиков технической документации на каждый случай есть договоренность о том, как мы пишем заголовки, списки, вставляем скриншоты и т. д.
Действительно, реальность часто отличается от желаемого, и с этой проблемой тоже нужно уметь бороться. Казалось бы, результат ожидаемый, но если эту проблему не решить сейчас, ее придется решать на этапе сборки. Часто возникает задача — например, найти все заголовки третьего уровня с бэктиками и увеличить на два пикселя. Если мы ее не решаем на этапе линтинга, то придется решать ее на этапе сборки, писать большие скрипты. 
Поэтому обавляем следующую проблему — синтаксис Markdown. У нас получилось три основных вызова, с которыми мы боремся. Также у нас есть опенсорсные проекты, в частности БЭМ. У опенсорсных проектов помимо разработчиков, технических писателей и переводчиков есть еще контрибьюторы. Контрибьюторы помогают делать наши продукты лучше, за что мы им благодарны. Их очень много. Они присылают нам свои пул-реквесты, а мы с ними делимся качественным контентом. Поэтому однозначно надо как-то искать пути решения. 
Следующий раздел посвящен автопроверке, линтингу. Тому, что можно сделать, чтобы как-то научиться согласованно проверять синтаксис Markdown, находить грамматические ошибки и маркеры проблемного текста. Это мой любимый раздел. Считаю, прогрессия линтинга работает на прогрессию технического писателя.
Начнем с инструмента под названием remark-lint. Он позволяет проверять синтаксис и стиль написания. Сам remark находится в открытом доступе, он разработан не нами, мы его используем, у него есть собственный набор правил, их больше 50. Поверх этих правил мы написали свои правила, внесли наш гайд в remark.
Как это работает? Допустим, есть тестовый файл с содержанием, есть заголовок первого уровня, второго и какой-то список.
Мы вводим команду в терминале. Это команда у нас на прекоммите обрабатывается, показываю. Когда технический писатель совершает коммит на GitHub и документ в порядке, выводится сообщение, что ошибок нет. И коммит уходит на GitHub. Предположим, у нас есть ошибки — например, сделаем в первом заголовке его вторым уровнем, а во втором заголовке добавим «Привет» и восклицательный знак. Выполняем ту же команду, и у нас появляется три ошибки.
Прогрессия линтинга работает на прогрессию технического писателя. Технический писатель вспоминает, что мы договорились не ставить восклицательные знаки в заголовках, правит, все отлично. Как же подключаются эти правила? В корне проекта лежит файла remarkrc, в нем мы определяем набор собственных правил (их я сократил) и набор заимствованных правил самого remark.
Следующий инструмент — yaspeller. Он проверяет грамматику и наличие орфографических ошибок в документации. Документация есть на Яндекс.Технологиях — она, кстати, написана в git. Вы можете ее прочитать, там все работает по тому же принципу: есть орфографическая ошибка — выводится сообщение. Контрибьюторы, разработчики, которые пытаются сделать вам пул-реквест, прислать какие-то исправления, они не смогут их прислать с орфографическими ошибками или неточностями в синтаксисе Markdown. Так что эти инструменты очень удобно подключать, и отрабатывают они на прекоммите.
Следующий раздел посвящен переводу. Мы разработали инструмент md2xliff. Переводим мы очень много опенсорсной документации и чуть-чуть внутренней. В случае опенсорсной документации у нас есть контрибьюторы, которые присылают свои пул-реквесты, а чтобы им было удобнее их присылать, мы для них на нашем сайте делаем плашки, в которых предлагаем им пройти по ссылке либо через интерфейс GitHub, либо используя сервис prose.io. Например, они заходят, вносят изменения, нажимают ОК, и к нам прилетает пул-реквест.
Как же все это поддерживать? Допустим, документ написал технический писатель, переводчик его перевел, пришел пользователь — изначально в русскоязычную версию — и что-то там поправил. Как быть с английской версией? Нужно там что-то править или нет? Непонятно. Как искать опечатку, что была исправлена, тоже непонятно. Либо можно пойти на GitHub и там в diff смотреть разницу. Но это та еще задача, нужно же поставить ее переводчику. Необходимо искать решение. 
Бывает вторая ситуация. Например, разработчик написал вторую версию библиотеки, и взял не весь документ, не переписал 30 страниц, а тут кусочек удалил, там добавил. И если удалил — непонятно, что делать. Надо идти и как-то сверять это в diff на GitHub.
Как быть? Кажется, это сложная ситуация, при которой выхода нет. Однако если кто-то из вас работал с переводами, он наверняка знает, что есть куча стандартов, и при ближайшем рассмотрении решение выглядит примерно так: есть тестовый файл и какой-то текст документации, который лежит на GitHub. Что нужно сделать? Нужно сгенерировать из него два файла, скелет и XLIFF перевода.
Скелет представляет из себя блочное форматирование, то есть мы подменяем куски текста на такие плейсхолдеры с цифрами.
XLIFF — специальный формат, он описан, у него есть спецификация, там все просто. Самое главное, что в XLIFF есть юниты, и id юнита соответствует тому сегменту, который мы подменили в скелете.
Также в каждом юните есть два тега: source и target. В теге source находится именно тот кусок текста, который мы заменили в скелете, а поле target изначально пустое. Мы отдаем этот XLIFF переводчику. Теперь поле target на выходе заполнено. После перевода делаем обратную генерацию и получаем английскую версию документа.
При этом перевод у нас никуда не пропадает, а сохраняется в специальном стандартизированном XML-файле TMX. Там лежат два значения: source и target. Как это нам помогает? Возвращаемся к прошлой ситуации. Пришли контрибьюторы, разработчики или другой технический писатель и что-то поправили в исходном документе. В русскоязычной версии, например. 
Мы по-прежнему генерируем XLIFF, отдаем его переводчику, он применяет ту базу, которая у него сохранена в программе и переводит ровно те сегменты, которые изменились. Он не переводит строки, которые имеют стопроцентное совпадение — они сами автозаменой заменяются. Таким образом, больше нет проблемы искать, что же поменялось. Мы гарантируем, что все строки, которые хоть как-то были изменены, будут видны в переводе. Далее мы генерируем английскую версию документа, все просто. Кажется, что есть готовое решение — просто потому что наверняка они должны быть.
Есть smartcat.ai от ABBYY, есть решение от Google и есть Matecat. Но тотальные недостатки этих решений в том, что они не поддерживают Markdown, у которого нет единого стандарта того, как писать. И они обходят его стороной, поддерживают любые стандартизированные форматы. На прошлой неделе я проверял Markdown в matecat, там все краснеет. Хотя Markdown был простенький.
Возьмем, например, наш инструмент со сложной вложенностью. Если у вас код, внутри него три бэктика, и там есть JSDoc, он со всем справляется на 99%, уровень вложенности может быть любым.
Второй фатальный недостаток этих сервисов — они не интегрируются с GitHub. Мы же хотим, чтобы к нам пользователь пришел через ссылку и что-то поправил, а они не интегрируются. 
Мы все это обсуждали. Когда есть исходный документ на русском, и мы переводим на другой язык, у нас есть определенная пара, жесткая привязанность к русскому языку. Мы работаем над тем, чтобы избавиться от этой привязанности, чтобы мы могли править TMX на лету, независимо от того, куда придет пользователь. Он может прийти в русскую версию, а может в английскую, и мы должны развернуть TMX прямо при генерации. Пока это не решено.
Сборку сайта предлагаю рассмотреть в рамках общего обзора пути Markdown-документа от момента написания до момента выкладки на сайт.
Как выглядит рабочий процесс? Предположим, план работ составлен, собрана вся информация. Если говорить о Markdown, здесь важно соблюдать договоренность о синтаксисе. После чего происходит автопроверка, она отрабатывает на прекоммите наши линтинги. Далее документ попадает на GitHub. Если нужна англоязычная версия, мы документ локализуем. После происходит сборка, и там две истории. Одна — когда документ один к одному мапится на страницу, а вторая — когда нужно построить различные инлайновые примеры. В страничку нужно встроить iframe и т. д. У нас есть инструмент, который все это умеет, горшочек. Он умеет подменять ссылки, объединять различные Markdown-документы в один, умеет строить инлайновые примеры. Затем происходит выкладка на сайт.
Зачем вообще нужен сайт? Почему, как на gulp.js, не хранить всю документацию в Markdown? 
Ответ очевиден — нужна единая точка входа. У нас больше ста репозиториев, и мы хотим, чтобы эти документы были собраны в одном месте. Также нужны поиск, навигация и живые примеры. Живые примеры выглядят так.
Один и тот же документ на GitHub и на сайте рендерится по-разному. Мы можем открыть его в новом окне, покликать по кнопке, посмотреть ее HTML. Это очень удобно.