GnuriaN / Format Readme
Projects that are alternatives of or similar to Format Readme
Описание разметки файла README.md
Для описания проектов на GitHub используется README.md, который пишется на языке разметки markdown. Что и как поддерживается расписано ниже. Также существует еще один формат - reStructuredText, описание которого вынесено в отдельный файл README.rst.
Оглавление
- Разделительная черта
- Заголовки
- Работа с выделением текста
- Использование эмодзи (emoji)
- Использование цитирования в тексте
- Подсветка кода
- Списки
- Ссылки
- Вставка изображения
- Вставка таблиц
- Дополнения
Разделительная черта
При использовании
____
получается разделительная черта
Заголовки
Всего существует шесть уровней заголовков. Для того, чтобы создать заголовок, необходимо в начале строки добавить символы #, в количестве равном его уровню.
Заголовок первого уровня
# Заголовок 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) пробела для того, что бы был переход на новую строку):
✅ Это уже сделано
❎ Я не буду это делать
🔲 делать или не делать, вот в чем вопрос?
Список работающих Эмодзи находится тут -> 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.
- Уровень списка 2. Пункт 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
- Седьмой уровень "маркер"
- Седьмой уровень "нумерованный" - 2
- Седьмой уровень "нумерованный" - 3
- Восьмой уровень "нумерованный" - 1
- Шестой уровень "нумерованный" - 1
- Пятый уровень "нумерованный" - 1
- Четвертый уровень "нумерованный" - 1
- Второй уровень "маркер"
- Первый уровень "нумерованный" - 2
- Первый уровень "маркерный" - 3
- Первый уровень "нумерованный" - 4 (хотя по идее должен быть 3)
- Первый уровень "нумерованный" - 5 (хотя, по идее должен быть 3)
Список задач
(Task List)
Можно создавать "Списки задач" для этого необходимо использовать - [ ] для поставленной задачи и - [X] для выполненной задачи.
- [X] Придумать внешний вид резюме
- [ ] Написать основные категории
- [X] Опубликовать
- [X] Придумать внешний вид резюме
- [ ] Написать основные категории
- [X] Опубликовать
Также можно создавать многоуровневые списки задач. Каждый уровень отделяется четырьмя (4) пробелами:
- [X] Задача 1
- [X] Подзадача 1 для Задачи 1
- [X] Подзадача 2 для Задачи 1
- [ ] Задача 2
- [X] Подзадача 1 для Задачи 2
- [ ] Подзадача 2 для Задачи 2
- [ ] Задача 3
- [ ] Подзадача 1 для Задачи 3
- [ ] Подзадача 1 для Подзадача 1 для Задачи 3
- [X] Задача 1
- [X] Подзадача 1 для Задачи 1
- [X] Подзадача 2 для Задачи 1
- [ ] Задача 2
- [X] Подзадача 1 для Задачи 2
- [ ] Подзадача 2 для Задачи 2
- [ ] Задача 3
- [ ] Подзадача 1 для Задачи 3
- [ ] Подзадача 1 для Подзадача 1 для Задачи 3
- [ ] Подзадача 1 для Задачи 3
Ссылки
Либо просто вставить ссылку, либо дополнительно задать текст ссылки (пробела между скобками быть не должно):
Первый вариант вставки ссылок - это просто написать адрес сайта http://sabaka.net
Первый вариант вставки ссылок - это просто написать адрес сайта http://sabaka.net
Второй вариант записывается так: [текст ссылки](адрес ссылки)
[sabaka.net](http://sabaka.net)
Вставка изображения
Дополнительно:
Вставка ссылки с картинкой на ролик с YouTube
Описание комбинации [](ссылка на страничку YouTube)
Пример:
[](https://youtu.be/RHPYGwVQB2o)
Что мы увидим:
Вставка таблиц
| LEFT | CENTER | RIGHT |
|----------------|:---------:|----------------:|
| По левому краю | По центру | По правому краю |
| текст | текст | текст |
| LEFT | CENTER | RIGHT |
|---|---|---|
| По левому краю | По центру | По правому краю |
| текст | текст | текст |
Внимание: Если в тексте таблицы нужно использовать символ "вертикальная черта - |", то в место него необходимо написать замену на комбинацию HTML-кода* |, это нужно для того, что бы таблица не потеряла ориентации.
*) - Можно использовать ASCII и/или UTF коды.
Пример:
| Обозначение | Описание | Пример регулярного выражения|
|----:|:----:|:----------|
| literal | Строка содержит символьный литерал literal | foo |
| re1|re2 | Строка содержит регулярные выражения `rel` или `re2` | foo|bar |
Результат:
| Обозначение | Описание | Пример регулярного выражения |
|---|---|---|
| literal | Строка содержит символьный литерал literal | foo |
| re1|re2 | Строка содержит регулярные выражения rel или re2
|
foo|bar |