Разметка текстовых файлов

В настоящем разделе описаны основы разметки файлов .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 вы можете использовать ссылки на заголовки.

Пример:

1. [Заголовки](#заголовки)
   1. [Разделительная линия](#разделительная-линия)
   2. [Параграфы](#параграфы)

Результат:

1. Заголовки
   1. Разделительная линия
   2. Параграфы

Заголовки

В синтаксисе Markdown есть шесть уровней заголовков: от H1 до H6. Для их выделения используют решетки #:

Пример разметки:

# Заголовок первого уровня
 
## Заголовок второго уровня
 
...
 
###### Заголовок шестого уровня

У заголовков H1 и H2 есть альтернативный способ разметки - на следующей строке после них нужно поставить знаки равенства = или дефисы -:

Пример разметки:

# Заголовок первого уровня
 
# Заголовок первого уровня
 
## Заголовок второго уровня
 
## Заголовок второго уровня

Разделительная линия

Разделительная линия в Markdown документах создается с помощью трех звездочек *** (или дефисов ---, или подчеркивания ___). Она обычно используется для создания четкого разделения между разными частями документа.

Пример:

Параграфы

Для создания параграфов в Markdown разделяйте текст пустой строкой.

Пример (звездочка * размечает текст курсивом):

Результат:

Выделение текста (emphasis)

Выдержка из кода

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

В 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 поддерживает подсветку синтаксиса для множества языков программирования:

Комментирование строк

Вы можете комментировать строки в 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. Пункт 1.
2. Пункт 2.
3. Пункт 3.

Вложенные списки

Чтобы создать вложенный список, добавьте отступы.

Пример:

1. Уровень 1:
   - уровень 2:
     - уровень 3;
   * eще один элемент уровня 2.
2. Другой элемент уровня 1:
   - второй уровень:
     - третий уровень.

Результат:

1. Уровень 1:
   • уровень 2:
     • уровень 3;
   • eще один элемент уровня 2.
2. Другой элемент уровня 1:
   • второй уровень:
     • третий уровень.

Чекбоксы

Чтобы сделать чекбоксы, нужно использовать маркированный список, но между маркером и текстом поставить [x] для отмеченного пункта и [] — для неотмеченного:

- [ ] Невыполненная задача
- [x] Выполненная задача

Результат:

• Невыполненная задача
• Выполненная задача

Ссылки

Чтобы создать встроенную ссылку, заключите ее текст в квадратные скобки [ ], а затем адрес в обычные скобки ( ).

Изображения

Вы можете включить изображение, добавив ! и заключив замещающий текст в квадратные скобки [ ]. Замещающий текст — это короткий текст, эквивалентный информации на изображении. Затем в круглых скобках () оставьте ссылку на изображение.

Пример добавления изображения - ![Softmax](./resources/softmax.webp).

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

Для создания ссылок внутри изображения в Markdown, вы можете использовать следующий синтаксис - [![Alt text](image.jpg)](http://example.com/), где

Пример:

[![Softmax](./resources/softmax.webp)](https://gitverse.ru/new_horizons/NeuralNetworks/content/master/articles/article2)

Результат:

Таблицы

Используйте символы | и - для создания таблицы с заголовком.

Пример:

| Заголовок 1 | Заголовок 2 |
| ----------- | ----------- |
| Строка 1    | Строка 2    |

Результат:

Выравнивание в таблицах

Используйте двоеточие для выравнивания текста в ячейках.

Пример:

| Лево         | По центру    | Право        |
|:-------------|:------------:|-------------:|
| выравнивание | выравнивание | выравнивание |

Результат:

Эмодзи

Для добавления эмодзи в Markdown вы можете использовать его код с двоеточием в начале и конце. Например:

HTML теги в .md

Markdown поддерживаются некоторые распространенные HTML теги.

Коды клавиш клавиатуры

Для указания пользовательского вводимого значения (например, клавиши клавиатуры) в Markdown используется HTML тег <kbd>. Например, <kbd>Ctrl</kbd>+<kbd>C</kbd> будет отображаться как Ctrl+C.

Другие теги

1. Параграфы - <p>Это пример параграфа в Markdown.</p>.

2. Ссылки - <a href="https://www.example.com">Название ссылки</a>.

3. Изображения.

   Пример использования тега <img> </img> для вставки изображения и тега <a> </a> для создания ссылки вокруг изображения:

   <a href="https://www.example.com">
   	<img src="image.jpg" alt="Описание изображения" />
   </a>

4. Списки.

   Пример использования тегов <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>

5. Код: <code>git log --grep="TASK-996"</code>.

6. Разделительная линия - <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}

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, 10d

ER-диаграммы

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--o{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "is part of"

Результат:

Разметка .adoc

AsciiDoc (.adoc) — это семантический формат разметки, предназначенный для написания технической документации. Он предоставляет богатый набор инструментов для структурирования контента, включая сложные таблицы, кросс-ссылки, включения файлов и условное содержимое. В отличие от Markdown, AsciiDoc изначально разрабатывался для создания книг и объемных технических руководств.

Основные различия между Markdown и AsciiDoc:

Оглавление

В AsciiDoc оглавление генерируется автоматически при использовании атрибута :toc: в заголовке документа.

Пример:

= Заголовок документа
:toc:
 
== Первый раздел
 
=== Подраздел
 
== Второй раздел

Заголовки

Заголовки в AsciiDoc создаются с помощью знаков равенства =. Количество знаков определяет уровень заголовка.

Пример разметки:

= Заголовок первого уровня (название документа)
 
== Заголовок второго уровня
 
=== Заголовок третьего уровня
 
==== Заголовок четвертого уровня

Разделительная линия

Разделительная линия в AsciiDoc создается с помощью четырех или более дефисов ----.

Пример:

----

Результат:

Параграфы

Параграфы в AsciiDoc разделяются одной или несколькими пустыми строками, как и в Markdown.

Пример:

Это первый параграф.
 
Это второй параграф.

Выделение текста (emphasis)

Выдержка из кода

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

Символы можно экранировать с помощью обратного слэша \, например, \* для отображения звездочки.

Фрагменты кода в предложении

Для вставки инлайн-кода используется обратный апостроф ` или плюсы +.

Пример:

Используйте команду `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[].
• Условное содержимое: Позволяет показывать или скрывать части документа в зависимости от условий.
• Перекрестные ссылки: Мощная система ссылок на разделы, таблицы, рисунки внутри документа.