Разметка текстовых файлов
В настоящем разделе описаны основы разметки файлов .mdx, LaTeX и Mermaid для форматирования README-описания репозитория или иных текстовых файлов.
Приоритет отображения README.md файлов
При наличии в репозитории нескольких версий файла README.md, включая версию с суффиксом _RU или _ru, приоритет отдается именно файлу с указанным суффиксом, даже если присутствует стандартный файл README.md.
Таким образом на главной странице репозитория будет отображаться версия с суффиксом _RU, если в репозитории одновременно находятся файлы вида:
README.md;README_RU.md.
Аналогично на главной странице репозитория будет отображаться версия с суффиксом _ru, если в репозитории одновременно находятся файлы вида:
README.md;README_ru.md.
Разметка .mdx
MDX (Markdown + JSX) — это расширение обычного Markdown, которое позволяет использовать в нeм JSX-синтаксис, при этом все стандартные элементы Markdown (заголовки, списки, ссылки, изображения и т.д.) поддерживаются в mdx.
Основные различия между MD и MDX:
| Характеристика | Markdown (.md) | MDX (.mdx) |
|---|---|---|
| Синтаксис | Стандартный Markdown | Markdown с поддержкой JSX |
| Возможности | Текст, заголовки, списки и т.д. | Все возможности Markdown + JSX, компоненты |
| Использование | Документация, блоги | Интерактивные документы, блоги с UI |
| Компиляция | В HTML | Может компилироваться в React-компоненты |
| Язык | Сырой текст | JavaScript (в виде JSX) |
Оглавление
Для создания оглавления в Markdown вы можете использовать ссылки на заголовки.
Пример:
1. [Заголовки](#заголовки)
1. [Разделительная линия](#разделительная-линия)
2. [Параграфы](#параграфы)Результат:
Заголовки
В синтаксисе Markdown есть шесть уровней заголовков: от H1 до H6. Для их выделения используют решетки #:
- количество решеток соответствует уровню заголовка; 2. между решеткой и текстом ставится пробел.
Пример разметки:
# Заголовок первого уровня
## Заголовок второго уровня
...
###### Заголовок шестого уровняУ заголовков H1 и H2 есть альтернативный способ разметки - на следующей строке после них нужно поставить знаки равенства = или дефисы -:
=применяется для заголовков H1; 2.-применяется для заголовков H2; 3. можно использовать любое количество знаков, но оба знака в одной строке не размечают заголовок; 4. между заголовком и знаками не должно быть пустых строк.
Пример разметки:
# Заголовок первого уровня
# Заголовок первого уровня
## Заголовок второго уровня
## Заголовок второго уровняРазделительная линия
Разделительная линия в Markdown документах создается с помощью трех звездочек *** (или дефисов ---, или подчеркивания ___). Она обычно используется для создания четкого разделения между разными частями документа.
Пример:
Разделительная линия из дефисов --- требует пустой строки перед ней, иначе
эта строка будет размечена как заголовок второго уровня.
Параграфы
Для создания параграфов в Markdown разделяйте текст пустой строкой.
Пример (звездочка * размечает текст курсивом):
*Это первый параграф.*
*Это все еще первый параграф.*
*Это второй параграф.*
Результат:
Это первый параграф. Это все еще первый параграф.
Это второй параграф.
Выделение текста (emphasis)
| Стиль | Разметка | Пример | Результат |
|---|---|---|---|
| Жирный | ** ** или __ __ | **This** is __bold text__ | This is bold text |
| Курсив | * * или _ _ | _This text_ is *italicized* | This text is italicized |
| Зачеркнутый | ~~ ~~ | ~~This was mistaken text~~ | |
| Полужирный и вложенный курсив | ** ** и _ _ | **This text is _extremely_ important** | This text is extremely important |
| Весь полужирный и курсивный | *** *** | ***All this text is important*** | All this text is important |
| Подстрочный индекс | <sub> </sub> | This is a <sub>subscript</sub> text | This is a subscript text |
| Надстрочный индекс | <sup> </sup> | This is a <sup>superscript</sup> text | This is a superscript text |
Выдержка из кода
Экранирование символов
В Markdown символы можно экранировать с помощью обратного слэша \, чтобы они не интерпретировались как форматирование. Например, если вы хотите отобразить символ * как обычный символ, а не как начало или конец выделенного текста, вы можете написать \*.
Фрагменты кода в предложении
Для вставки коротких выдержек из кода можно использовать одиночный гравис (`).
Пример:
`git rm Filename` — удаляет файл с диска и убирает его из отслеживаемых файлов. Если файл был изменен и проиндексирован, то нужно добавить параметр `-f` — `git rm -f Filename`.
Результат:
git rm Filename — удаляет файл с диска и убирает его из отслеживаемых файлов. Если файл был изменен и проиндексирован, то нужно добавить параметр -f — git rm -f Filename.
Многострочный код
Для разметки большого участка кода в тексте его следует выделять тремя грависами в начале и в конце .
Пример:
```bash echo “Starting the script…” ls -l echo “Script execution completed.” ```
Результат:
#!/bin/bash
echo "Starting the script..."
ls -l
echo "Script execution completed."При просмотре .md файлов в профиле репозитория многострочный код, если для него указан язык программирования, можно копировать.
Пиктограмма копирования многострочного кода:

Ключевое слово после первых трех грависов используется для указания языка программирования, к которому относится фрагмент кода. Это помогает правильно подсветить синтаксис кода при отображении в `.md’ документах или на веб-страницах.
Markdown поддерживает подсветку синтаксиса для множества языков программирования:
- C * C++ * C# * CSS * Go * HTML * Java * JavaScript * JSON * Kotlin * PHP * Python * Ruby * Rust * SQL * Swift * TypeScript * и многие другие.
Комментирование строк
Вы можете комментировать строки в Markdown, используя символы <!-- -->.
Пример:
<!-- Это комментарий в Markdown -->Цитирование
Цитировать текст можно с помощью >:
> Text that is a quoteРезультат:
Text that is a quote
Вложенное цитирование
Пример:
> Это первый уровень цитирования.
>
> > Это вложенный уровень цитирования.
>
> Вернулись к первому уровню.Результат:
Это первый уровень цитирования.
Это вложенный уровень цитирования.
Вернулись к первому уровню.
Сноски
Сноски
Пример кода со сноской:
Текст сноски 1 [^1]
Текст сноски 2 [^2]
[^1]: Содержание сноски 1.
[^2]: Содержание сноски 2.Результат:

Списки
Ненумерованные списки
Вы можете сделать неупорядоченный список с помощью символов - ,* или +.
Пример:
- George Washington
* John Adams
- Thomas JeffersonРезультат:
- George Washington
- John Adams
- Thomas Jefferson
Нумерованные списки
Чтобы пронумеровать список, поставьте перед каждой строкой номер с точкой:
Пример:
1. Пункт 1.
2. Пункт 2.
3. Пункт 3.Результат:
- Пункт 1.
- Пункт 2.
- Пункт 3.
Вложенные списки
Чтобы создать вложенный список, добавьте отступы.
Пример:
1. Уровень 1:
- уровень 2:
- уровень 3;
* eще один элемент уровня 2.
2. Другой элемент уровня 1:
- второй уровень:
- третий уровень.Результат:
- Уровень 1:
- уровень 2:
- уровень 3;
- eще один элемент уровня 2.
- уровень 2:
- Другой элемент уровня 1:
- второй уровень:
- третий уровень.
- второй уровень:
Чекбоксы
Чтобы сделать чекбоксы, нужно использовать маркированный список, но между маркером и текстом поставить [x] для отмеченного пункта и [] — для неотмеченного:
- [ ] Невыполненная задача
- [x] Выполненная задачаРезультат:
- Невыполненная задача
- Выполненная задача
Ссылки
Чтобы создать встроенную ссылку, заключите ее текст в квадратные скобки [ ], а затем адрес в обычные скобки ( ).
| Пример | Результат | |
|---|---|---|
| Ссылка на URL | [GitVerse](https://gitverse.ru/) | GitVerse |
| Ссылка на раздел | [Разметка текстовых файлов][markup-guide.md] | Разметка текстовых файлов |
| Относительная ссылка | [Разметка текстовых файлов][../../docs/get-started/markup-guide.md] | Разметка текстовых файлов |
Изображения
Вы можете включить изображение, добавив ! и заключив замещающий текст в квадратные скобки [ ]. Замещающий текст — это короткий текст, эквивалентный информации на изображении. Затем в круглых скобках () оставьте ссылку на изображение.
Пример добавления изображения - .
Ссылки внутри изображения
Для создания ссылок внутри изображения в Markdown, вы можете использовать следующий синтаксис - [](http://example.com/), где
Alt text- это альтернативный текст для изображения; *image.jpg- путь к изображению; *http://example.com/- ссылка, куда будет вести изображение.
Пример:
[](https://gitverse.ru/new_horizons/NeuralNetworks/content/master/articles/article2)Результат:
Таблицы
Используйте символы | и - для создания таблицы с заголовком.
Пример:
| Заголовок 1 | Заголовок 2 |
| ----------- | ----------- |
| Строка 1 | Строка 2 |Результат:
| Заголовок 1 | Заголовок 2 |
|---|---|
| Строка 1 | Строка 2 |
Выравнивание в таблицах
Используйте двоеточие для выравнивания текста в ячейках.
Пример:
| Лево | По центру | Право |
|:-------------|:------------:|-------------:|
| выравнивание | выравнивание | выравнивание |Результат:
| Лево | По центру | Право |
|---|---|---|
| выравнивание | выравнивание | выравнивание |
Эмодзи
Для добавления эмодзи в Markdown вы можете использовать его код с двоеточием в начале и конце. Например:
😊 :blush: | 😄 :smile: | 😆 :laughing: |
|---|---|---|
😏 :smirk: | 😃 :smiley: | 😘 :kissing_heart: |
😚 :kissing_closed_eyes: | 😍 :heart_eyes: | 😌 :relieved: |
Полный список emoji можно посмотреть по ссылке.
HTML теги в .md
Markdown поддерживаются некоторые распространенные HTML теги.
Коды клавиш клавиатуры
Для указания пользовательского вводимого значения (например, клавиши клавиатуры) в Markdown используется HTML тег <kbd>. Например, <kbd>Ctrl</kbd>+<kbd>C</kbd> будет отображаться как Ctrl+C.
Другие теги
-
Параграфы -
<p>Это пример параграфа в Markdown.</p>. -
Ссылки -
<a href="https://www.example.com">Название ссылки</a>. -
Изображения.
Пример использования тега
<img> </img>для вставки изображения и тега<a> </a>для создания ссылки вокруг изображения:<a href="https://www.example.com"> <img src="image.jpg" alt="Описание изображения" /> </a> -
Списки.
Пример использования тегов
<ul> </ul>для маркированного списка (unordered list) и<ol> </ol>для нумерованного списка (ordered list):<ul> <li>Элемент списка 1</li> <li>Элемент списка 2</li> <li>Элемент списка 3</li> </ul> <ol> <li>Элемент списка 1</li> <li>Элемент списка 2</li> <li>Элемент списка 3</li> </ol> -
Код:
<code>git log --grep="TASK-996"</code>. -
Разделительная линия -
<hr> </hr>(для разделительной линии в .md может требоваться закрывающий тег</hr>).
LaTeX-формулы
В настоящем разделе описано использование LaTeX-формул в Markdown.
Markdown поддерживает встраивание математических выражений через LaTeX-синтаксис с использованием библиотек вроде KaTeX или MathJax.
Формулы внутри строки
Для отображения математической формулы внутри текста используйте двойные $:
Теорема Пифагора: $ a^2 + b^2 = c^2 $Формулы на новой строке (отдельный блок)
Для отображения формулы на новой строке и выделения ее в виде отдельного блока используйте $$ ... $$:
\int_{0}^{1} f(x) dx
Примеры формул
Квадратное уравнение
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
Матрица
\begin{bmatrix}
1 & 2 \\
3 & 4
\end{bmatrix}
Сумма
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
Полный список поддерживаемых команд можно найти в справочнике KaTeX.
Mermaid-диаграммы
В Markdown поддерживаются диаграммы с использованием языка Mermaid. Это позволяет создавать графики, блок-схемы, последовательности и другие визуализации прямо в документе.
Блок-схемы (Flowcharts)
graph TD
A[Start] --> B{Condition}
B -- Yes --> C[End]
B -- No --> D[Repeat]Результат:
Схемы последовательности (Sequence Diagrams)
sequenceDiagram
participant User
participant Browser
participant Server
User->>Browser: Click button
Browser->>Server: Fetch data
Server-->>Browser: Return data
Browser-->>User: Display resultРезультат:
Графики задач (Gantt)
gantt
title Проектный план
dateFormat YYYY-MM-DD
section Разработка
Задача 1 :a1, 2025-04-01, 7d
Задача 2 :after a1, 5d
section Тестирование
Тестирование :2025-04-15, 10dER-диаграммы
erDiagram
USER ||--o{ ORDER : places
ORDER ||--o{ ORDER_ITEM : contains
PRODUCT ||--o{ ORDER_ITEM : "is part of"Результат:
Разметка .adoc
AsciiDoc (.adoc) — это семантический формат разметки, предназначенный для написания технической документации. Он предоставляет богатый набор инструментов для структурирования контента, включая сложные таблицы, кросс-ссылки, включения файлов и условное содержимое. В отличие от Markdown, AsciiDoc изначально разрабатывался для создания книг и объемных технических руководств.
Основные различия между Markdown и AsciiDoc:
| Характеристика | Markdown (.md) | AsciiDoc (.adoc) |
|---|---|---|
| Синтаксис | Простой, минималистичный | Более сложный, но мощный и гибкий |
| Возможности | Базовое форматирование | Расширенное форматирование, атрибуты, макросы |
| Использование | Блоги, README-файлы | Техническая документация, книги, мануалы |
| Язык | Сырой текст | Сырой текст с расширенной семантикой |
| Обработка | Простые конвертеры в HTML | Мощные процессоры (Asciidoctor) |
Оглавление
В AsciiDoc оглавление генерируется автоматически при использовании атрибута :toc: в заголовке документа.
Пример:
= Заголовок документа
:toc:
== Первый раздел
=== Подраздел
== Второй разделЗаголовки
Заголовки в AsciiDoc создаются с помощью знаков равенства =. Количество знаков определяет уровень заголовка.
- один знак
=для заголовка первого уровня (название документа); 2. два знака==для заголовка второго уровня; 3. три знака===для третьего уровня и т.д.
Пример разметки:
= Заголовок первого уровня (название документа)
== Заголовок второго уровня
=== Заголовок третьего уровня
==== Заголовок четвертого уровняРазделительная линия
Разделительная линия в AsciiDoc создается с помощью четырех или более дефисов ----.
Пример:
----Результат:
Параграфы
Параграфы в AsciiDoc разделяются одной или несколькими пустыми строками, как и в Markdown.
Пример:
Это первый параграф.
Это второй параграф.Выделение текста (emphasis)
| Стиль | Разметка | Пример | Результат |
|---|---|---|---|
| Жирный | * * | *Этот текст жирный* | Этот текст жирный |
| Курсив | _ _ | _Этот текст курсивом_ | Этот текст курсивом |
| Моноширинный | + + | +моноширинный текст+ | моноширинный текст |
| Зачеркнутый | [line-through]# # | [line-through]#зачеркнутый# | |
| Подстрочный | ~ ~ | H~2~O | H |
| Надстрочный | ^ ^ | E = mc^2^ | E = mc^2^ |
Выдержка из кода
Экранирование символов
Символы можно экранировать с помощью обратного слэша \, например, \* для отображения звездочки.
Фрагменты кода в предложении
Для вставки инлайн-кода используется обратный апостроф ` или плюсы +.
Пример:
Используйте команду `git commit` или +git commit+ для фиксации изменений.Многострочный код
Блоки кода выделяются с помощью отступов в четыре пробела или с помощью блоков с отбивкой.
Пример с отбивкой:
[source,bash]
----
#!/bin/bash
echo "Hello, World!"
ls -l
----Атрибут source указывает, что это исходный код, а bash — язык подсветки.
Комментирование строк
Комментарии в AsciiDoc начинаются с двух слэшей //.
Пример:
// Это комментарий, он не будет отображаться в финальном документе.Цитирование
Цитаты создаются с помощью символов [quote] и последующего блока.
Пример:
[quote, Автор, Источник]
____
Это цитируемый текст.
____Вложенное цитирование
Для вложенных цитат можно использовать тот же синтаксис внутри блока.
Списки
Ненумерованные списки
Используются звездочки * или дефисы -.
Пример:
* Первый элемент
* Второй элемент
** Вложенный элементНумерованные списки
Используются цифры с точкой или просто цифры.
Пример:
1. Первый пункт
2. Второй пунктЧекбоксы
Чекбоксы создаются с помощью символов [ ] и [x].
Пример:
* [ ] Невыполненная задача
* [x] Выполненная задачаСсылки
Ссылки в AsciiDoc создаются с помощью угловых скобок или макроса link.
Пример:
Посетите сайт <<https://gitverse.ru/, GitVerse>> или используйте link:https://gitverse.ru/[GitVerse].Изображения
Изображения вставляются с помощью макроса image.
Пример:
image::./resources/softmax.webp[Alt text, width=300]Ссылки внутри изображения
Для создания кликабельного изображения можно обернуть его в ссылку.
Пример:
<<https://gitverse.ru/new_horizons/NeuralNetworks/content/master/articles/article2, image:./resources/softmax.webp[Softmax]>>Таблицы
AsciiDoc предоставляет мощный синтаксис для создания таблиц.
Пример:
[cols="1,2"]
|===
| Заголовок 1 | Заголовок 2
| Строка 1, Колонка 1
| Строка 1, Колонка 2
| Строка 2, Колонка 1
| Строка 2, Колонка 2
|===Атрибут cols определяет ширину колонок.
Выравнивание в таблицах
Выравнивание задается в атрибутах колонок: < (лево), ^ (центр), > (право).
Пример:
[cols="<,^,>"]
|===
| Лево | Центр | Право
| текст | текст | текст
|===Эмодзи
AsciiDoc напрямую не поддерживает эмодзи через коды вроде :smile:, но они могут отображаться, если вставлены как символы Unicode или через HTML-коды.
HTML теги в .adoc
AsciiDoc позволяет вставлять HTML-теги, но это не рекомендуется, так как нарушает принцип семантической разметки. Лучше использовать нативные возможности AsciiDoc.
Коды клавиш клавиатуры
Для обозначения клавиш используется макрос kbd.
Пример:
Нажмите kbd:[Ctrl+C] для копирования.Дополнительные возможности AsciiDoc
AsciiDoc обладает рядом уникальных функций, отсутствующих в Markdown:
- Атрибуты: Позволяют определять переменные и настройки для всего документа.
- Включения файлов: Позволяют включать содержимое других файлов с помощью
include::filename.adoc[]. - Условное содержимое: Позволяет показывать или скрывать части документа в зависимости от условий.
- Перекрестные ссылки: Мощная система ссылок на разделы, таблицы, рисунки внутри документа.
Для более глубокого изучения синтаксиса AsciiDoc рекомендуется обратиться к официальной документации Asciidoctor.
