Как сделать файл markdown

Обновлено: 05.07.2024

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

Процесс отображения оформления текста может называться по-разному, например: интерпретация, рендеринг или сборка документа. Далее будем использовать термин сборка.

Одним из наиболее простых языков разметки является markdown. Среди других языков стоит выделить HTML (используется для оформления web-страниц) и Latex (оформление научных статей и других документов). Популярный текстовый редактор Word также использует собственный язык разметки для внутреннего представления данных.

Тег markdown представляет собой символ или группу символов. Возможно два способа применения тегов. Если тэг стоит в начале строки, то он действует на все символы строки. Если тэг стоит в начале и конце фрагмента текста, то он действует на этот фрагмент текста.

После сборки будет выглядеть так:

Структура документа

Текст документа состоит из слов. Слова отделяются друг от друга пробелами или символами табуляции или конца строки. Независимо от количества пробелов или наличия символов табуляции и конца строки после сборки между словами будет один пробел.

Слова группируются в предложения, после последнего слова которых ставят точку. Предложения группируются в абзацы. В исходном коде markdown абзацы отделяются пустой строкой, после сборки каждый абзац начинается с новой строки.

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

Тег	Значение
* или _	курсив
**	жирный
~~	зачеркнутый
***	жирный с курсивом

Если в тексте документа требуется отобразить символ, который используется как тег, то этот символ нужно экранировать с помощью обратного слеша. Например, следующий текст:

* – это звездочка, а не курсив и не список.

Вставки

В дополнение к отформатированному тексту в markdown можно вставить дополнительные элементы.

Для вставки гиперссылки используется следующая конструкция:

Например, исходный текст:

Для вставки картинки используется следующая конструкция:

Альтернативный текст будет показываться в то время, когда картинка загружается. Например, исходный текст:

будет собран в такую картинку: .

Для вставки более сложных элементов (например, видео) или использования более сложных элементов оформления в исходный текст на языке markdown могут быть вставлены теги языка HTML. Например, следующим образом можно создать метку в тексте:

а затем сослаться на нее:

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

Читаемость, однако, подчеркиваю, превыше всего. Документ в Markdown формате должен восприниматься как есть, как обычный текст, что бы не бросались в глаза ни теги, ни инструкции форматирования. Синтаксис Markdown испытал влияние нескольких существующих фильтров преобразования текста в HTML (в том числе Setext, atx, Textile, reStructuredText, Grutatext, и EtText) и крупнейший источник вдохновения для Markdown синтаксиса был простой текст электронных писем.

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

Вставка HTML

Для создания разметки, которую синтаксис Markdown не обеспечивает, можно просто использовать сам HTML. Нет необходимости обёртывать HTML в какие-либо специальные разделители, чтобы достигнуть переключения из Markdown в HTML; достаточно начать использовать тэги HTML.

Единственное ограничение состоит в том, что блочные элементы HTML (то есть

Синтаксис форматирования Markdown не обрабатывается внутри блочных элементов HTML. Например, нельзя использовать маркдауновское *выделение текста* (см. ниже) внутри блока HTML.

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

В отличие от блочных элементов HTML, во внутристрочных элементах HTML обрабатывается синтаксис Markdown.

Автоматическое кодирование специальных символов

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

Заголовки

Цитаты

Цитаты могут содержать и другие элементы Markdown — заголовки, списки, кодовые блоки:

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

Списки

Markdown позволяет составлять нумерованные и ненумерованные списки.

В качестве маркеров ненумерованного списка используются звёздочки, или плюсы, или дефисы; эти символы могут для этой цели использоваться взаимозаменяемо.

Скажем, вот этот пример:

совершенно равносилен вот этому:

Нумерованные списки используют в качестве маркеров числа с точкою:

Конкретные числа, которые используются при разметке списка, не оказывают никакого влияния на производящийся Маркдауном итоговый HTML-код. По вышеприведённому списку Markdown изготовит такой HTML-код:

Если вместо этого записать список так:

то получится совершенно тот же HTML-код. Смысл в том, что при желании автор может использовать порядковые номера элементов в списке, чтобы они соответствовали номерам, получающимся в HTML. Но также автор может и не тратить на это своё время, если это не особенно для него важно.

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

Маркеры списков обычно начинаются с начала строки, но им могут предшествовать до трёх пробелов. За маркером должен следовать либо пробел (один или более), либо символ табуляции.

Для красоты можно снабжать последующие строки списка отступами:

Но если нет надобности, то на это можно не тратить время:

Если элементы списка разделяются пустыми строками, то Markdown обернёт эти элементы тэгами

в своём итоговом HTML-коде. Скажем, вот этот список:

будет преобразован к виду

а зато вот этот:

будет преобразован к виду

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

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

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

К сожалению, нумерованный список можно начать случайно, просто написав что- нибудь в таком духе:

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

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

Блоки кода

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

будет преобразован Маркдауном в следующий HTML-код:

Один уровень отступа (4 пробела или 1 символ табуляции) устраняются из каждой строки кодового блока. Например, вот этот текст:

будет преобразован к виду

Блок кода продолжается до тех пор, покуда не отыщется строка без отступа (или конец текста).

примет вид следующего HTML-кода:

Обычный синтаксис Markdown не обрабатывается внутри блоков кода. Например, звёздочки внутри кодового блока считаются просто звёздочками в буквальном смысле. Так что нетрудно использовать Markdown, чтобы на нём писать о его собственном синтаксисе, приводя наглядные примеры.

Горизонтальная черта

Чтобы создать горизонтальную черту (соответствующую HTML-элементу ), достаточно поместить три (или более) дефиса, или звёздочки, или символа подчёркивания, на отдельной строке текста. Если угодно, между дефисами или звёздочками можно располагать пробелы. Каждая из следующих строк соответствует горизонтальной черте:

Встроенные элементы

Гиперссылки

Markdown поддерживает три стиля оформления гиперссылок:

Первая пара стилей предполагает, что помимо URLа существует ещё текст ссылки; в разметке он [заключается в квадратные скобки].

Гиперссылка с немедленным указанием адреса

Чтобы создать ссылку с немедленным указанием адреса, надобно немедленно после закрывающей квадратной скобки поместить обычные (круглые) скобки; в этих круглых скобках приводится тот URL, на который указывает гиперссылка, а за ним может ещё быть указан (в кавычках) всплывающий заголовок-подсказка ссылки. Вот пример:

Из этого примера выйдет следующий HTML-код:

Для ссылок на локальный ресурс (то есть расположенный на том же сервере) можно использовать относительные пути:

Гиперссылка, подобная сноске

Ссылка, подобная сноске, вместо целевого адреса использует вторую пару квадратных скобок, внутри которых помещается метка, идентификатор ссылки:

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

Затем, где угодно в документе, следует определить эту метку ссылки, для чего используется отдельная строка следующего примерно вида:

Строка эта состоит из следующих элементов:

Идентификатор ссылки, окружённый квадратными скобками (которым может предшествовать необязательный отступ — от одного до трёх пробелов).
Двоеточие,
Один или несколько пробелов (или символов табуляции).
URL гиперссылки.
Необязательный заголовок (всплывающая подсказка) гиперссылки, заключённый либо в двойные или одиночные кавычки, либо в скобки.

Три следующие определения ссылки совершенно равносильны:

URL гиперссылки может (но не обязательно) быть помещён в угловые кавычки:

Можно поместить заголовок на следующей строке, а перед ним отступ из пробелов (или символов табуляции); с длинными URL такая запись выглядит красивее:

Такие определения ссылок используются только для создания самих ссылок при обработке текста в Markdown; из итогового HTML-кода определения ссылок убираются.

Идентификаторы ссылок могут состоять из букв, цифр, пробелов и знаков пунктуации, однако они не чувствительны к регистру. Например, вот эти две ссылки:

и затем определить гиперссылку:

Так как имена ссылок могут содержать пробелы, то этот способ сработает и тогда, когда текст гиперссылки состоит из нескольких слов:

А затем определите гиперссылку:

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

Преимущество гиперссылок, подобных сноскам

Вот пример англоязычного текста, снабжённого сноскоподобными гиперссылками:

Используя подразумеваемый ярлык гиперссылки, вместо этого можно записать:

Каждый из этих примеров преобразуется Маркдауном к следующему HTML-виду:

Для сравнения, вот тот же абзац, записанный в Markdown ссылками с немедленным указанием адреса:

Смысл ссылок, подобных сноскам, не в том, что их проще записывать. Смысл в том, что с такими ссылками сам абзац занимает 81 символов, в то время как с немедленным указанием адреса он занял бы 176 символов, а в HTML занимает 234 символа. Таким образом, в HTML разметка занимает даже больше места, чем сам текст.

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

Смысловое выделение текста

Например, вот этот текст:

будет преобразован в следующий HTML-код:

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

Выделенный фрагмент может находиться и в середине слова:

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

Кодовые фрагменты строк

Он соответствует следующему HTML-коду:

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

HTML-код получится таким:

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

HTML-код этого примера получится таким:

Внутри кодового фрагмента строки все амперсанды и угловые скобки преобразуются к виду соответствующих HTML-сущностей (HTML entities), что упрощает включение примеров на языке HTML. Например, Markdown преобразует вот этот текст:

к следующему HTML-виду:

Можно также написать:

и получить следующий HTML-код:

Изображения

Иными словами, он состоит из следующих элементов:

Восклицательный знак.
Квадратные скобки, в которых указывается альтернативный изображению текст (он станет содержимым атрибута alt в элементе img).
Круглые скобки, содержащие URL или относительный путь изображения, а также (необязательно) содержимое атрибута title (всплывающей подсказки к изображению), заключённое в двойные или одиночные кавычки.

Изображения в подобной сноскам манере записываются следующим образом:

Следует отметить, что Markdown не позволяет задать размеры изображения (ширину, высоту); если же такое задание важно, то следует использовать обычный элемент языка HTML.

Прочее

Простая вставка URL

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

и Markdown сделает из него HTML-код

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

Например, вот такой адрес:

преобразуется к такому примерно виду:

Употребление обратной косой черты

Вот полный список символов, перед которыми в Markdown можно поставить обратную косую черту, чтобы они были восприняты буквально:

Послесловие

Этот текст написан с помощью разметки PHP Markdown Extra.

Изначально не хотел публиковать на своей страничке этот текст, но в русском переводе отсутствовал перевод идеалогии Markdown. Вторым "за" было - гарантия доступности перевода 2 .

Обращать внимание в тексте принято с помощью курсива, или, если этого не хватает, с помощью выделения жирным. В английском языке слово emphasis имеет значения - внимание, выделение, курсив. В оригинале получается что-то вроде игры слов. ↩

В разделе рассмотрен синтаксис классической реализации Markdown от Джона Грубера [John Gruber].

Содержание:

HTML-теги и разметка Markdown.

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

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

Единственные ограничения заключаются в том, что HTML-элементы уровня блока - например

Обратите внимание, что синтаксис форматирования Markdown не обрабатывается на уровне блока. Например, можно использовать стиль Markdown emphasis внутри HTML-тегов. HTML-блок.

HTML-теги уровня span - например , , или - могут использоваться/вставляться в любом месте абзаца Markdown, элемента списка или заголовка. Если необходимо, то можно использовать HTML-теги вместо разметки Markdown. Например, можно использовать HTML-теги или вместо предлагаемого синтаксиса Markdown ссылок или изображений.

В отличие от HTML-тегов блочного уровня, в тегах уровня span - синтаксис Markdown обрабатывается.

Автоматическое экранирование специальных символов.

Если надо написать о "AT&T" , то нужно писать как "AT&T" . Так же нужно избегать амперсандов в URL-адресах. Таким образом:

Заголовки

Markdown поддерживает два стиля заголовков: Setext и atx .

Заголовки в стиле Setext подчеркиваются с помощью знаков равенства (для заголовков первого уровня

). Например:

Будет работать любое количество подчеркивающих = или - .

Заголовки в стиле atx используют 1 - 6 символов хэша в начале строки, соответствующие уровням заголовка

. Например:

При желании можно “закрыть” заголовки в стиле atx . Это чисто косметическое средство - можно использовать его, если считаете, что это выглядит лучше. Закрывающие хэши даже не должны совпадать с количеством хэшей, используемых для открытия заголовка. (Количество открывающихся хэшей определяет уровень заголовка) :

Блоки с цитатами .

Markdown позволяет ставить символ > только перед первой строкой абзаца с цитатой:

Блоки с цитатами можно вкладывать друг в друга, добавив дополнительные уровни с помощью символа > :

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

Markdown поддерживает упорядоченные (нумерованные) и неупорядоченные (маркированные) списки.

Неупорядоченные списки используют символы звездочки * , плюсы + и дефисы - (взаимозаменяемо) в качестве маркеров списков:

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

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

Если список написан в разметке/документе Markdown вот так:

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

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

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

Для того, что бы оформление списка выглядели красиво, их можно обернуть висячими отступами:

Но можно этого не делать:

Если элементы списка разделены пустыми строками, то Markdown обернет элементы в теги

при выводе HTML. Например:

преобразуется в следующий HTML:

Но следующая разметка:

преобразуется в следующий HTML:

Элементы списка могут состоять из нескольких абзацев. Каждый последующий абзац в элементе списка должен иметь отступ либо в 4 пробела либо в одну табуляцию:

Будет выглядеть красиво, если сделать отступы в каждой строке последующих абзацев, но и здесь это делать не обязятельно:

Чтобы поместить блок с цитатой в элемент списка, то она (цитата) должна быть задана следующим образом: символы разделители > должны иметь отступы:

Чтобы поместить блок кода в элемент списка, он должен иметь двойной отступ - 8 пробелов или две табуляции:

Стоит отметить, что можно случайно сгенерировать на выходе упорядоченный список, написав что-то вроде этого:

Чтобы избежать такого поведения, можно использовать обратную косую черту \ - экранировать точку:

Оформление слов или фраз HTML-тегами , , .

Markdown рассматривает звездочки * и подчеркивания _ как индикаторы акцента (привлечения внимания) какого то участка текста.

текст, обернутый одним _ будет обернут HTML-тегом ,
текст, обернутый одной * будет обернут HTML-тегом ,
текст в двойных * или _ будет обернут с помощью HTML-тега .

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

Акцент может быть использован в середине слова:

Но если окружить символ * или _ пробелами, то он будет рассматриваться как буквальная звездочка или подчеркивание.

Чтобы создать буквальную звездочку или подчеркивание в том месте, где они в противном случае использовались бы в качестве разделителя акцента, то можно сделать это, экранировав данный символ обратной косой чертой \ :

Оформление блоков с кодом.

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

Markdown будет генерировать:

Один уровень отступа - 4 пробела или 1 табуляция, удаляется из каждой строки блока с кодом. Например:

Блок кода продолжается до тех пор, пока он не достигнет строки без отступа (или конца статьи).

Внутри блока с кодом амперсанды & и угловые скобки и > автоматически преобразуются в HTML-сущности. Такое поведение позволяет очень легко включить пример исходного кода HTML с помощью разметки Markdown - просто вставьте его и сделайте отступ, остальное движок Markdown сделает сам. Например:

Обратите внимание, внутри блоков с кодом, синтаксис Markdown не обрабатывается, например, звездочки - это просто буквальные звездочки.

Строка с кодом по ходу текста.

Чтобы указать строку с кодом в тексте, оберните его обратными кавычками ` . В отличие от предварительно отформатированного блока кода, строку с кодом указывает код в пределах обычного абзаца. Например:

будет генерировать следующее:

Чтобы включить символ обратной кавычки в строку с кодом, можно использовать несколько символов обратных кавычек в качестве разделителей открытия и закрытия:

будет генерировать следующее:

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

будет генерировать следующее:

При использовании строк кода амперсанды & и угловые скобки и > автоматически кодируются как HTML-сущности, что позволяет легко включать примеры HTML-тегов:

Так же можно написать следующее:

в итоге получится:

Горизонтальные линии .

Можно создать горизонтальный тег , поместив три или более дефиса - , звездочки * или подчеркивания _ в отдельную строку. При желании, можно использовать пробелы между дефисами или звездочками. Каждая из следующих строк, в последствии создаст HTML-тег :

Оформление ссылок .

Markdown поддерживает два стиля ссылок: inline и reference .

В обоих стилях текст ссылки разделен [квадратными скобками].

Чтобы создать встроенную inline ссылку, необходимо использовать набор обычных круглых скобок сразу после закрывающей квадратной скобки текста ссылки. В круглых скобках укажите URL-адрес, на который должна указывать ссылка, а также необязательный заголовок title ссылки, заключенный в кавычки. Например:

Будет генерировать следующий HTML:

Если ссылка ведет на локальный ресурс на том же сервере, то можно использовать относительные пути:

Ссылки в стиле reference используют второй набор квадратных скобок, внутри которых помещается метка по выбору пользователя для идентификации ссылки:

Можно дополнительно использовать пробел для разделения наборов скобок:

Затем, в любом месте документа, на отдельной строке определяется метка ссылки:

Алгоритм создания метки ссылки, при создании ссылок в стиле reference :

Квадратные скобки, содержащие идентификатор ссылки (необязательно отступ от левого поля с использованием до трех пробелов);
За ними следует двоеточие;
Затем следует один или несколько пробелов (или табуляций);
Далее следует URL-адрес для ссылки;
При необходимости, за URL-адресом следует атрибут заголовка ссылки, заключенный в двойные или одинарные кавычки или заключенный в круглые скобки.

Следующие три определения ссылок эквивалентны:

URL-адрес ссылки может быть дополнительно заключен в угловые скобки:

Можно поместить атрибут title в следующую строку и использовать дополнительные пробелы или табуляции для заполнения, что, как правило, выглядит лучше при более длинных URL-адресах:

Определения ссылок используются только для создания ссылок во время обработки Markdown и удаляются из вашего документа в выводе HTML.

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

А затем проставьте метку, определив связь:

Поскольку имена ссылок могут содержать пробелы, то следующий ярлык будет работать даже для нескольких слов в тексте ссылки:

А затем определите связь:

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

Вот пример ссылок в действии:

Используя неявный ярлык имени ссылки, можно было бы написать:

Оба вышеприведенных примера приведут к следующему выводу HTML:

Для сравнения, вот тот же самый абзац, написанный с использованием встроенного inline стиля ссылок Markdown:

Смысл ссылок reference стиля не в том, что их легче писать. Дело в том, что с reference ссылками ваш источник документа значительно более удобочитаем. Сравните приведенные выше примеры: при использовании ссылок reference стиля сам абзац имеет длину всего 81 символ, а при использовании ссылок inline стиля - 176 символов, а в виде необработанного HTML-кода - 234 символа.

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

Публикация изображений .

Довольно сложно разработать “естественный” синтаксис для размещения изображений в формате обычного текстового документа.

Разметка Markdown использует синтаксис публикации изображений, напоминающий синтаксис размещения ссылок, так же используя два стиля: inline и reference .

Размещение изображения в документе inline стилем выглядит следующим образом:

Алгоритм публикации изображения в документе inline стилем:

Сначала идет восклицательный знак: ! ;
Далее следует набор квадратных скобок, содержащий альтернативный текст для изображения (атрибут alt );
Далее следует набор скобок, содержащих URL-адрес или путь к изображению, и необязательный атрибут title, заключенный в двойные или одинарные кавычки.

Синтаксис изображения в reference стиле выглядит следующим образом:

Где id - это имя метки изображения, которая может определятся в любом месте документа. Другими словами, метки на изображения определяются с использованием синтаксиса идентичного ссылкам:

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

Автоматические ссылки.

Markdown поддерживает стиль быстрого создания “автоматических” ссылок для URL-адресов и адресов электронной почты. Для этого окружите URL-адрес или адрес электронной почты угловыми скобками и > . Такое поведение означает, что если в документе Markdown допустимо показать фактический URL или адрес электронной почты, а также сделать его кликабельной ссылкой, то можете сделать следующее:

Markdown преобразует это в:

Автоматические ссылки для адресов электронной почты работают аналогично, за исключением того, что Markdown также выполнит скрытие фактического адреса от спам-ботов. Например:

закодирует адрес электронной почты в нечто подобное:

который будет отображаться в браузере в виде кликабельной ссылки на “address@example.com".

Этот трюк с кодированием сущностей действительно обманет многих, если не большинство, ботов по сбору адресов E-Mail, но он определенно не обманет их всех. Это лучше, чем ничего, но адрес, опубликованный таким образом , вероятно, в конечном итоге начнет получать спам.

Экранирование специальных символов.

Markdown позволяет использовать обратные слешы \ для создания буквенных символов, которые в противном случае имели бы особое значение в синтаксисе форматирования Markdown. Например, если надо окружить слово буквальными звездочками (вместо HTML-тега ), можно использовать обратный слеш перед звездочками, например так:

Markdown предоставляет экранирование обратной косой черты для следующих символов:

Используйте Atom для записи файлов .md, базовый синтаксис Markdown

Введение атома:

Atom - это кроссплатформенный текстовый редактор, запущенный Github специально для программистов, и один из трех основных кроссплатформенных редакторов (Atom, sublime, vscode). Atom имеет встроенную поддержку уценки, которая может легко анализировать и просматривать.

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

Как включить Atom для записи .md файлов:

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

Затем откройте программное обеспечение Atom.

Откройте любой файл .md (файл формата уценки), Вы также можете создать новый файл .md и открыть его, открыв строку меню Файл-> Открыть файл.

Используйте сочетания клавиш Ctrl + Shift + P под окнами, чтобы открыть окно ввода команды；

Введите переключатель предварительного просмотра уценки, введите, чтобы установить, а затем нажмите Ctrl + Shift + M, чтобы выполнить правый и левый предварительный просмотр в реальном времени.

Мы также можем использовать строку меню Packages-> Markdown Preview-> Toggle Treview, чтобы выполнить редактирование слева и предварительный просмотр в реальном времени справа.

Плагины Atom делятся на встроенные и расширенные. Markdown Preview - встроенный плагин Atom.

Если вы хотите хорошо писать файлы Markdown, вам также необходимо установить следующие плагины:

Используйте сочетания клавиш Ctrl + Shift + P под окнами, чтобы открыть окно ввода команд, введите настройки просмотра установки пакетов и тем или вы можете использовать строку меню Файл-> Настройка-> Установить;

markdown-preview-plus：

Плагин был расширен на основе markdown-preview, поддерживает предварительный просмотр в реальном времени и поддерживает формулу Latex.

Ctrl + Shift + M, чтобы открыть уценку живой предварительный просмотр

Ctrl + Shift + X Включить поддержку формулы латекса

Синхронная прокрутка:

Активируйте плагин markdown-scroll-sync, вы увидите, что Atom поддерживает синхронную прокрутку. Синхронная прокрутка является важной функцией редактора Markdown, который удобен для быстрого поиска позиции предварительного просмотра при просмотре изменения документа. markdown-scroll-sync поддерживает не только синхронную прокрутку, но и синхронную прокрутку при изменении положения курсора. Эта функция недоступна во многих редакторах Markdown.

Текущая markdown-scroll-sync не поддерживает markdown-preview-plus, а только markdown-preview, который поставляется с Atom.

Улучшение кода:

Активируйте плагин языковой разметки. Общий редактор Markdown предоставляет базовые функции, такие как раскраска кода, а также разметка кода, а также быстрая генерация фрагментов кода и другие функции.

Картинная паста:

Перед установкой плагина для вставки картинки необходимо выполнить следующие шаги:

Снимок экрана-> Имя и сохранить файл-> Упорядочить в текущую папку-> Вставить соответствующую команду в файл .md

Мы используем плагин markdown-img-paste, сохраненный в нашем локальном каталоге .md. Изображение сохраняется в папке активов каталога, в котором находится .md.

После завершения установки для вставки снимка экрана требуется только:

Используйте любой инструмент для создания снимков экрана, чтобы сделать снимок экрана (не нужно его сохранять, просто скопируйте его в буфер обмена), а затем ctr + shift + v автоматически вставит ссылку на изображение и сгенерирует пустой заголовок для заполнения и отображения изображения в предварительном просмотре.

qiniu-uploader (устанавливается и настраивается только при загрузке изображений в облачное пространство при выборе изображений для вставки):

Если вы используете плагин markdown-assistant, вы должны сначала настроить qiniu-uploader.

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

Затем мы устанавливаем четыре параметра в qiniu-uploader:

qiniuAK：

Скопируйте и вставьте содержимое красной строки в qiniuAK.

qiniuBucket：

Нажмите на значок стиля папки, чтобы создать новое место для хранения (сначала попросит вас назвать его). Затем введите название вашего недавно созданного пространства ниже.

qiniuDomain：

Тогда мы можем сначала выбрать тестовое доменное имя. Обратите внимание, что тестовое доменное имя будет восстановлено через 30 дней.

Скопируйте и вставьте тестовое доменное имя ниже:

qiniuSK：

Скопируйте и вставьте значение SK в:

Редактирование таблицы:

Активируйте плагин markdown-table-editor.

Введите | в начале строки, а затем нажмите клавишу Tab. Если | становится розовым, таблица создается. | После этого вы можете написать содержимое этой ячейки и нажать | после завершения записи ячейки. Ячейка создана.

Экспорт в PDF:

Активируйте markdown-themeable-pdf и pdf-view.

Сначала сохраните файл Ctrl + s, а затем щелкните правой кнопкой мыши в области редактирования-> Markdown to PDF или используйте сочетания клавиш ctrl + shift + e для экспорта PDF-файла и его предварительного просмотра. Экспортированный PDF-файл находится в той же папке, что и .md по умолчанию.

Расположение сочетаний клавиш:

Ctrl + Shift + P, чтобы открыть окно ввода команды

Ctrl + Shift + M, чтобы открыть уценку живой предварительный просмотр

Ctrl + Shift + X Включить поддержку формулы латекса

Ctrl + S, чтобы сохранить файл, а затем Ctrl + Shift + E, чтобы экспортировать PDF и просмотреть его.

Основной синтаксис уценки:

НАЗВАНИЕ:

Эффект заключается в следующем:

Есть еще один способ выразить названия первого и второго уровня:

== означает, что первая строка является заголовком первого уровня, - означает, что вышеуказанная строка является заголовком второго уровня. = Или - хотя бы 2.

Эффект заключается в следующем:

Список:

Список делится на упорядоченный список и неупорядоченный список.

Неупорядоченные списки могут быть созданы с помощью *, +, - - * рекомендуется.

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

Вы можете видеть, что номер списка установлен в 2,4,7, но фактический эффект должен начинаться с 2 (номер набора первого элемента), и он будет фиксированным, а затем увеличится в последовательности.

Блок цитаты:

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

Ссылка - это блок, теоретически все должно быть размещено, например: заголовок, список, ссылка и т. Д.

Ссылки могут быть вложенными.

Разделив линия:

Разделительная линия может быть представлена как минимум 3 из 3 символов * -_ (звездочка, знак минус, нижняя строка) и не должна быть непрерывной с пробелами между ними.Рекомендуется знак минус.

Ссылка:

Markdown поддерживает 2 вида методов связывания: встроенный и параметрический. Независимо от того, какой из них, текст ссылки помечается [квадратными скобками].

Формат встроенной ссылки: текст ссылки помещается в [], а адрес ссылки помещается в следующую (). Ссылки могут также иметь атрибут заголовка с пробелом после адреса ссылки и затем заключаться в кавычки.

Метка за параметром может быть заключена в "", "или ().

Изображение:

Есть также два способа изображения: встроенный и параметрический.

Использование в основном такое же, как ссылка, с той лишь разницей, что нужно писать перед картинкой! ,

Эффект заключается в следующем:

Кодовое поле:

Существует только одна строка кода, которая может быть заключена в `` в начале и конце кода.

Для нескольких строк кода используйте `` `в строке над кодом и строку под концом кода.

Эффект заключается в следующем:

Форма:

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

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

Эффект заключается в следующем:

Жирный и наклонный:

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

Наклон: добавьте звездочку или подчеркивание до и после наклоняемого предложения.

Читайте также: