|
|
@@ -1,2 +1,381 @@
|
|
|
-# markdown-doc
|
|
|
+Настоящий документ предназначен для ознакомления пользователя с функциональными возможностями языка разметки Markdown.
|
|
|
+Markdown – это облегченный язык разметки, который является инструментом преобразования кода в HTML.
|
|
|
+Главной особенностью данного языка является максимально простой синтаксис, который служит для упрощения написания и чтения кода разметки, что, в свою очередь, позволяет легко его корректировать.
|
|
|
+Теперь рассмотрим более подробно функции языка разметки Markdown.
|
|
|
|
|
|
+Markdown не является заменой HTML. Синтаксис Markdown достаточно ограничен, и соответствует лишь небольшому подмножеству элементов HTML. Он включает в себя следующие элементы:
|
|
|
+
|
|
|
+1. Блочные элементы
|
|
|
+ + [Параграфы и разрывы строк](#Parag);
|
|
|
+ + [Заголовки](#Headers);
|
|
|
+ + [Цитаты](#Blockquotes);
|
|
|
+ + [Списки](#Lists)
|
|
|
+ + [Блоки кода](#CodeBlocks);
|
|
|
+ + [Горизонтальные (разделительные) линии](#Lines).
|
|
|
+2. Строчные элементы
|
|
|
+ + [Ссылки](#Links);
|
|
|
+ + [Выделение текста](#Emphasis);
|
|
|
+ + [Кодовые фрагменты строк](#Code);
|
|
|
+ + [Изображения](#Images).
|
|
|
+3. Дополнительные элементы
|
|
|
+ + [Обратный слеш](#Backslash Escapes);
|
|
|
+ + [Автоматические ссылки](#Automatic Links);
|
|
|
+ + [Специальные символы HTML](#SpecialSymbol).
|
|
|
+
|
|
|
+Более подробно с перечисленными функциями можно ознакомиться в разделе «Описание синтаксиса».
|
|
|
+
|
|
|
+ОПИСАНИЕ СИНТАКСИСА
|
|
|
+=========================
|
|
|
+
|
|
|
+Блочные элементы
|
|
|
+--------------------------
|
|
|
+
|
|
|
+##### <a name="Parag"></a> Параграфы и разрывы строк
|
|
|
+Для того, чтобы создать параграф с использованием синтаксиса языка Markdown, достаточно отделить строки текста одной (или более) пустой строкой (пустой считается всякая строка, которая не содержит в себе ничего, кроме пробелов и символов табуляции).
|
|
|
+Для того, чтобы вставить видимый перенос строки (элемент `<br/>`) необходимо окончить строку двумя пробелами и нажатием клавиши «Enter».
|
|
|
+Многие элементы синтаксиса Markdown выглядят и работают гораздо лучше в случае, когда их форматируют с помощью «жесткого перевода строк» (разделение строк, осуществленное самим пользователем, а не программой автоматически). К таким элементам относятся цитаты, списки и пр.
|
|
|
+
|
|
|
+##### <a name="Headers"></a> Заголовки
|
|
|
+Язык разметки Markdown поддерживает 2 стиля обозначения заголовков: подчеркивание и выделение символом («#»).
|
|
|
+Выделение заголовков с помощью подчеркивания производится знаками равенства («=») в случае, если заголовок первого уровня, и дефисами («-») в случае, если заголовок второго уровня. Количество знаков подчеркивания не ограничивается.
|
|
|
+При выделении заголовков с помощью символа («#») используется от одного до шести данных символов, которые устанавливаются в начале строки (перед заголовком). В данном случае количество символов соответствует уровню заголовка. Кроме того, заголовок возможно снабдить закрывающимися символами («#»), хотя это и не является обязательным. Количество закрывающихся символов не обязано соответствовать количеству начальных символов. Уровень заголовка определяется по количеству начальных символов.
|
|
|
+Заголовки первого и второго уровней, выполненные с помощью подчеркивания, выглядят следующим образом:
|
|
|
+
|
|
|
+ Заголовок первого уровня
|
|
|
+ ========================
|
|
|
+ Заголовок второго уровня
|
|
|
+ -------------------------
|
|
|
+
|
|
|
+Заголовки первого, третьего и шестого уровней, выполненные с помощью символа («#»), выглядят следующим образом:
|
|
|
+
|
|
|
+ # Заголовок первого уровня
|
|
|
+ ### Заголовок третьего уровня
|
|
|
+ ###### Заголовок шестого уровня
|
|
|
+Приведенные выше заголовки, выполненные с помощью символа («#») тождественны следующим:
|
|
|
+
|
|
|
+ # Заголовок первого уровня #
|
|
|
+ ### Заголовок третьего уровня ###
|
|
|
+ ###### Заголовок шестого уровня ######
|
|
|
+В результате на экран выводится следующее:
|
|
|
+
|
|
|
+Заголовок первого уровня
|
|
|
+========================
|
|
|
+
|
|
|
+Заголовок второго уровня
|
|
|
+------------------------
|
|
|
+
|
|
|
+# Заголовок первого уровня
|
|
|
+### Заголовок третьего уровня
|
|
|
+###### Заголовок шестого уровня
|
|
|
+
|
|
|
+##### <a name="Blockquotes"></a> Цитаты
|
|
|
+Для обозначения цитат в языке Markdown используется знак «больше» («>»). Его можно вставлять как перед каждой строкой цитаты, так и только перед первой строкой параграфа.
|
|
|
+Также синтаксис Markdown позволяет создавать вложенные цитаты (цитаты внутри цитат). Для их разметки используются дополнительные уровни знаков цитирования («>»).
|
|
|
+Цитаты в Markdown могут содержать всевозможные элементы разметки.
|
|
|
+Цитаты в языке Markdown выглядят следующим образом:
|
|
|
+
|
|
|
+ >Это пример цитаты,
|
|
|
+ >в которой перед каждой строкой
|
|
|
+ >ставится угловая скобка.
|
|
|
+
|
|
|
+ >Это пример цитаты,
|
|
|
+ в которой угловая скобка
|
|
|
+ ставится только перед началом нового параграфа.
|
|
|
+ >Второй параграф.
|
|
|
+
|
|
|
+Вложение цитаты в цитату выглядит следующим образом:
|
|
|
+
|
|
|
+ > Первый уровень цитирования
|
|
|
+ >> Второй уровень цитирования
|
|
|
+ >>> Третий уровень цитирования
|
|
|
+ >
|
|
|
+ >Первый уровень цитирования
|
|
|
+В результате на экран выводится следующее:
|
|
|
+
|
|
|
+>Это пример цитаты,
|
|
|
+>в которой перед каждой строкой
|
|
|
+>ставится угловая скобка.
|
|
|
+
|
|
|
+>Это пример цитаты,
|
|
|
+в которой угловая скобка
|
|
|
+ставится только перед началом нового параграфа.
|
|
|
+
|
|
|
+>Второй параграф.
|
|
|
+
|
|
|
+Вложенная цитата:
|
|
|
+
|
|
|
+> Первый уровень цитирования
|
|
|
+>> Второй уровень цитирования
|
|
|
+>>> Третий уровень цитирования
|
|
|
+>
|
|
|
+>Первый уровень цитирования
|
|
|
+
|
|
|
+
|
|
|
+Уровень цитирования не может превышать 15-й.
|
|
|
+
|
|
|
+##### <a name="Lists"></a> Списки
|
|
|
+Markdown поддерживает упорядоченные (нумерованные) и неупорядоченные (ненумерованные) списки.
|
|
|
+ Для формирования неупорядоченный списков используются такие маркеры, как звездочки, плюсы и дефисы. Все перечисленные маркеры могут использоваться взаимозаменяемо.
|
|
|
+Для формирования упорядоченных списков в качестве маркеров используются числа с точкой. Важной особенностью в данном случае является то, что сами номера, с помощью которых формируется список, не важны, так как они не оказывают влияния на выходной HTML код. Как бы ни нумеровал пользователь список, на выходе он в любом случае будет иметь упорядоченный список, начинающийся с единицы (1, 2, 3…). Эту особенность стоит учитывать в том случае, когда необходимо использовать порядковые номера элементов в списке, чтобы они соответствовали номерам, получающимся в HTML.
|
|
|
+Упорядоченные списки всегда следует начинать с единицы. Маркеры списков обычно начинаются с начала строки, однако они могут быть сдвинуты, но не более чем на 3 пробела. За маркером должен следовать пробел, либо символ табуляции.
|
|
|
+При необходимости в список можно вставить цитату. В этом случае обозначения цитирования ( «>» ) нужно писать с отступом.
|
|
|
+Упорядоченные списки выглядят следующим образом:
|
|
|
+
|
|
|
+ 1. Проводник
|
|
|
+ 2. Полупроводник
|
|
|
+ 3. Диэлектрик
|
|
|
+
|
|
|
+Неупорядоченные списки выглядят следующим образом:
|
|
|
+
|
|
|
+ * Проводник
|
|
|
+ * Полупроводник
|
|
|
+ * Диэлектрик
|
|
|
+
|
|
|
+Или
|
|
|
+
|
|
|
+ - Проводник
|
|
|
+ - Полупроводник
|
|
|
+ - Диэлектрик
|
|
|
+
|
|
|
+Или
|
|
|
+
|
|
|
+ + Проводник
|
|
|
+ + Полупроводник
|
|
|
+ + Диэлектрик
|
|
|
+На выходе всех трех перечисленных вариантов имеется один и тот же результат.
|
|
|
+В результате на экран выводится следующее:
|
|
|
+
|
|
|
+1. Проводник
|
|
|
+2. Полупроводник
|
|
|
+3. Диэлектрик
|
|
|
+
|
|
|
+и
|
|
|
+
|
|
|
++ Проводник
|
|
|
++ Полупроводник
|
|
|
++ Диэлектрик
|
|
|
+
|
|
|
+Цитата, вставленная в список, выглядит следующим образом:
|
|
|
+
|
|
|
+ 1. Элемент списка с цитатой:
|
|
|
+
|
|
|
+ > Это цитата
|
|
|
+ > внутри элемента списка.
|
|
|
+
|
|
|
+ 2. Второй элемент списка
|
|
|
+
|
|
|
+В результате на экран выводится следующее:
|
|
|
+
|
|
|
+1. Элемент списка с цитатой:
|
|
|
+
|
|
|
+ > Это цитата
|
|
|
+ > внутри элемента списка.
|
|
|
+
|
|
|
+2. Второй элемент списка
|
|
|
+
|
|
|
+
|
|
|
+При вставке цитат в элементы списка важно учитывать, что элементы списка должны находиться на одном уровне, а цитаты должны указываться с отступом. В случае, если правило с единым уровнем списка не соблюдается, следующий после цитаты элемент списка будет автоматически нумероваться цифрой «1.».
|
|
|
+Кроме того, при необходимости в список можно вставить исходный код. В этом случае его нужно писать с двойным отступом – 8 пробелов или 2 символа табуляции.
|
|
|
+
|
|
|
+ - Элемент списка, содержащий исходный код
|
|
|
+
|
|
|
+ <исходный код >
|
|
|
+
|
|
|
+##### <a name="CodeBlocks"></a> Блоки кода
|
|
|
+Отформатированные блоки кода используются в случае необходимости процитировать исходный код программ или разметки.
|
|
|
+Для создания блока кода в языке Markdown необходимо каждую строку параграфа начинать с отступа, состоящего из четырех пробелов или одного символа табуляции. Блок кода продолжается до тех пор, пока не встретится строка без отступа (или конец текста). Внутри блока кода амперсанды («&») и угловые скобки («<» и «>») автоматически преобразуются в элементы HTML разметки. Кроме того, следует отметить, что внутри блоков кода обычный синтаксис Markdown не обрабатывается.
|
|
|
+Блок кода в Markdown выглядит следующим образом:
|
|
|
+
|
|
|
+Это обычный параграф:
|
|
|
+
|
|
|
+ Это блок кода
|
|
|
+
|
|
|
+##### <a name="Lines"> </a> Горизонтальные линии (разделители)
|
|
|
+
|
|
|
+Для того чтобы создать горизонтальную линию с использованием синтаксиса языка Markdown, необходимо поместить три (или более)дефиса или звездочки на отдельной строке текста. Между ними возможно располагать пробелы.
|
|
|
+Горизонтальные линии в Markdown выглядят следующим образом:
|
|
|
+
|
|
|
+ Первая часть текста, который необходимо разделить
|
|
|
+ ***
|
|
|
+ Вторая часть текста, который необходимо разделить
|
|
|
+
|
|
|
+Или
|
|
|
+
|
|
|
+ Первая часть текста, который необходимо разделить
|
|
|
+
|
|
|
+ ---
|
|
|
+
|
|
|
+ Вторая часть текста, который необходимо разделить
|
|
|
+В результате на экран выводится следующее:
|
|
|
+
|
|
|
+Первая часть текста, который необходимо разделить
|
|
|
+***
|
|
|
+Вторая часть текста, который необходимо разделить
|
|
|
+
|
|
|
+При использовании данного инструмента важно помнить, что после первой части текста и перед второй необходимо оставлять пустую строку. Данное правило необходимо соблюдать только при использовании дефисов. Если его не соблюдать, на экран будет выведен заголовок второго уровня и строка обычного текста. При использовании символа звездочки данным правилом можно пренебречь.
|
|
|
+
|
|
|
+ Строчные элементы
|
|
|
+-------------------
|
|
|
+
|
|
|
+##### <a name="Links"></a> Ссылки
|
|
|
+Markdown поддерживает два стиля оформления ссылок:
|
|
|
+
|
|
|
+ - Гиперссылка, с немедленным указанием адреса (внутритекстовая);
|
|
|
+ - Гиперссылка, подобная сноске.
|
|
|
+
|
|
|
+Подразумевается, что помимо URL-адреса существует еще текст ссылки. Он заключается в квадратные скобки.
|
|
|
+Для создания внутритекстовой гиперссылки необходимо использовать круглые скобки сразу после закрывающей квадратной. Внутри них необходимо поместить URL-адрес. В них же возможно расположить название, заключенное в кавычки, которое будет отображаться при наведении, но этот пункт не является обязательным.
|
|
|
+
|
|
|
+ [пример](http://example.com/ "Необязательная подсказка")
|
|
|
+В результате на экран выводится следующее:
|
|
|
+[пример](http://example.com/ "Необязательная подсказка")
|
|
|
+При ссылке на локальную директорию возможно использование относительного пути (от текущей страницы, сайта и т.п.)
|
|
|
+
|
|
|
+При создании сносной гиперссылки вместо целевого адреса используется вторая пара квадратных скобок, внутри которых помещается метка, идентификатор ссылки (id).
|
|
|
+
|
|
|
+ [пример][id]:
|
|
|
+Также, можно использовать пробел, чтобы отделять 2 пары квадратных скобок:
|
|
|
+
|
|
|
+ [пример] [id]:
|
|
|
+
|
|
|
+В этом случае возможно определить идентификатор в любом месте документа:
|
|
|
+
|
|
|
+ [id]: http://example.com/ "Необязательная подсказка"
|
|
|
+
|
|
|
+В результате на экран выводится следующее:
|
|
|
+[пример] [id]
|
|
|
+[id]: http://example.com/ "Необязательная подсказка"
|
|
|
+Иными словами, она состоит из следующих элементов:
|
|
|
+
|
|
|
+ - Идентификатор ссылки, окружённый квадратными скобками (которым может предшествовать необязательный отступ от одного до трёх пробелов);
|
|
|
+ - Двоеточие;
|
|
|
+ - Один или несколько пробелов (или символов табуляции);
|
|
|
+ - URL гиперссылки;
|
|
|
+ - Необязательный заголовок (подсказка к изображению, которая всплывает при наведении на него) гиперссылки, заключённый либо в двойные или одиночные кавычки, либо в скобки.
|
|
|
+
|
|
|
+Идентификаторы ссылок могут состоять из букв, цифр, пробелов и знаков пунктуации, однако они не чувствительны к регистру. То есть эти два варианта эквивалентны:
|
|
|
+
|
|
|
+ [текст ссылки][a]
|
|
|
+ [текст ссылки][A]
|
|
|
+Markdown позволяет также использовать неявно выраженный идентификатор (сокращенный). В этом случае метка не приводится, вместо неё текст гиперссылки используется и в качестве её имени, а вторая пара квадратных скобок остаётся пустою.
|
|
|
+Например, чтобы сделать слово «Example» гиперссылкой, ведущей на сайт <http://example.com/>, достаточно написать:
|
|
|
+
|
|
|
+ [Example][]
|
|
|
+и затем определить гиперссылку:
|
|
|
+
|
|
|
+ [Example]: http://example.com/
|
|
|
+В результате на экран выводится следующее:
|
|
|
+[Example][]
|
|
|
+[Example]: http://example.com/
|
|
|
+
|
|
|
+##### <a name="Emphasis"></a> Выделение текста
|
|
|
+Markdown воспринимает звёздочки «*» и символы подчёркивания «_» как признаки смыслового выделения текста:
|
|
|
+
|
|
|
+ - Текст, окружённый одиночными «*» или «_», будет заключен в HTML-тэг `<em>`.
|
|
|
+ - Текст, окружённый двойными «*» или «_», будет заключен в HTML-тэг `<strong>`.
|
|
|
+
|
|
|
+Иными словами, текст, окруженный одинарными символами, выделяется курсивным шрифтом, а текст, окруженный двойными символами, выделяется полужирным шрифтом.
|
|
|
+Также, выделенный фрагмент может находиться в любой части слова.
|
|
|
+Текст, выделенный курсивом с использованием синтаксиса языка Markdown, выглядит следующим образом:
|
|
|
+
|
|
|
+ *Пример*
|
|
|
+*Пример*
|
|
|
+
|
|
|
+Текст, выделенный полужирным шрифтом с использованием синтаксиса языка Markdown, выглядит следующим образом:
|
|
|
+
|
|
|
+ **Пример**
|
|
|
+**Пример**
|
|
|
+
|
|
|
+Текст, выделенный курсивным полужирным шрифтом с использованием синтаксиса языка Markdown выглядит следующим образом:
|
|
|
+
|
|
|
+ ***Пример***
|
|
|
+***Пример***
|
|
|
+
|
|
|
+Все приведенные выше примеры аналогичны следующим:
|
|
|
+
|
|
|
+ _Пример_
|
|
|
+
|
|
|
+ __Пример__
|
|
|
+
|
|
|
+ Пере___распред___деление
|
|
|
+
|
|
|
+ ___Пример___
|
|
|
+
|
|
|
+##### <a name="Code"></a> Кодовые фрагменты строк
|
|
|
+Чтобы отметить фрагмент строки, содержащий код, необходимо окружить его обратными апострофами «`». При использовании кодовых фрагментов строк текст будет отображаться в виде моноширинного шрифта.
|
|
|
+В отличие от блоков кода, кодовый фрагмент позволяет поместить код внутрь обычного абзаца текста.
|
|
|
+Кодовый фрагмент строки в языке Markdown выглядит следующим образом:
|
|
|
+
|
|
|
+Используйте оператор `if`
|
|
|
+
|
|
|
+##### <a name="Images"></a> Изображения
|
|
|
+В Markdown существует 2 способа вставки изображений в документ:
|
|
|
+
|
|
|
+a. С помощью непосредственного указания URL-адреса изображения. Синтаксис данной команды выглядит следующим образом:
|
|
|
+
|
|
|
+ 
|
|
|
+или
|
|
|
+
|
|
|
+ 
|
|
|
+Иными словами, он состоит из следующих элементов:
|
|
|
+
|
|
|
+ - восклицательный знак;
|
|
|
+ - квадратные скобки, в которых указывается альтернативный изображению текст (он станет содержимым атрибута в элементе img);
|
|
|
+ - круглые скобки, содержащие URL-адрес или относительный путь изображения, а также (необязательно) всплывающую подсказку, заключённуе в двойные или одиночные кавычки.
|
|
|
+
|
|
|
+b. С помощью метки-идентификатора. Синтаксис данной команды записывается следующим образом:
|
|
|
+
|
|
|
+ ![Альтернативный текст][id]
|
|
|
+где «id» — имя определённой метки изображения. Метки изображений определяются при помощи синтаксиса, совершенно идентичного меткам гиперссылок:
|
|
|
+
|
|
|
+ [id]: путь/к/изображению "Необязательная подсказка"
|
|
|
+Важной особенностью является то, что Markdown не позволяет задать размеры изображения (ширину, высоту).
|
|
|
+
|
|
|
+ Дополнительные элементы
|
|
|
+-------------------------
|
|
|
+
|
|
|
+##### <a name="Backslash Escapes"></a> Обратный слеш
|
|
|
+Может употребляться в Markdown перед специальными символами для того, чтобы они воспринимались в их буквальном (а не служебном) значении. Полный список данных символов приводится ниже:
|
|
|
+
|
|
|
+«\» - слеш;
|
|
|
+
|
|
|
+«`» - обратный апостроф;
|
|
|
+
|
|
|
+«*» - звездочка;
|
|
|
+
|
|
|
+«_» - символ подчеркивания;
|
|
|
+
|
|
|
+«{}» - фигурные скобки;
|
|
|
+
|
|
|
+«[]» - квадратные скобки;
|
|
|
+
|
|
|
+«()» - круглые скобки;
|
|
|
+
|
|
|
+«#» - символ решетки;
|
|
|
+
|
|
|
+«+» - плюс;
|
|
|
+
|
|
|
+«-» - минус (дефис);
|
|
|
+
|
|
|
+«.» – точка;
|
|
|
+
|
|
|
+«!» - восклицательный знак.
|
|
|
+
|
|
|
+##### <a name="Automatic Links"></a> Автоматические ссылки
|
|
|
+Markdown поддерживает упрощённый порядок автоматического создания ссылок для URL-адресов и адресов электронной почты. Для этого достаточно поместить URL-адрес или почтовый адрес в угловые скобки, и Markdown сделает его гиперссылкой. В отличие от вышеописанных стилей, в данном случае сам же URL-адрес или почтовый адрес становится и текстом гиперссылки. Автоматические ссылки на адреса электронной почты работают аналогично.
|
|
|
+Автоматические ссылки в языке Markdown выглядят следующим образом
|
|
|
+
|
|
|
+ <http://example.com/>
|
|
|
+В результате на экран выводится следующее:
|
|
|
+<http://example.com/>
|
|
|
+
|
|
|
+Автоматическая ссылка на адрес электронной почты в Markdown выглядит следующим образом
|
|
|
+
|
|
|
+ <address@example.com>
|
|
|
+В результате на экран выводится следующее:
|
|
|
+<address@example.com>
|
|
|
+
|
|
|
+##### <a name="SpecialSymbol"></a> Специальные символы HTML
|
|
|
+В языке HTML существует два символа, требующих специального рассмотрения: это символы («<») и («&»). Левая угловая скобка используется как начало тэга; амперсанды применяются для обозначения специального символа HTML.
|
|
|
+Для того чтобы использовать эти символы в их буквальном смысле, необходимо заменить их элементами HTML, а именно `<` и `&` соответственно.
|
|
|
+При использовании Markdown подобных действий совершать не нужно. Он позволяет использовать эти символы в исходном виде. В случае если амперсанд используется как часть спецсимвола HTML, он останется неизменным. В противном случае Markdown преобразует его в `&`.
|