Описание разметки файла 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/

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

GnuriaN/format-README

GnuriaN

Reviews

Repository Details

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

Оглавление

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

Заголовки

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

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

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

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

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

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

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

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

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

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

Списки

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

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

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

Список задач

Ссылки

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

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

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

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

Диаграммы Mermaid.js

More Repositories