Что такое Markdown?

12 мин

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

В этом уроке мы обсудим структуру и синтаксис Markdown. Мы также рассмотрим функции GitHub-Flavored Markdown (GFM), которые являются расширениями синтаксиса, которые позволяют интегрировать функции GitHub в содержимое.

Примечание.

В этом модуле вы можете познакомиться с Markdown. Дополнительные сведения см . в описании синтаксиса Markdown и статьях GitHub-Flavored Markdown Spec в этом модуле Сводки.

Подчеркивать текст

Наиболее важной частью любого взаимодействия на GitHub обычно является сам текст, но как вы показываете, что некоторые части текста более важны, чем другие?

Использовать курсив в тексте просто: укажите в начале и конце нужного фрагмента по одному символу звездочки (*) или подчеркивания (_). Просто закройте акцент с тем же символом, с которым вы открыли его. Наблюдайте за тем, как сочетать использование звездочек и подчеркивания. Вот несколько примеров:

This is *italic* text.
This is also _italic_ text.

Это текст курсивом. Это тоже текст курсивом.

Чтобы выделить текст полужирным шрифтом, используйте два символа звездочки (**) или подчеркивания (__).

This is **bold** text.
This is also __bold__ text.

Это полужирный текст. Это тоже полужирный текст.

Можно также смешивать разные выделения.

_This is **italic and bold** text_ using a single underscore for italic and double asterisks for bold.
__This is bold and *italic* text__ using double underscores for bold and single asterisks for italic.

Это текст, выделенный курсивом и полужирным шрифтом. Курсив задает одна звездочка, а полужирный шрифт — двойное подчеркивание. Это текст, выделенный полужирным шрифтом и курсивом. Полужирный шрифт задает двойное подчеркивание, а курсив — одна звездочка.

Чтобы использовать звездочку литерала, предшествуйте ей escape-символом; в GFM это обратная косая черта (\). В этом примере в результатах отображаются символы подчеркивания и звездочки.

\_This is all \*\*plain\*\* text\_.

_Это **обычный** текст_.

Объявление заголовков

HTML предоставляет заголовки содержимого <h1> , такие как тег. В Markdown это поддерживается с помощью символа #. Просто используйте один # для каждого уровня заголовка от 1 до 6.

###### This is H6 text

Это текст со стилем H6

Ссылка на изображения и сайты

Ссылки на изображения и сайты используют аналогичный синтаксис.

![Link an image.](/learn/azure-devops/shared/media/mara.png)

[Link to Microsoft Training](/training)

Ссылка на Обучение Майкрософт

Создание списков

Можно определить нумерованные и маркированные списки. Кроме того, можно определить вложенные элементы с помощью отступов.

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

Вот Markdown для упорядоченного списка:

1. First
1. Second
1. Third

Результат:

First

Second

Третья

Вот Markdown для неупорядоченного списка:

- First
  - Nested
- Second
- Third

Первые

Вложенный

Second

Третья

Сборка таблиц

Таблицы можно создавать с помощью сочетания вертикальных черточек (|) для обозначения разрывов столбцов и тире (-) для указания первой строки в качестве заголовка.

First|Second
-|-
1|2
3|4

First Second

1 2

3 4

First	Second
1	2
3	4

Текст кавычки

Цитаты можно создать с помощью знака "больше" (>).

> This is quoted text.

Это текст в кавычках.

Заполнение пробелов встроенным HTML

Если вы столкнулись с html-сценарием, не поддерживаемым Markdown, вы можете использовать этот html-код встроенного кода.

Here is a<br />line break

Это
разрыв строки

Работа с кодом

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

This is `code`.

Это code.

Если сегмент кода охватывает несколько строк, можно использовать три обратных апострофа (```) до и после кода, чтобы создать огражденный код блока.

```markdown
var first = 1;
var second = 2;
var sum = first + second;
```

var first = 1;
var second = 2;
var sum = first + second;

GFM расширяет эту поддержку, выделяя синтаксис популярных языков. Просто укажите язык в части первой последовательности делений.

```javascript
var first = 1;
var second = 2;
var sum = first + second;
```

var first = 1;
var second = 2;
var sum = first + second;

Проблемы с перекрестным подключением и запросы на вытягивание

GFM поддерживает различные форматы shortcode, чтобы упростить связь с проблемами и запросами на вытягивание. Самый простой способ сделать это — использовать формат #ID, как, например, #3602. GitHub автоматически настраивает более длинные ссылки на этот формат при их вставке. Существуют также дополнительные соглашения, которым можно следовать, если вы работаете с другими средствами или хотите указать другие проекты/ветви.

Тип ссылки	Простая ссылка	Короткая ссылка
URL-адрес проблемы или запроса на внесение изменений	`https://github.com/desktop/desktop/pull/3602`	#3602
`#` и номер проблемы или запроса на внесение изменений	#3602	#3602
`GH-` и номер проблемы или запроса на внесение изменений	GH-3602	GH-3602
`Username/Repository#` и номер проблемы или запроса на внесение изменений	desktop/desktop#3602	desktop/desktop#3602

Дополнительные сведения см . в статье об автоматических ссылках и URL-адресах этого модуля.

Связывание определенных фиксаций

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

Тип ссылки	Простая ссылка	Короткая ссылка
URL-адрес фиксации	https://github.com/desktop/desktop/commit/
8304e9c271a5e5ab4fda797304cd7bcca7158c87	8304e9c
SHA	8304e9c271a5e5ab4fda797304cd7bcca7158c87	8304e9c
User@SHA	desktop@8304e9c271a5e5ab4fda797304cd7bcca7158c87	desktop@8304e9c
Username/Repository@SHA	desktop/desktop@8304e9c271a5e5ab4fda797304cd7bcca7158c87	desktop/desktop@8304e9c

Упоминание пользователей и команд

Ввод символа @ , за которым следует имя пользователя GitHub, отправляет уведомление этому лицу о комментарии. Это называется "@mention", так как вы упоминаете отдельное лицо. Вы также можете @mention команды в организации.

@githubteacher

@githubteacher

Отслеживание списков задач

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

- [x] First task
- [x] Second task
- [ ] Third task

Снимок экрана: список задач GitHub.

Команды косой черты

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

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

Команда	Description
`/code`	Вставляет блок кода Markdown. Вы выбираете язык.
`/details`	Вставляет область сворачиваемой детализации. Вы выбираете название и содержимое.
`/saved-replies`	Вставляет сохраненный ответ. Вы выбираете сохраненные ответы для учетной записи пользователя. Если добавить `%cursor%` в сохраненный ответ, команда косой черты помещает курсор в это расположение.
`/table`	Вставляет таблицу Markdown. Вы выбираете количество столбцов и строк.
`/tasklist`	Вставляет список задач. Эта команда косой черты работает только в описании проблемы.
`/template`	Отображает все шаблоны в репозитории. Вы выбираете шаблон для вставки. Эта команда косой черты работает для шаблонов проблем и шаблона запроса на вытягивание.