Мова розмітки GitHub Flavored Markdown

Markdown – візуально зрозуміла та зручна при редагуванні мова розмітки для оформлення текстових документів. Зазвичай перетворюється на код HTML для відображення інформації в Інтернет. GitHub розширив стандартний Markdown, додавши можливість оформлення таблиць (? лише?). Крім власної розмітки Markdown-текст може містити у собі вставки звичайного HTML-коду.

Зміст

• Типографія
• Заголовки
• Параграфи та розриви рядків
• Лінії (розділювачі)
• Виділення тексту
• Списки
  • unordered
  • ordered
  • definition
  • task
• Цитати
• Виноски
• Посилання
• Зображення
• Спеціальні HTML-символи
• Код

Переделать это:

1. Блочные элементы
   • Блоки кода;
2. Строчные элементы
   • ;
   • Строки кода;
   • Изображения.

GitHub Flavored Markdown Spec

Типография

• This text contains italic text. <i></i>
• This text contains emphasized text. <em></em>
• This text contains bold text. <b></b>
• This text contains strong text. <strong></strong>
• This text contains code text. <code></code> аналог ``
• This text contains samp text. <samp></samp>
• This text contains mark text. <mark></mark>
• This text contains abbr text. <abbr></abbr>
• This text contains kbd text. <kbd></kbd>
• This text contains var text. <var></var>
• This text contains ^superscript text. <sup></sup>
• This text contains _subscript text. <sub></sub>

• This text contains small text. <small></small>

• This text contains <pre></pre> text:

pre

Markdown воспринимает звёздочки «*» и символы подчёркивания «_» как признаки смыслового выделения текста:

This text will be italic *text* This will also be italic _text_

This text will be bold **text** This will also be bold __text__

You can combine them _You **can** combine them_ You can combine them *You __can__ combine them*

Strikethrough ~~Strikethrough~~

edit typography.md top

Заголовки

This is an <h1> tag

Sometimes it’s useful to have different levels of headings to structure your documents. Start lines with a # to create headings. Multiple ## in a row denote smaller heading sizes.

Язык разметки Markdown поддерживает 2 стиля обозначения заголовков: подчеркивание и выделение символом («#»). Выделение заголовков с помощью подчеркивания производится знаками равенства («=») в случае, если заголовок первого уровня, и дефисами («-») в случае, если заголовок второго уровня. Количество знаков подчеркивания не ограничивается. При выделении заголовков с помощью символа («#») используется от одного до шести данных символов, которые устанавливаются в начале строки (перед заголовком). В данном случае количество символов соответствует уровню заголовка. Кроме того, заголовок возможно снабдить закрывающимися символами («#»), хотя это и не является обязательным. Количество закрывающихся символов не обязано соответствовать количеству начальных символов. Уровень заголовка определяется по количеству начальных символов. Заголовки первого и второго уровней, выполненные с помощью подчеркивания, выглядят следующим образом:

# H1
## H2
### H3
#### H4
##### H5
###### H6

Alternatively, for H1 and H2, an underline-ish style:

Alt-H1
======

Alt-H2
------

В результате на экран выводится следующее:

H1

H2

H3

H4

H5

H6

Alternatively, for H1 and H2, an underline-ish style:

Alt-H1

Alt-H2

Heading IDs Many Markdown processors support custom IDs for headings — some Markdown processors automatically add them. Adding custom IDs allows you to link directly to headings and modify them with CSS. To add a custom heading ID, enclose the custom ID in curly braces on the same line as the heading.

### My Great Heading {#custom-id}

The HTML looks like this:

<h3 id="custom-id">My Great Heading</h3>

Linking to Heading IDs You can link to headings with custom IDs in the file by creating a standard link with a number sign (#) followed by the custom heading ID. These are commonly referred to as anchor links.

Markdown HTML Rendered Output Heading IDs Heading IDs Heading IDs Other websites can link to the heading by adding the custom heading ID to the full URL of the webpage (e.g, Heading IDs).

edit headers.md top

Параграфи та розриви рядків

Для того, чтобы создать параграф с использованием синтаксиса языка Markdown, достаточно отделить строки текста одной (или более) пустой строкой (пустой считается всякая строка, которая не содержит в себе ничего, кроме пробелов и символов табуляции). Для того, чтобы вставить видимый перенос строки (элемент <br/>) необходимо окончить строку двумя пробелами и нажатием клавиши «Enter». Многие элементы синтаксиса Markdown выглядят и работают гораздо лучше в случае, когда их форматируют с помощью «жесткого перевода строк» (разделение строк, осуществленное самим пользователем, а не программой автоматически). К таким элементам относятся цитаты, списки и пр.

edit paragraphs.md top

Лінії (розділювачі)

Для того чтобы создать горизонтальную линию необходимо поместить три (или более) дефиса --- или знака подчеркивания ___ на отдельной строке текста.

Горизонтальные линии в Markdown выглядят следующим образом:

Первая часть текста, который необходимо разделить
___
Вторая часть текста, который необходимо разделить

Или

Первая часть текста, который необходимо разделить

---

Вторая часть текста, который необходимо разделить

В результате на экран выводится следующее:

Первая часть текста, который необходимо разделить

Вторая часть текста, который необходимо разделить

TEST: Между ними возможно располагать пробелы.

При использовании данного инструмента важно помнить, что после первой части текста и перед второй необходимо оставлять пустую строку. Данное правило необходимо соблюдать только при использовании дефисов. Если его не соблюдать, на экран будет выведен заголовок второго уровня и строка обычного текста. При использовании символа звездочки данным правилом можно пренебречь.

(необходимо добавить пустую строку, над и под символами, которыми обозначается линия)

Линия (а такой код не требует добавления пустой строки):

Лайфхак: можно “нарисовать” вот такую толстую бледную линию, расположив две строки символов ` ``` `: (пустой блок кода)

edit lines.md top

Списки

Unordered (до 3 уровней)

• Item 1
• Item 2
  • 2nd level
    • 3rd level

Ordered 1

1. One
2. Two
3. Three

Ordered 2 (только 2 уровня)

1. Item 1
1. Item 2
1. Item 3
   1. Item 1a
   1. Item 2b
   1. Item 3a
   1. Item 4b

1. Item 1
2. Item 2
3. Item 3
   1. Item 1a
   2. Item 2b
   3. Item 3a
   4. Item 4b

Списки

Markdown поддерживает упорядоченные (нумерованные) и неупорядоченные (ненумерованные) списки. Для формирования неупорядоченный списков используются такие маркеры, как звездочки, плюсы и дефисы. Все перечисленные маркеры могут использоваться взаимозаменяемо. Для формирования упорядоченных списков в качестве маркеров используются числа с точкой. Важной особенностью в данном случае является то, что сами номера, с помощью которых формируется список, не важны, так как они не оказывают влияния на выходной HTML код. Как бы ни нумеровал пользователь список, на выходе он в любом случае будет иметь упорядоченный список, начинающийся с единицы (1, 2, 3…). Эту особенность стоит учитывать в том случае, когда необходимо использовать порядковые номера элементов в списке, чтобы они соответствовали номерам, получающимся в HTML. Упорядоченные списки всегда следует начинать с единицы. Маркеры списков обычно начинаются с начала строки, однако они могут быть сдвинуты, но не более чем на 3 пробела. За маркером должен следовать пробел, либо символ табуляции. При необходимости в список можно вставить цитату. В этом случае обозначения цитирования ( «>» ) нужно писать с отступом. Упорядоченные списки выглядят следующим образом:

1. Проводник
2. Полупроводник
3. Диэлектрик

Неупорядоченные списки выглядят следующим образом:

* Проводник
* Полупроводник
* Диэлектрик

Или

- Проводник
- Полупроводник
- Диэлектрик

Или

+ Проводник
+ Полупроводник
+ Диэлектрик

На выходе всех трех перечисленных вариантов имеется один и тот же результат. В результате на экран выводится следующее:

1. Проводник
2. Полупроводник
3. Диэлектрик

и

• Проводник
• Полупроводник
• Диэлектрик

Цитата, вставленная в список, выглядит следующим образом:

1. Элемент списка с цитатой:

    > Это цитата
    > внутри элемента списка.

 2. Второй элемент списка

В результате на экран выводится следующее:

1. Элемент списка с цитатой:

   Это цитата внутри элемента списка.

2. Второй элемент списка

При вставке цитат в элементы списка важно учитывать, что элементы списка должны находиться на одном уровне, а цитаты должны указываться с отступом. В случае, если правило с единым уровнем списка не соблюдается, следующий после цитаты элемент списка будет автоматически нумероваться цифрой «1.». Кроме того, при необходимости в список можно вставить исходный код. В этом случае его нужно писать с двойным отступом – 8 пробелов или 2 символа табуляции.

• Элемент списка, содержащий исходный код

  <исходный код="">

Definition Lists

Some Markdown processors allow you to create definition lists of terms and their corresponding definitions. To create a definition list, type the term on the first line. On the next line, type a colon followed by a space and the definition.

First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term.

The HTML looks like this:

<dl>
  <dt>First Term</dt>
  <dd>This is the definition of the first term.</dd>
  <dt>Second Term</dt>
  <dd>This is one definition of the second term. </dd>
  <dd>This is another definition of the second term.</dd>
</dl>

Task Lists

• @cruad, #refs, links, formatting, and tags supported
• list syntax required (any unordered or ordered list supported)
• this is a complete item
• this is an incomplete item

edit lists.md top

Цитаты

Для обозначения цитат в языке Markdown используется знак «больше» («>»). Его можно вставлять как перед каждой строкой цитаты, так и только перед первой строкой параграфа. Также синтаксис Markdown позволяет создавать вложенные цитаты (цитаты внутри цитат). Для их разметки используются дополнительные уровни знаков цитирования («>»). Цитаты в Markdown могут содержать всевозможные элементы разметки. Цитаты в языке Markdown выглядят следующим образом:

>Это пример цитаты,
>в которой перед каждой строкой
>ставится угловая скобка.

>Это пример цитаты,
в которой угловая скобка
ставится только перед началом нового параграфа.
>Второй параграф.

Вложение цитаты в цитату выглядит следующим образом:

> Первый уровень цитирования
>> Второй уровень цитирования
>>> Третий уровень цитирования
>
>Первый уровень цитирования В результате на экран выводится следующее:

Это пример цитаты, в которой перед каждой строкой ставится угловая скобка.

Это пример цитаты, в которой угловая скобка ставится только перед началом нового параграфа.

Второй параграф.

Вложенная цитата:

Первый уровень цитирования

Второй уровень цитирования

Третий уровень цитирования

Первый уровень цитирования

Уровень цитирования не может превышать 15-й.

edit quotes.md top

Сноски

Сноски позволяют добавлять примечания и ссылки, не загромождая текст документа. Когда вы создаете сноску, в месте добавления ссылки на сноску появляется надстрочный номер со ссылкой. Читатели могут щелкнуть ссылку, чтобы перейти к содержимому сноски внизу страницы.

Чтобы создать ссылку на сноску, добавьте знак вставки и идентификатор в квадратных скобках ([^1]). Идентификаторы могут быть числами или словами, но они не могут содержать пробелы или табуляции. Идентификаторы только соотносят ссылку на сноску с самой сноской — в выводе сноски нумеруются последовательно.

Добавьте сноску, используя еще один знак вставки и номер в квадратных скобках с двоеточием и текстом ([^1]: Моя сноска.). Не обязательно делать сноски в конце документа. Вы можете размещать их где угодно, кроме как внутри других элементов, таких как списки, блок-кавычки и таблицы.

Это простая, корокая сноска[^2] а также длинная[^bignote], состоящая из нескольких строк.

[^2]: Это расшифровка сноски, располагающаяся внизу страницы.

[^bignote]: А эта расшифровка сноски содержит несколько строк и код в себе.

    Сделайте отступ абзацев, чтобы включить их в сноску.

    `{ # здесь код }`

    Добавьте столько абзацев, сколько хотите.

Это будет выглядеть так:

Это простая, корокая сноска¹ а также длинная², состоящая из нескольких строк.

edit footnotes.md top

Посилання

Markdown підтримує спрощений варіант створення посилань для URL-адрес та адрес електронної пошти. Для цього достатньо помістити URL-адресу в кутові дужки: <http://example.com/>. В цьому випадку URL-адреса також стає і текстом гіперпосилання:

<a href="http://example.com/">http://example.com/</a>

Посилання на адреси електронної пошти працюють аналогічно: <address@example.com>

<a href="mailto:address@example.com">address@example.com</a>

Але, зазвичай, html-посилання має відмінні одна від одної частини: URL, текст, та, інколи, випливаючу підказку при наведенні мишкою. Такі посилання оформлюють так:

• Гиперссылка, подобная сноске.

Очевидно, що крім URL-адреси існує ще . текст посилання розміщують у квадратних дужках, після чого йдуть круглі дужки з URL-адресою. Через пробіл від адреси, у лапках, можна прописати підказку, але цей не обов’язково.

[приклад](http://example.com/ "Необов'язкова підказка")

Результат буде виглядати так: приклад

Згенерований HTML-код посилання буде таким:

<a href="http://example.com/" title="Необов'язкова підказка" rel="nofollow">приклад</a>

При посиланні на локальну директорію можливе використання відносного шляху (від поточної сторінки, сайту тощо)

При створенні посилання як виноски замість цільової адреси використовується друга пара квадратних дужок, всередині яких міститься мітка, ідентифікатор посилання (id).

[приклад][id]:

Також можна використовувати пробіл, щоб відокремлювати 2 пари квадратних дужок:

[приклад] [id]:

У цьому випадку можна визначити ідентифікатор у будь-якому місці документа:

[id]: http://example.com/ "Необов'язкова підказка"

В результате на экран выводится следующее: приклад

Ідентифікатори посилань можуть складатися з букв, цифр, пробілів та знаків пунктуації, однак вони не чутливі до регістру. Тобто ці два варіанти еквівалентні:

[текст посилання][a]
[текст посилання][A]

Markdown також дозволяє використовувати неявно виражений ідентифікатор (скорочений). У цьому випадку мітка не наводиться, замість неї текст гіперпосилання використовується і як її ім’я, а друга пара квадратних дужок залишається порожньою.

Наприклад, щоб зробити слово “Example” гіперпосиланням, що веде на сайт http://example.com/, достатньо написати:

[Example][]

і потім визначити гіперпосилання:

[Example]: http://example.com/

В результаті на екран виводиться таке: Example

edit links.md top

Зображення

В Markdown существует 2 способа вставки изображений в документ:

a. С помощью непосредственного указания URL-адреса изображения. Синтаксис данной команды выглядит следующим образом:

![Альтернативный текст](/путь/к/изображению.jpg)

или

![Альтернативный текст](/путь/к/изображению.jpg "Подсказка")

Иными словами, он состоит из следующих элементов:

• восклицательный знак;
• квадратные скобки, в которых указывается альтернативный изображению текст (он станет содержимым атрибута в элементе img);
• круглые скобки, содержащие URL-адрес или относительный путь изображения, а также (необязательно) всплывающую подсказку, заключённуе в двойные или одиночные кавычки.

b. С помощью метки-идентификатора. Синтаксис данной команды записывается следующим образом:

![Альтернативный текст][id]

где «id» — имя определённой метки изображения. Метки изображений определяются при помощи синтаксиса, совершенно идентичного меткам гиперссылок:

[id]: путь/к/изображению "Необязательная подсказка"

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

# ![logo](i/enote_logo.png) E-Note

c помощью html

<h1 style="padding-top:0; border-top:0"><img src="/e-note/i/enote_logo.png" alt="logo" />E-Note</h1>

Важной особенностью является то, что Markdown не позволяет задать размеры изображения (ширину, высоту).

edit images.md top

Блоки кода

Отформатированные блоки кода используются в случае необходимости процитировать исходный код программ или разметки. Для создания блока кода в языке Markdown необходимо каждую строку параграфа начинать с отступа, состоящего из четырех пробелов или одного символа табуляции. Блок кода продолжается до тех пор, пока не встретится строка без отступа (или конец текста). Внутри блока кода амперсанды («&») и угловые скобки («<» и «>») автоматически преобразуются в элементы HTML разметки. Кроме того, следует отметить, что внутри блоков кода обычный синтаксис Markdown не обрабатывается. Блок кода в Markdown выглядит следующим образом:

Это обычный параграф:

Это блок кода

Строки кода

Чтобы отметить фрагмент строки, содержащий код, необходимо окружить его обратными апострофами «`». При использовании кодовых фрагментов строк текст будет отображаться в виде моноширинного шрифта. В отличие от блоков кода, кодовый фрагмент позволяет поместить код внутрь обычного абзаца текста. Кодовый фрагмент строки в языке Markdown выглядит следующим образом:

це теж код

Escaping Pipe Characters in Tables

Fenced Code Blocks

The basic Markdown syntax allows you to create code blocks by indenting lines by four spaces or one tab. If you find that inconvenient, try using fenced code blocks. Depending on your Markdown processor or editor, you’ll use three backticks (```) or three tildes (~~~) on the lines before and after the code block. The best part? You don’t have to indent any lines!

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

The rendered output looks like this:

{ “firstName”: “John”, “lastName”: “Smith”, “age”: 25 }

Syntax Highlighting

Many Markdown processors support syntax highlighting for fenced code blocks. This feature allows you to add color highlighting for whatever language your code was written in. To add syntax highlighting, specify a language next to the backticks before the fenced code block.

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

The rendered output looks like this:

{ “firstName”: “John”, “lastName”: “Smith”, “age”: 25 }

edit code.md top

It’s very easy to make some words bold and other words italic with Markdown. You can even link to Google!

Используйте оператор if ???

Дополнительные элементы

Обратный слеш

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

• \ - обратный слеш
• | - символ “pipe”, который является разделителем ячеек в таблицах (также можно заменить кодом |)
• ` - обратный апостроф
• * - звездочка
• _ - символ подчеркивания
• {} - фигурные скобки
• [] - квадратные скобки
• () - круглые скобки
• # - символ решетки
• + - плюс
• - - минус (дефис)
• . - точка
• ! - восклицательный знак

Специальные HTML-символы

В языке HTML существует два символа ( только), требующих специального рассмотрения: это символы («<») и («&»). Левая угловая скобка используется как начало тэга; амперсанды применяются для обозначения специального символа HTML. Для того чтобы использовать эти символы в их буквальном смысле, необходимо заменить их элементами HTML, а именно < и & соответственно.

При использовании Markdown подобных действий совершать не нужно. Он позволяет использовать эти символы в исходном виде. В случае если амперсанд используется как часть спецсимвола HTML, он останется неизменным. В противном случае Markdown преобразует его в &.

README.md

edit symbols.md top

См. также

• Mastering Markdown
• Markdown Cheatsheet
• https://paulradzkov.com/2014/markdown_cheatsheet/
• https://help.github.com/en/github/writing-on-github/working-with-advanced-formatting
• https://github.com/github/linguist/blob/master/lib/linguist/languages.yml
• emoji / emoji-cheat-sheet