└── README.md /README.md: -------------------------------------------------------------------------------- 1 | Настоящий документ предназначен для ознакомления пользователя с функциональными возможностями языка разметки Markdown. 2 | Markdown – это облегченный язык разметки, который является инструментом преобразования кода в HTML. 3 | Главной особенностью данного языка является максимально простой синтаксис, который служит для упрощения написания и чтения кода разметки, что, в свою очередь, позволяет легко его корректировать. 4 | Теперь рассмотрим более подробно функции языка разметки Markdown. 5 | 6 | Markdown не является заменой HTML. Синтаксис Markdown достаточно ограничен, и соответствует лишь небольшому подмножеству элементов HTML. Он включает в себя следующие элементы: 7 | 8 | 1. Блочные элементы 9 | + [Параграфы и разрывы строк](#Parag); 10 | + [Заголовки](#Headers); 11 | + [Цитаты](#Blockquotes); 12 | + [Списки](#Lists) 13 | + [Блоки кода](#CodeBlocks); 14 | + [Горизонтальные (разделительные) линии](#Lines). 15 | 2. Строчные элементы 16 | + [Ссылки](#Links); 17 | + [Выделение текста](#Emphasis); 18 | + [Кодовые фрагменты строк](#Code); 19 | + [Изображения](#Images). 20 | 3. Дополнительные элементы 21 | + [Обратный слеш](#Backslash Escapes); 22 | + [Автоматические ссылки](#Automatic Links); 23 | + [Специальные символы HTML](#SpecialSymbol). 24 | 25 | Более подробно с перечисленными функциями можно ознакомиться в разделе «Описание синтаксиса». 26 | 27 | ОПИСАНИЕ СИНТАКСИСА 28 | ========================= 29 | 30 | Блочные элементы 31 | -------------------------- 32 | 33 | ##### Параграфы и разрывы строк 34 | Для того, чтобы создать параграф с использованием синтаксиса языка Markdown, достаточно отделить строки текста одной (или более) пустой строкой (пустой считается всякая строка, которая не содержит в себе ничего, кроме пробелов и символов табуляции). 35 | Для того, чтобы вставить видимый перенос строки (элемент `
`) необходимо окончить строку двумя пробелами и нажатием клавиши «Enter». 36 | Многие элементы синтаксиса Markdown выглядят и работают гораздо лучше в случае, когда их форматируют с помощью «жесткого перевода строк» (разделение строк, осуществленное самим пользователем, а не программой автоматически). К таким элементам относятся цитаты, списки и пр. 37 | 38 | ##### Заголовки 39 | Язык разметки Markdown поддерживает 2 стиля обозначения заголовков: подчеркивание и выделение символом («#»). 40 | Выделение заголовков с помощью подчеркивания производится знаками равенства («=») в случае, если заголовок первого уровня, и дефисами («-») в случае, если заголовок второго уровня. Количество знаков подчеркивания не ограничивается. 41 | При выделении заголовков с помощью символа («#») используется от одного до шести данных символов, которые устанавливаются в начале строки (перед заголовком). В данном случае количество символов соответствует уровню заголовка. Кроме того, заголовок возможно снабдить закрывающимися символами («#»), хотя это и не является обязательным. Количество закрывающихся символов не обязано соответствовать количеству начальных символов. Уровень заголовка определяется по количеству начальных символов. 42 | Заголовки первого и второго уровней, выполненные с помощью подчеркивания, выглядят следующим образом: 43 | 44 | Заголовок первого уровня 45 | ======================== 46 | Заголовок второго уровня 47 | ------------------------- 48 | 49 | Заголовки первого, третьего и шестого уровней, выполненные с помощью символа («#»), выглядят следующим образом: 50 | 51 | # Заголовок первого уровня 52 | ### Заголовок третьего уровня 53 | ###### Заголовок шестого уровня 54 | Приведенные выше заголовки, выполненные с помощью символа («#») тождественны следующим: 55 | 56 | # Заголовок первого уровня # 57 | ### Заголовок третьего уровня ### 58 | ###### Заголовок шестого уровня ###### 59 | В результате на экран выводится следующее: 60 | 61 | Заголовок первого уровня 62 | ======================== 63 | 64 | Заголовок второго уровня 65 | ------------------------ 66 | 67 | # Заголовок первого уровня 68 | ### Заголовок третьего уровня 69 | ###### Заголовок шестого уровня 70 | 71 | ##### Цитаты 72 | Для обозначения цитат в языке Markdown используется знак «больше» («>»). Его можно вставлять как перед каждой строкой цитаты, так и только перед первой строкой параграфа. 73 | Также синтаксис Markdown позволяет создавать вложенные цитаты (цитаты внутри цитат). Для их разметки используются дополнительные уровни знаков цитирования («>»). 74 | Цитаты в Markdown могут содержать всевозможные элементы разметки. 75 | Цитаты в языке Markdown выглядят следующим образом: 76 | 77 | >Это пример цитаты, 78 | >в которой перед каждой строкой 79 | >ставится угловая скобка. 80 | 81 | >Это пример цитаты, 82 | в которой угловая скобка 83 | ставится только перед началом нового параграфа. 84 | >Второй параграф. 85 | 86 | Вложение цитаты в цитату выглядит следующим образом: 87 | 88 | > Первый уровень цитирования 89 | >> Второй уровень цитирования 90 | >>> Третий уровень цитирования 91 | > 92 | >Первый уровень цитирования 93 | В результате на экран выводится следующее: 94 | 95 | >Это пример цитаты, 96 | >в которой перед каждой строкой 97 | >ставится угловая скобка. 98 | 99 | >Это пример цитаты, 100 | в которой угловая скобка 101 | ставится только перед началом нового параграфа. 102 | 103 | >Второй параграф. 104 | 105 | Вложенная цитата: 106 | 107 | > Первый уровень цитирования 108 | >> Второй уровень цитирования 109 | >>> Третий уровень цитирования 110 | > 111 | >Первый уровень цитирования 112 | 113 | 114 | Уровень цитирования не может превышать 15-й. 115 | 116 | ##### Списки 117 | Markdown поддерживает упорядоченные (нумерованные) и неупорядоченные (ненумерованные) списки. 118 | Для формирования неупорядоченный списков используются такие маркеры, как звездочки, плюсы и дефисы. Все перечисленные маркеры могут использоваться взаимозаменяемо. 119 | Для формирования упорядоченных списков в качестве маркеров используются числа с точкой. Важной особенностью в данном случае является то, что сами номера, с помощью которых формируется список, не важны, так как они не оказывают влияния на выходной HTML код. Как бы ни нумеровал пользователь список, на выходе он в любом случае будет иметь упорядоченный список, начинающийся с единицы (1, 2, 3…). Эту особенность стоит учитывать в том случае, когда необходимо использовать порядковые номера элементов в списке, чтобы они соответствовали номерам, получающимся в HTML. 120 | Упорядоченные списки всегда следует начинать с единицы. Маркеры списков обычно начинаются с начала строки, однако они могут быть сдвинуты, но не более чем на 3 пробела. За маркером должен следовать пробел, либо символ табуляции. 121 | При необходимости в список можно вставить цитату. В этом случае обозначения цитирования ( «>» ) нужно писать с отступом. 122 | Упорядоченные списки выглядят следующим образом: 123 | 124 | 1. Проводник 125 | 2. Полупроводник 126 | 3. Диэлектрик 127 | 128 | Неупорядоченные списки выглядят следующим образом: 129 | 130 | * Проводник 131 | * Полупроводник 132 | * Диэлектрик 133 | 134 | Или 135 | 136 | - Проводник 137 | - Полупроводник 138 | - Диэлектрик 139 | 140 | Или 141 | 142 | + Проводник 143 | + Полупроводник 144 | + Диэлектрик 145 | На выходе всех трех перечисленных вариантов имеется один и тот же результат. 146 | В результате на экран выводится следующее: 147 | 148 | 1. Проводник 149 | 2. Полупроводник 150 | 3. Диэлектрик 151 | 152 | и 153 | 154 | + Проводник 155 | + Полупроводник 156 | + Диэлектрик 157 | 158 | Цитата, вставленная в список, выглядит следующим образом: 159 | 160 | 1. Элемент списка с цитатой: 161 | 162 | > Это цитата 163 | > внутри элемента списка. 164 | 165 | 2. Второй элемент списка 166 | 167 | В результате на экран выводится следующее: 168 | 169 | 1. Элемент списка с цитатой: 170 | 171 | > Это цитата 172 | > внутри элемента списка. 173 | 174 | 2. Второй элемент списка 175 | 176 | 177 | При вставке цитат в элементы списка важно учитывать, что элементы списка должны находиться на одном уровне, а цитаты должны указываться с отступом. В случае, если правило с единым уровнем списка не соблюдается, следующий после цитаты элемент списка будет автоматически нумероваться цифрой «1.». 178 | Кроме того, при необходимости в список можно вставить исходный код. В этом случае его нужно писать с двойным отступом – 8 пробелов или 2 символа табуляции. 179 | 180 | - Элемент списка, содержащий исходный код 181 | 182 | <исходный код > 183 | 184 | Помимо вышеперечисленного Markdown позволяет создавать вложенные списки (список внутри списка), то есть внутрь нумерованного списка можно вставить ненумерованный, сделав отступ перед маркером списка в один пробел. Для того, чтобы нумерованный список продолжался, а не начинался с единицы, после того, как закончился ненумерованный, необходимо срзау использовать конструкцию "цифра\.", не добавляя пустых строк. Пример данной конструкции представлен ниже. 185 | 186 | 1. Проводник 187 | 2. Полупроводник 188 | * Простые 189 | * Сложные 190 | 3. Диэлектрик 191 | 192 | В результате на экран выводится следующее: 193 | 194 | 1. Проводник 195 | 2. Полупроводник 196 | * Простые 197 | * Сложные 198 | 3. Диэлектрик 199 | 200 | ##### Блоки кода 201 | Отформатированные блоки кода используются в случае необходимости процитировать исходный код программ или разметки. 202 | Для создания блока кода в языке Markdown необходимо каждую строку параграфа начинать с отступа, состоящего из четырех пробелов или одного символа табуляции. Блок кода продолжается до тех пор, пока не встретится строка без отступа (или конец текста). Внутри блока кода амперсанды («&») и угловые скобки («<» и «>») автоматически преобразуются в элементы HTML разметки. Кроме того, следует отметить, что внутри блоков кода обычный синтаксис Markdown не обрабатывается. 203 | Блок кода в Markdown выглядит следующим образом: 204 | 205 | Это обычный параграф: 206 | 207 | Это блок кода 208 | 209 | ##### Горизонтальные линии (разделители) 210 | 211 | Для того чтобы создать горизонтальную линию с использованием синтаксиса языка Markdown, необходимо поместить три (или более)дефиса или звездочки на отдельной строке текста. Между ними возможно располагать пробелы. 212 | Горизонтальные линии в Markdown выглядят следующим образом: 213 | 214 | Первая часть текста, который необходимо разделить 215 | *** 216 | Вторая часть текста, который необходимо разделить 217 | 218 | Или 219 | 220 | Первая часть текста, который необходимо разделить 221 | 222 | --- 223 | 224 | Вторая часть текста, который необходимо разделить 225 | В результате на экран выводится следующее: 226 | 227 | Первая часть текста, который необходимо разделить 228 | *** 229 | Вторая часть текста, который необходимо разделить 230 | 231 | При использовании данного инструмента важно помнить, что после первой части текста и перед второй необходимо оставлять пустую строку. Данное правило необходимо соблюдать только при использовании дефисов. Если его не соблюдать, на экран будет выведен заголовок второго уровня и строка обычного текста. При использовании символа звездочки данным правилом можно пренебречь. 232 | 233 | Строчные элементы 234 | ------------------- 235 | 236 | ##### Ссылки 237 | Markdown поддерживает два стиля оформления ссылок: 238 | 239 | - Гиперссылка, с немедленным указанием адреса (внутритекстовая); 240 | - Гиперссылка, подобная сноске. 241 | 242 | Подразумевается, что помимо URL-адреса существует еще текст ссылки. Он заключается в квадратные скобки. 243 | Для создания внутритекстовой гиперссылки необходимо использовать круглые скобки сразу после закрывающей квадратной. Внутри них необходимо поместить URL-адрес. В них же возможно расположить название, заключенное в кавычки, которое будет отображаться при наведении, но этот пункт не является обязательным. 244 | 245 | [пример](http://example.com/ "Необязательная подсказка") 246 | В результате на экран выводится следующее: 247 | [пример](http://example.com/ "Необязательная подсказка") 248 | При ссылке на локальную директорию возможно использование относительного пути (от текущей страницы, сайта и т.п.) 249 | 250 | При создании сносной гиперссылки вместо целевого адреса используется вторая пара квадратных скобок, внутри которых помещается метка, идентификатор ссылки (id). 251 | 252 | [пример][id]: 253 | Также, можно использовать пробел, чтобы отделять 2 пары квадратных скобок: 254 | 255 | [пример] [id]: 256 | 257 | В этом случае возможно определить идентификатор в любом месте документа: 258 | 259 | [id]: http://example.com/ "Необязательная подсказка" 260 | 261 | В результате на экран выводится следующее: 262 | [пример] [id] 263 | [id]: http://example.com/ "Необязательная подсказка" 264 | Иными словами, она состоит из следующих элементов: 265 | 266 | - Идентификатор ссылки, окружённый квадратными скобками (которым может предшествовать необязательный отступ от одного до трёх пробелов); 267 | - Двоеточие; 268 | - Один или несколько пробелов (или символов табуляции); 269 | - URL гиперссылки; 270 | - Необязательный заголовок (подсказка к изображению, которая всплывает при наведении на него) гиперссылки, заключённый либо в двойные или одиночные кавычки, либо в скобки. 271 | 272 | Идентификаторы ссылок могут состоять из букв, цифр, пробелов и знаков пунктуации, однако они не чувствительны к регистру. То есть эти два варианта эквивалентны: 273 | 274 | [текст ссылки][a] 275 | [текст ссылки][A] 276 | Markdown позволяет также использовать неявно выраженный идентификатор (сокращенный). В этом случае метка не приводится, вместо неё текст гиперссылки используется и в качестве её имени, а вторая пара квадратных скобок остаётся пустою. 277 | Например, чтобы сделать слово «Example» гиперссылкой, ведущей на сайт , достаточно написать: 278 | 279 | [Example][] 280 | и затем определить гиперссылку: 281 | 282 | [Example]: http://example.com/ 283 | В результате на экран выводится следующее: 284 | [Example][] 285 | [Example]: http://example.com/ 286 | 287 | ##### Выделение текста 288 | Markdown воспринимает звёздочки «*» и символы подчёркивания «_» как признаки смыслового выделения текста: 289 | 290 | - Текст, окружённый одиночными «*» или «_», будет заключен в HTML-тэг ``. 291 | - Текст, окружённый двойными «*» или «_», будет заключен в HTML-тэг ``. 292 | 293 | Иными словами, текст, окруженный одинарными символами, выделяется курсивным шрифтом, а текст, окруженный двойными символами, выделяется полужирным шрифтом. 294 | Также, выделенный фрагмент может находиться в любой части слова. 295 | Текст, выделенный курсивом с использованием синтаксиса языка Markdown, выглядит следующим образом: 296 | 297 | *Пример* 298 | *Пример* 299 | 300 | Текст, выделенный полужирным шрифтом с использованием синтаксиса языка Markdown, выглядит следующим образом: 301 | 302 | **Пример** 303 | **Пример** 304 | 305 | Текст, выделенный курсивным полужирным шрифтом с использованием синтаксиса языка Markdown выглядит следующим образом: 306 | 307 | ***Пример*** 308 | ***Пример*** 309 | 310 | Все приведенные выше примеры аналогичны следующим: 311 | 312 | _Пример_ 313 | 314 | __Пример__ 315 | 316 | Пере___распред___деление 317 | 318 | ___Пример___ 319 | 320 | ##### Кодовые фрагменты строк 321 | Чтобы отметить фрагмент строки, содержащий код, необходимо окружить его обратными апострофами «`». При использовании кодовых фрагментов строк текст будет отображаться в виде моноширинного шрифта. 322 | В отличие от блоков кода, кодовый фрагмент позволяет поместить код внутрь обычного абзаца текста. 323 | Кодовый фрагмент строки в языке Markdown выглядит следующим образом: 324 | 325 | Используйте оператор `if` 326 | 327 | ##### Изображения 328 | В Markdown существует 2 способа вставки изображений в документ: 329 | 330 | a. С помощью непосредственного указания URL-адреса изображения. Синтаксис данной команды выглядит следующим образом: 331 | 332 | ![Альтернативный текст](/путь/к/изображению.jpg) 333 | или 334 | 335 | ![Альтернативный текст](/путь/к/изображению.jpg "Подсказка") 336 | Иными словами, он состоит из следующих элементов: 337 | 338 | - восклицательный знак; 339 | - квадратные скобки, в которых указывается альтернативный изображению текст (он станет содержимым атрибута в элементе img); 340 | - круглые скобки, содержащие URL-адрес или относительный путь изображения, а также (необязательно) всплывающую подсказку, заключённуе в двойные или одиночные кавычки. 341 | 342 | b. С помощью метки-идентификатора. Синтаксис данной команды записывается следующим образом: 343 | 344 | ![Альтернативный текст][id] 345 | где «id» — имя определённой метки изображения. Метки изображений определяются при помощи синтаксиса, совершенно идентичного меткам гиперссылок: 346 | 347 | [id]: путь/к/изображению "Необязательная подсказка" 348 | Важной особенностью является то, что Markdown не позволяет задать размеры изображения (ширину, высоту). 349 | 350 | Дополнительные элементы 351 | ------------------------- 352 | 353 | ##### Обратный слеш 354 | Может употребляться в Markdown перед специальными символами для того, чтобы они воспринимались в их буквальном (а не служебном) значении. Полный список данных символов приводится ниже: 355 | 356 | «\» - слеш; 357 | 358 | «`» - обратный апостроф; 359 | 360 | «*» - звездочка; 361 | 362 | «_» - символ подчеркивания; 363 | 364 | «{}» - фигурные скобки; 365 | 366 | «[]» - квадратные скобки; 367 | 368 | «()» - круглые скобки; 369 | 370 | «#» - символ решетки; 371 | 372 | «+» - плюс; 373 | 374 | «-» - минус (дефис); 375 | 376 | «.» – точка; 377 | 378 | «!» - восклицательный знак. 379 | 380 | ##### Автоматические ссылки 381 | Markdown поддерживает упрощённый порядок автоматического создания ссылок для URL-адресов и адресов электронной почты. Для этого достаточно поместить URL-адрес или почтовый адрес в угловые скобки, и Markdown сделает его гиперссылкой. В отличие от вышеописанных стилей, в данном случае сам же URL-адрес или почтовый адрес становится и текстом гиперссылки. Автоматические ссылки на адреса электронной почты работают аналогично. 382 | Автоматические ссылки в языке Markdown выглядят следующим образом 383 | 384 | 385 | В результате на экран выводится следующее: 386 | 387 | 388 | Автоматическая ссылка на адрес электронной почты в Markdown выглядит следующим образом 389 | 390 | 391 | В результате на экран выводится следующее: 392 | 393 | 394 | ##### Специальные символы HTML 395 | В языке HTML существует два символа, требующих специального рассмотрения: это символы («<») и («&»). Левая угловая скобка используется как начало тэга; амперсанды применяются для обозначения специального символа HTML. 396 | Для того чтобы использовать эти символы в их буквальном смысле, необходимо заменить их элементами HTML, а именно `<` и `&` соответственно. 397 | При использовании Markdown подобных действий совершать не нужно. Он позволяет использовать эти символы в исходном виде. В случае если амперсанд используется как часть спецсимвола HTML, он останется неизменным. В противном случае Markdown преобразует его в `&`. 398 | --------------------------------------------------------------------------------