learnxinyminutes-docs/markdown.md at master

Язык разметки Markdown создан Джоном Грубером (англ. John Gruber) в 2004 году. Авторы задавались целью создать максимально удобочитаемый и удобный в публикации облегчённый язык разметки, пригодный для последующего преобразования в HTML (а также и в другие форматы).

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

HTML-элементы

Markdown является надмножеством HTML, поэтому любой HTML-файл является корректным документом Markdown.

<!-- Это позволяет использовать напрямую
любые элементы HTML-разметки, такие, например, как этот комментарий.
  Встроенные в документ HTML-элементы не затрагиваются парсером Markdown
и попадают в итоговый HTML без изменений. Однако следует понимать,
что эта же особенность не позволяет использовать разметку Markdown внутри
HTML-элементов -->

Заголовки

HTML-элементы от <h1> до <h6> размечаются очень просто: текст, который должен стать заголовком, предваряется соответствующим количеством символов "#":

# Это заголовок h1
## Это заголовок h2
### Это заголовок h3
#### Это заголовок h4
##### Это заголовок h5
###### Это заголовок h6

Markdown позволяет размечать заголовки <h1> и <h2> ещё одним способом:

Это заголовок h1
================

А это заголовок h2
------------------

Простейшая стилизация текста

Текст легко сделать полужирным и/или курсивным:

*Этот текст будет выведен курсивом.*
_Так же, как этот._

**А этот текст будет полужирным.**
__И этот тоже.__

***Полужирный курсив.***
**_И тут!_**
*__И даже здесь!__*

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

~~Зачёркнутый текст.~~

Абзацы

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

Это абзац. Я печатаю в абзаце, разве это не прикольно?

А тут уже абзац №2.
Эта строка всё ещё относится к абзацу №2!


О, а вот это уже абзац №3!

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

Эта строка завершается двумя пробелами (выделите, чтобы увидеть!).

Над этой строкой есть <br />!

Цитаты размечаются с помощью символа «>»:

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

> А ещё цитаты могут быть многоуровневыми:
>> как здесь
>>> и здесь :)
> Неплохо?

Списки

Маркированные списки размечаются вставкой в начало каждого элемента одного из символов «*», «+» или «-»: (символ должен быть одним и тем же для всех элементов)

* Список,
* Размеченный
* Звёздочками

либо

+ Список,
+ Размеченный
+ Плюсами

либо

- Список,
- Размеченный
- Дефисами

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

1. Первый элемент
2. Второй элемент
3. Третий элемент

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

1. Первый элемент
1. Второй элемент
1. Третий элемент

(Этот список будет отображён так же, как и предыдущий!)

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

1. Введение
2. Начало работы
3. Примеры использования
    * Простые
    * Сложные
4. Заключение

Можно даже делать списки задач. Блок ниже создаёт HTML-флажки.

Для отметки флажка используйте «x»
- [ ] Первая задача
- [ ] Вторая задача
Этот флажок ниже будет отмечен
- [x] Задача была завершена

Блоки кода

Фрагменты исходного кода (обычно отмечаемые тегом <code>) выделяются просто: каждая строка блока должна иметь отступ в четыре пробела либо в один символ табуляции.

    Это код,
    причём многострочный

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

    my_array.each do |item|
      puts item
    end

Иногда бывает нужно вставить фрагмент кода прямо в строку текста, не выделяя код в блок. Для этого фрагменты кода нужно обрамлять символами «`»:

Ваня даже не знал, что делает функция `go_to()`!

В GitHub Flavored Markdown для блоков кода можно использовать специальный синтаксис:

```ruby
def foobar
  puts "Привет, мир!"
end
```

Во фрагменте, приведённом выше, отступ не требуется. Кроме того, GitHub подсветит синтаксис языка, указанного после ```

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

Разделители (<hr>) добавляются вставкой строки из трёх и более (одинаковых) символов «*» или «-», с пробелами или без них:

***
---
- - -
****************

Ссылки

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

[Ссылка!](http://test.com/)

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

[Ссылка!](http://test.com/ "Ссылка на Test.com")

Относительные пути тоже возможны:

[Перейти к музыке](/music/).

Markdown также позволяет размечать ссылку в виде сноски:

[Щёлкните эту ссылку][link1] для подробной информации!
[Также посмотрите эту ссылку,][foobar] если хотите.

[link1]: http://test.com/ "Круто!"
[foobar]: http://foobar.biz/ "Нормально!"

Title также может быть в одинарных кавычках или круглых скобках, а также отсутствовать вовсе. Ссылки на сноски могут быть в любом месте документа, а идентификаторы могут быть какими угодно, лишь бы они были уникальными.

Существует также неявное именование, когда ссылка является идентификатором.

[Это][] ссылка.

[это]: http://thisisalink.com/

Правда, эта возможность не очень распространена.

Изображения

Разметка изображений очень похожа на разметку ссылок. Нужно всего лишь добавить перед ссылкой восклицательный знак!

![Альтернативный текст для изображения](http://imgur.com/myimage.jpg "Подсказка")

Изображения тоже могут быть оформлены как сноски.

![Это альтернативный текст.][myimage]

[myimage]: relative/urls/cool/image.jpg "Если нужна подсказка, её можно добавить"

Разное

Автоссылки

Ссылка вида <http://testwebsite.com/> эквивалентна
[http://testwebsite.com/](http://testwebsite.com/)

Автоссылки для адресов электронной почты

<foo@bar.com>

Экранирование символов

Я хочу напечатать *текст, заключённый в звёздочки*, но я не хочу,
чтобы он был курсивным. Тогда я делаю так:
\*Текст, заключённый в звёздочки\*

Клавиши на клавиатуре

В GitHub Flavored Markdown для представления клавиш на клавиатуре вы можете использовать тег <kbd>.

Ваш компьютер завис? Попробуйте нажать
<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd>

Таблицы

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

| Столбец 1    | Столбец 2    | Столбец 3    |
| :----------- | :----------: | -----------: |
| Выравнивание | Выравнивание | Выравнивание |
| влево        | по центру    | вправо       |

Или более компактно

Столбец 1|Столбец 2|Столбец 3
:--|:-:|--:
Выглядит|это|страшновато...

Ну вот и всё!

За более подробной информацией обращайтесь к статье Джона Грубера о синтаксисе Markdown.

Также часто бывает полезной отличная "шпаргалка" по Markdown от Адама Притчарда.

13 KiB Raw Permalink Blame History Unescape Escape