Описание разметки файла README.md

Для описания проектов на GitHub используется README.md, который пишется на языке разметки markdown. Что и как поддерживается расписано ниже. Также существует еще один формат - reStructuredText, описание которого вынесено в отдельный файл README.rst.

Разделительная черта
Заголовки
Работа с выделением текста
Использование эмодзи (emoji)
Использование цитирования в тексте
Подсветка кода
Списки
Ссылки
Вставка изображения
Вставка таблиц
Диаграмм Mermaid.js
Дополнения

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

При использовании

____

получается разделительная черта

⬆️Оглавление

Заголовки

Всего существует шесть уровней заголовков. Для того, чтобы создать заголовок, необходимо в начале строки добавить символы #, в количестве равном его уровню.

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

# Заголовок 1

Заголовок первого уровня также можно создать:

Заголовок 1
===========

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

## Заголовок 2

Заголовок второго уровня также можно создать:

Заголовок 2
-----------

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

### Заголовок 3

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

#### Заголовок 4

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

##### Заголовок 5

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

###### Заголовок 6

⬆️Оглавление

Работа с выделением текста

~~Зачеркнутый текст~~

~~Зачеркнутый текст (Strikethrough)~~

Для выделения текста жирным или наклонным и их сочетания можно использовать комбинации * или _

**Жирный текст (bold)**

Жирный текст (bold)

*Наклонный текст (italic)*

Наклонный текст (italic)

***Жирный наклонный текст (bold italic)***

Жирный наклонный текст (bold italic)

__Жирный текст (bold)__

Жирный текст (bold)

_Наклонный текст (italic)_

Наклонный текст (italic)

___Жирный наклонный текст (bold italic)___

Жирный наклонный текст (bold italic)

~~*__Тут странный текст__*~~

~~Тут странный текст~~

⬆️Оглавление

Использование эмодзи (emoji)

В самом тексте можно использовать эмодзи, например написать вот так:
✅ Это уже сделано
❎ Я не буду это делать
🔲 делать или не делать, вот в чем вопрос?
В оригинале это выглядит так (в конце строки четыре (4) пробела для того, что бы был переход на новую строку):

:white_check_mark: Это уже сделано    
:negative_squared_cross_mark: Я не буду это делать    
:black_square_button: делать или не делать, вот в чем вопрос?

Список работающих Эмодзи находится тут -> emoji.md

⬆️Оглавление

Использование цитирования в тексте

> Цитата (уровень 1)    
> > Вложенная цитата (уровень 2)    
> > > Вложенная цитата (уровень 3)    

> > Продолжение цитаты (уровень 2)    

> Продолжение цитаты (уровень 1)

Цитата (уровень 1)

Вложенная цитата (уровень 2)

Вложенная цитата (уровень 3)

Продолжение цитаты (уровень 2)

Продолжение цитаты (уровень 1)

Внешний вид, конечно, не очень, но может и пригодиться.

⬆️Оглавление

Подсветка кода

Если нужно выделить слово или фразу внутри строки, то используются одинарные обратные кавычки (`):

Это `слово` будет выделено

Для выделения в блоки - тройные:

```
    Здесь может быть
    Ваша реклама
```

Дополнительно можно задавать язык кода внутри блока, указав его после первых трех кавычек:

```html
    <input type="text">
```

```css
    body {
        margin: 0;
        padding: 0;
    }
```

```php
    <?php phpinfo();?>
```

Пример блока для C#:

using MarkdownSharp;
using MarkdownSharp.Extensions.Mal;

Markdown mark = new Markdown();

// Short link for MAL - 
// http://myanimelist.net/people/413/Kitamura_Eri => mal://Kitamura_Eri
mark.AddExtension(new Articles()); 
mark.AddExtension(new Profile());

mark.Transform(text);

Пример блока для Python:

from timeit import Timer

tmp = "Python 3.2.2 (default, Jun 12 2011, 15:08:59) [MSC v.1500 32 bit (Intel)] on win32."

def case1(): # А. инкрементальные конкатенации в цикле
    s = ""
    for i in range(10000):
        s += tmp

def case2(): # Б. через промежуточный список и метод join
    s = []
    for i in range(10000):
        s.append(tmp)
    s = "".join(s)

def case3(): # В. списковое выражение и метод join
    return "".join([tmp for i in range(10000)])

def case4(): # Г. генераторное выражение и метод join
    return "".join(tmp for i in range(10000))

for v in range(1,5):
    print (Timer("func()","from __main__ import case%s as func" % v).timeit(200))

⬆️Оглавление

Списки

Маркированный

Задать маркированный список можно несколькими символами -, + или *:

- Уровень списка 1. Пункт 1.
- Уровень списка 1. Пункт 2.
- Уровень списка 1. Пункт 3.

Уровень списка 1. Пункт 1.
Уровень списка 1. Пункт 2.
Уровень списка 1. Пункт 3.

+ Уровень списка 1. Пункт 1.
+ Уровень списка 1. Пункт 2.
+ Уровень списка 1. Пункт 3.

Уровень списка 1. Пункт 1.
Уровень списка 1. Пункт 2.
Уровень списка 1. Пункт 3.

* Уровень списка 1. Пункт 1.
* Уровень списка 1. Пункт 2.
* Уровень списка 1. Пункт 3.

Уровень списка 1. Пункт 1.
Уровень списка 1. Пункт 2.
Уровень списка 1. Пункт 3.

Можно создавать многоуровневые списки. Каждый уровень отделяется четырьмя (4) пробелами:

- Уровень списка 1. Пункт 1.
    - Уровень списка 2. Пункт 1.
- Уровень списка 1. Пункт 2.
    - Уровень списка 2. Пункт 1.
    - Уровень списка 2. Пункт 2.
- Уровень списка 1. Пункт 3.
    - Уровень списка 2. Пункт 1.
        - Уровень списка 3. Пункт 1.
        - Уровень списка 3. Пункт 2.
           - Уровень списка 4. Пункт 1.

Уровень списка 1. Пункт 1.
- Уровень списка 2. Пункт 1.
Уровень списка 1. Пункт 2.
- Уровень списка 2. Пункт 1.
- Уровень списка 2. Пункт 2.
Уровень списка 1. Пункт 3.
- Уровень списка 2. Пункт 1.
  - Уровень списка 3. Пункт 1.
  - Уровень списка 3. Пункт 2.
    - Уровень списка 4. Пункт 1.

Каждый уровень отделяется двумя пробелами.

Нумерованный

Для Githib работа с нумерованными списками выглядит очень интересно. Каждый уровень отделяется четырьмя (4) пробелами:

1. Первый уровень 1
    1. Второй уровень 1
        1. Третий уровень 1
            1. Четвертый уровень 1
                1. Пятый уровень 1
                    1. Шестой уровень
                        1. Седьмой уровень
                            1. Седьмой уровень
2. Первый уровень 2
2. Первый уровень (должно быть 3)
4. Первый уровень 4

Первый уровень 1
1. Второй уровень 1
  1. Третий уровень 1
    1. Четвертый уровень 1
      1. Пятый уровень 1
        
        Шестой уровень
        
        Седьмой уровень
        
        Седьмой уровень
Первый уровень 2
Первый уровень (должно быть 3)
Первый уровень 4

Смешанные списки

При использовании смешанных списков нужно очень внимательно следить за нумерацией. Лучше, как и в нумерованных, использовать четыре (4) пробела для отделения уровня.

1. Первый уровень "нумерованный" - 1
    * Второй уровень "маркер"
        + Третий уровень "маркер"
        - Третий уровень "маркер"
        1. Третий уровень "нумерованный" - 1
            1. Четвертый уровень "нумерованный" - 1
                1. Пятый уровень "нумерованный" - 1
                    1. Шестой уровень "нумерованный" - 1
                        1. Седьмой уровень "нумерованный" - 1
                        * Седьмой уровень "маркер"
                        2. Седьмой уровень "нумерованный" - 1 (нарушена нумерация, новая нумерация 1)
                        3. Седьмой уровень "нумерованный" - 1 (нарушена нумерация, новая нумерация 2)
                            1. Восьмой уровень "нумерованный" - 1
2. Первый уровень "нумерованный" - 2
- Первый уровень "нумерованный" - 3
4. Первый уровень "нумерованный" - 4 (нарушена нумерация, новая нумерация 1)
5. Первый уровень "нумерованный" - 5 (нарушена нумерация, новая нумерация 2)

Первый уровень "нумерованный" - 1
- Второй уровень "маркер"
  - Третий уровень "маркер"
  - Третий уровень "маркер"
  1. Третий уровень "нумерованный" - 1
    1. Четвертый уровень "нумерованный" - 1
      1. Пятый уровень "нумерованный" - 1
        
        Шестой уровень "нумерованный" - 1
        
        Седьмой уровень "нумерованный" - 1
        
        Седьмой уровень "маркер"
        
        Седьмой уровень "нумерованный" - 2
        
        Седьмой уровень "нумерованный" - 3
        
        Восьмой уровень "нумерованный" - 1
Первый уровень "нумерованный" - 2

Первый уровень "маркерный" - 3

Первый уровень "нумерованный" - 4 (хотя по идее должен быть 3)
Первый уровень "нумерованный" - 5 (хотя, по идее должен быть 3)

Список задач

(Task List) Можно создавать "Списки задач" для этого необходимо использовать - [ ] для поставленной задачи и - [X] для выполненной задачи.

- [X] Придумать внешний вид резюме
- [ ] Написать основные категории
- [X] Опубликовать

Придумать внешний вид резюме
Написать основные категории
Опубликовать

Также можно создавать многоуровневые списки задач. Каждый уровень отделяется четырьмя (4) пробелами:

- [X] Задача 1
    - [X] Подзадача 1 для Задачи 1
    - [X] Подзадача 2 для Задачи 1
- [ ] Задача 2
    - [X] Подзадача 1 для Задачи 2
    - [ ] Подзадача 2 для Задачи 2
- [ ] Задача 3
    - [ ] Подзадача 1 для Задачи 3
        - [ ] Подзадача 1 для Подзадача 1 для Задачи 3

Задача 1
- Подзадача 1 для Задачи 1
- Подзадача 2 для Задачи 1
Задача 2
- Подзадача 1 для Задачи 2
- Подзадача 2 для Задачи 2
Задача 3
- Подзадача 1 для Задачи 3
  - Подзадача 1 для Подзадача 1 для Задачи 3

⬆️Оглавление

Ссылки

Либо просто вставить ссылку, либо дополнительно задать текст ссылки (пробела между скобками быть не должно):

Первый вариант вставки ссылок - это просто написать адрес сайта http://sabaka.net

Первый вариант вставки ссылок - это просто написать адрес сайта http://sabaka.net

Второй вариант записывается так: [текст ссылки](адрес ссылки)

[sabaka.net](http://sabaka.net)

sabaka.net

⬆️Оглавление

Вставка изображения

![Alt-текст](https://avatars1.githubusercontent.com/u/5384215?v=3&s=460 "Орк")

Дополнительно:

Вставка ссылки с картинкой на ролик с YouTube

Описание комбинации [![Тут текст](адрес до картинки)](ссылка на страничку YouTube)
Пример:
[![Тут текст](https://img.youtube.com/vi/RHPYGwVQB2o/0.jpg)](https://youtu.be/RHPYGwVQB2o)
Что мы увидим:

⬆️Оглавление

Вставка таблиц

| LEFT | CENTER | RIGHT |
|----------------|:---------:|----------------:|
| По левому краю | По центру | По правому краю |
| текст | текст | текст |

LEFT	CENTER	RIGHT
По левому краю	По центру	По правому краю
текст	текст	текст

Внимание: Если в тексте таблицы нужно использовать символ "вертикальная черта - |", то в место него необходимо написать замену на комбинацию HTML-кода* |, это нужно для того, что бы таблица не потеряла ориентации.
*) - Можно использовать ASCII и/или UTF коды.

Пример:

| Обозначение | Описание | Пример регулярного выражения|
|----:|:----:|:----------|
| literal | Строка содержит символьный литерал literal | foo |
| re1&#124;re2 | Строка содержит регулярные выражения `rel` или `re2` | foo&#124;bar |

Результат:

Обозначение	Описание	Пример регулярного выражения
literal	Строка содержит символьный литерал literal	foo
re1\|re2	Строка содержит регулярные выражения `rel` или `re2`	foo\|bar

⬆️Оглавление

Диаграмм Mermaid.js

Появилась возможность вставлять диаграммы Mermaid.js

```mermaid
... код диаграммы ...
```

Пример:

```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
```

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

Очень подробно на русском языке о диаграммах Mermaid.js: https://habr.com/ru/post/652867/

⬆️Оглавление

maxim1770/format-README

Описание разметки файла README.md

Оглавление

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

Заголовки

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

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

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

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

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

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

Работа с выделением текста

Использование эмодзи (emoji)

Использование цитирования в тексте

Подсветка кода

Списки

Маркированный

Нумерованный

Смешанные списки

Список задач

Ссылки

Вставка изображения

Дополнительно:

Вставка ссылки с картинкой на ролик с YouTube

Вставка таблиц

Диаграмм Mermaid.js