mirror of
https://github.com/adambard/learnxinyminutes-docs.git
synced 2024-11-25 20:14:30 +03:00
366 lines
13 KiB
Markdown
366 lines
13 KiB
Markdown
---
|
||
language: markdown
|
||
contributors:
|
||
- ["Dan Turkel", "http://danturkel.com/"]
|
||
- ["Jacob Ward", "http://github.com/JacobCWard/"]
|
||
translators:
|
||
- ["Pirogov Alexey", "http://twitter.com/alex_pir"]
|
||
- ["Andre Polykanine", "https://github.com/Oire"]
|
||
filename: markdown-ru.md
|
||
lang: ru-ru
|
||
---
|
||
|
||
Язык разметки Markdown создан Джоном Грубером (англ. John Gruber)
|
||
в 2004 году.
|
||
Авторы задавались целью создать максимально удобочитаемый
|
||
и удобный в публикации облегчённый язык разметки,
|
||
пригодный для последующего преобразования в HTML
|
||
(а также и в другие форматы).
|
||
|
||
Также реализации Markdown варьируют в зависимости от парсера.
|
||
В этом руководстве будет указано, какие функции универсальны для языка,
|
||
а какие зависят от конкретного парсера.
|
||
|
||
- [HTML-элементы](#html-elements)
|
||
- [Заголовки](#headings)
|
||
- [Простейшая стилизация текста](#simple-text-styles)
|
||
- [Абзацы](#paragraphs)
|
||
- [Списки](#lists)
|
||
- [Блоки кода](#code-blocks)
|
||
- [Горизонтальный разделитель](#horizontal-rule)
|
||
- [Ссылки](#links)
|
||
- [Изображения](#images)
|
||
- [Разное](#miscellany)
|
||
|
||
## HTML-элементы
|
||
Markdown является надмножеством HTML, поэтому любой HTML-файл является
|
||
корректным документом Markdown.
|
||
|
||
```md
|
||
<!-- Это позволяет использовать напрямую
|
||
любые элементы HTML-разметки, такие, например, как этот комментарий.
|
||
Встроенные в документ HTML-элементы не затрагиваются парсером Markdown
|
||
и попадают в итоговый HTML без изменений. Однако следует понимать,
|
||
что эта же особенность не позволяет использовать разметку Markdown внутри
|
||
HTML-элементов -->
|
||
```
|
||
|
||
## Заголовки
|
||
|
||
HTML-элементы от <h1> до <h6> размечаются очень просто:
|
||
текст, который должен стать заголовком, предваряется
|
||
соответствующим количеством символов "#":
|
||
|
||
```md
|
||
# Это заголовок h1
|
||
## Это заголовок h2
|
||
### Это заголовок h3
|
||
#### Это заголовок h4
|
||
##### Это заголовок h5
|
||
###### Это заголовок h6
|
||
```
|
||
Markdown позволяет размечать заголовки <h1> и <h2> ещё одним способом:
|
||
|
||
```md
|
||
Это заголовок h1
|
||
================
|
||
|
||
А это заголовок h2
|
||
------------------
|
||
```
|
||
|
||
## Простейшая стилизация текста
|
||
|
||
Текст легко сделать полужирным и/или курсивным:
|
||
|
||
```md
|
||
*Этот текст будет выведен курсивом.*
|
||
_Так же, как этот._
|
||
|
||
**А этот текст будет полужирным.**
|
||
__И этот тоже.__
|
||
|
||
***Полужирный курсив.***
|
||
**_И тут!_**
|
||
*__И даже здесь!__*
|
||
```
|
||
|
||
В GitHub Flavored Markdown, стандарте, который используется в GitHub,
|
||
текст также можно сделать зачёркнутым:
|
||
|
||
```md
|
||
~~Зачёркнутый текст.~~
|
||
```
|
||
|
||
## Абзацы
|
||
|
||
Абзацами являются любые строки, следующие друг за другом.
|
||
Разделяются же абзацы одной или несколькими пустыми строками:
|
||
|
||
```md
|
||
Это абзац. Я печатаю в абзаце, разве это не прикольно?
|
||
|
||
А тут уже абзац №2.
|
||
Эта строка всё ещё относится к абзацу №2!
|
||
|
||
|
||
О, а вот это уже абзац №3!
|
||
```
|
||
|
||
Для вставки принудительных переносов можно завершить абзац двумя дополнительными пробелами:
|
||
|
||
```md
|
||
Эта строка завершается двумя пробелами (выделите, чтобы увидеть!).
|
||
|
||
Над этой строкой есть <br />!
|
||
```
|
||
|
||
Цитаты размечаются с помощью символа «>»:
|
||
|
||
```md
|
||
> Это цитата. В цитатах можно
|
||
> принудительно переносить строки, вставляя «>» в начало каждой следующей строки. А можно просто оставлять их достаточно длинными, и такие длинные строки будут перенесены автоматически.
|
||
> Разницы между этими двумя подходами к переносу строк нет, коль скоро
|
||
> каждая строка начинается с символа «>»
|
||
|
||
> А ещё цитаты могут быть многоуровневыми:
|
||
>> как здесь
|
||
>>> и здесь :)
|
||
> Неплохо?
|
||
```
|
||
|
||
## Списки
|
||
Маркированные списки размечаются вставкой в начало каждого элемента
|
||
одного из символов «*», «+» или «-»:
|
||
(символ должен быть одним и тем же для всех элементов)
|
||
|
||
```md
|
||
* Список,
|
||
* Размеченный
|
||
* Звёздочками
|
||
|
||
либо
|
||
|
||
+ Список,
|
||
+ Размеченный
|
||
+ Плюсами
|
||
|
||
либо
|
||
|
||
- Список,
|
||
- Размеченный
|
||
- Дефисами
|
||
```
|
||
|
||
В нумерованных списках каждая строка начинается
|
||
с числа и точки вслед за ним:
|
||
|
||
```md
|
||
1. Первый элемент
|
||
2. Второй элемент
|
||
3. Третий элемент
|
||
```
|
||
|
||
Заметьте, нумеровать элементы корректно необязательно. Достаточно указать
|
||
любое число в начале каждого элемента, и парсер пронумерует элементы сам!
|
||
Правда, злоупотреблять этим не стоит :)
|
||
|
||
```md
|
||
1. Первый элемент
|
||
1. Второй элемент
|
||
1. Третий элемент
|
||
```
|
||
(Этот список будет отображён так же, как и предыдущий!)
|
||
|
||
Списки могут быть вложенными:
|
||
|
||
```md
|
||
1. Введение
|
||
2. Начало работы
|
||
3. Примеры использования
|
||
* Простые
|
||
* Сложные
|
||
4. Заключение
|
||
```
|
||
|
||
Можно даже делать списки задач. Блок ниже создаёт HTML-флажки.
|
||
|
||
```md
|
||
Для отметки флажка используйте «x»
|
||
- [ ] Первая задача
|
||
- [ ] Вторая задача
|
||
Этот флажок ниже будет отмечен
|
||
- [x] Задача была завершена
|
||
```
|
||
|
||
## Блоки кода
|
||
|
||
Фрагменты исходного кода (обычно отмечаемые тегом `<code>`) выделяются просто:
|
||
каждая строка блока должна иметь отступ в четыре пробела либо в один символ табуляции.
|
||
|
||
```md
|
||
Это код,
|
||
причём многострочный
|
||
```
|
||
|
||
Вы также можете делать дополнительные отступы, добавляя символы табуляции
|
||
или по четыре пробела:
|
||
|
||
```md
|
||
my_array.each do |item|
|
||
puts item
|
||
end
|
||
```
|
||
|
||
Иногда бывает нужно вставить фрагмент кода прямо в строку текста,
|
||
не выделяя код в блок. Для этого фрагменты кода нужно обрамлять
|
||
символами «`»:
|
||
|
||
```md
|
||
Ваня даже не знал, что делает функция `go_to()`!
|
||
```
|
||
|
||
В GitHub Flavored Markdown для блоков кода можно использовать
|
||
специальный синтаксис:
|
||
|
||
```ruby
|
||
def foobar
|
||
puts "Привет, мир!"
|
||
end
|
||
```
|
||
|
||
Во фрагменте, приведённом выше, отступ не требуется.
|
||
Кроме того, GitHub подсветит синтаксис языка, указанного после \`\`\`
|
||
|
||
## Горизонтальный разделитель
|
||
|
||
Разделители (`<hr>`) добавляются вставкой строки из трёх и более
|
||
(одинаковых) символов «*» или «-», с пробелами или без них:
|
||
|
||
```md
|
||
***
|
||
---
|
||
- - -
|
||
****************
|
||
```
|
||
|
||
## Ссылки
|
||
|
||
Одной из сильных сторон Markdown можно смело считать то,
|
||
как просто размечаются гиперссылки. Для создания ссылки укажите
|
||
текст ссылки, заключив его в квадратные скобки,
|
||
и сразу после — URL-адрес, заключенный в круглые
|
||
|
||
```md
|
||
[Ссылка!](http://test.com/)
|
||
```
|
||
|
||
Также для ссылки можно указать всплывающую подсказку (`title`), используя
|
||
кавычки внутри круглых скобок:
|
||
|
||
```md
|
||
[Ссылка!](http://test.com/ "Ссылка на Test.com")
|
||
```
|
||
Относительные пути тоже возможны:
|
||
|
||
```md
|
||
[Перейти к музыке](/music/).
|
||
```
|
||
|
||
Markdown также позволяет размечать ссылку в виде сноски:
|
||
|
||
```md
|
||
[Щёлкните эту ссылку][link1] для подробной информации!
|
||
[Также посмотрите эту ссылку,][foobar] если хотите.
|
||
|
||
[link1]: http://test.com/ "Круто!"
|
||
[foobar]: http://foobar.biz/ "Нормально!"
|
||
```
|
||
|
||
`Title` также может быть в одинарных кавычках или круглых скобках, а также
|
||
отсутствовать вовсе. Ссылки на сноски могут быть в любом месте документа,
|
||
а идентификаторы могут быть какими угодно, лишь бы они были уникальными.
|
||
|
||
Существует также неявное именование, когда ссылка является идентификатором.
|
||
|
||
```md
|
||
[Это][] ссылка.
|
||
|
||
[это]: http://thisisalink.com/
|
||
```
|
||
|
||
Правда, эта возможность не очень распространена.
|
||
|
||
## Изображения
|
||
Разметка изображений очень похожа на разметку ссылок.
|
||
Нужно всего лишь добавить перед ссылкой восклицательный знак!
|
||
|
||
```md
|
||
|
||
```
|
||
|
||
Изображения тоже могут быть оформлены как сноски.
|
||
|
||
```md
|
||
![Это альтернативный текст.][myimage]
|
||
|
||
[myimage]: relative/urls/cool/image.jpg "Если нужна подсказка, её можно добавить"
|
||
```
|
||
|
||
## Разное
|
||
### Автоссылки
|
||
|
||
```md
|
||
Ссылка вида <http://testwebsite.com/> эквивалентна
|
||
[http://testwebsite.com/](http://testwebsite.com/)
|
||
```
|
||
|
||
### Автоссылки для адресов электронной почты
|
||
|
||
```md
|
||
<foo@bar.com>
|
||
```
|
||
|
||
### Экранирование символов
|
||
|
||
```md
|
||
Я хочу напечатать *текст, заключённый в звёздочки*, но я не хочу,
|
||
чтобы он был курсивным. Тогда я делаю так:
|
||
\*Текст, заключённый в звёздочки\*
|
||
```
|
||
|
||
### Клавиши на клавиатуре
|
||
В GitHub Flavored Markdown для представления клавиш на клавиатуре
|
||
вы можете использовать тег `<kbd>`.
|
||
|
||
```md
|
||
Ваш компьютер завис? Попробуйте нажать
|
||
<kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd>
|
||
```
|
||
|
||
### Таблицы
|
||
Таблицы официально поддерживаются только в GitHub Flavored Markdown,
|
||
да и синтаксис имеют не слишком удобный.
|
||
Но если очень нужно, размечайте таблицы так:
|
||
|
||
```md
|
||
| Столбец 1 | Столбец 2 | Столбец 3 |
|
||
| :----------- | :----------: | -----------: |
|
||
| Выравнивание | Выравнивание | Выравнивание |
|
||
| влево | по центру | вправо |
|
||
```
|
||
|
||
Или более компактно
|
||
|
||
```md
|
||
Столбец 1|Столбец 2|Столбец 3
|
||
:--|:-:|--:
|
||
Выглядит|это|страшновато...
|
||
```
|
||
|
||
Ну вот и всё!
|
||
|
||
За более подробной информацией обращайтесь к [статье](http://daringfireball.net/projects/markdown/syntax) Джона Грубера о синтаксисе Markdown.
|
||
|
||
Также часто бывает полезной отличная ["шпаргалка"](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) по Markdown от Адама Притчарда.
|