Центр заботы
Начало работы
Разметка текстовых файлов

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

В настоящем разделе описаны основы разметки файлов .md для форматирования README описания репозитория или иных текстовых файлов.

Заголовки

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

  1. количество решёток соответствует уровню заголовка;
  2. между решёткой и текстом ставится пробел.

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

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

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

  1. = применяется для заголовков 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 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> textThis is a subscript text
Надстрочный индекс<sup> </sup>This is a <sup>superscript</sup> textThis is a superscript text

Таблицы

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

Пример:

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

Результат:

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

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

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

Пример:

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

Результат:

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

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

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

В 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

Вложенное цитирование

Пример:

> Это первый уровень цитирования.
>
> > Это вложенный уровень цитирования.
>
> Вернулись к первому уровню.

Результат:

Это первый уровень цитирования.

Это вложенный уровень цитирования.

Вернулись к первому уровню.

Ссылки

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

ПримерРезультат
Ссылка на URL[GitVerse](https://gitverse.ru/)GitVerse (opens in a new tab)
Ссылка на раздел[Разметка текстовых файлов][markup-guide.md]Разметка текстовых файлов
Относительная ссылка[Разметка текстовых файлов][../../docs/get-started/markup-guide.md]Разметка текстовых файлов

Изображения

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

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

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

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

  • Alt text - это альтернативный текст для изображения;
  • image.jpg - путь к изображению;
  • http://example.com/ - ссылка, куда будет вести изображение.

Пример:

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

Результат:

Softmax (opens in a new tab)

Списки

Ненумерованные списки

Вы можете сделать неупорядоченный список с помощью символов - ,* или +.

Пример:

- 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] Выполненная задача

Результат:

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

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>
  1. Списки.

Пример использования тегов <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>
  1. Код: <code>git log --grep="TASK-996"</code>.
  2. Разделительная линия - <hr> </hr> (для разделительной линии в .md может требоваться закрывающий тег </hr>).
ДашбордСистемные требования