# Язык разметки Markdown 2022-07-10 #sheka #index **MarkDown** - облегченный язык разметки. Он легко конвертируется в другие языки разметки. К примеру, в html, что позволяет отображать документы как веб-страницы. Безусловно, html несравнимо функциональнее и богаче, однако маркдаун намного проще: его легко писать и читать в плоском ("голом", неформатированном) виде в любом блокноте. Знание и использование маркдаун позволяет грамотно оформить документ; внести в него фундаментальный функционал: вставка иллюстраций, ссылок, заголовков, формул и т.д. Маркдаун не имеет какого-то жесткого стандарта. Самым распространенным является стандарт CommonMark, однако функционал нашей реализации несколько расширен. # Абзацы Абзацы отделяются друг от друга одной и более пустой строкой. Простой перенос строки обозначается двумя и более пробелами в конце строки. ``` Абзацы отделяются друг от друга одной и более пустой строкой. Простой перенос__ строки__ обозначается двумя и более пробелами в конце строки. Где (_) означает пробел ``` # Заголовок ## Заголовок 2 ### Заголовок 3 #### Заголовок 4 ##### Заголовок 5 ###### Заголовок 6 Комментировать важность этого элемента излишне. Он обозначается символом `#`, чье количество определяет уровень заголовка (1-6). Сам заголовок и решетки должны быть **отделены минимум одним пробелом**. # Заголовок ## Заголовок 2 ### Заголовок 3 #### Заголовок 4 ##### Заголовок 5 ###### Заголовок 6 Заголовки первого и второго уровня можно обозначать и таким образом: Заголовок 1 =========== Заголовок 2 ----------- В целях эстетики можно закрывать заголовок решетками с другой стороны. Количество "закрывающих" решеток может быть любым, но после них **не должно стоять других символов**. К примеру, так: ### Заголовок 3 ### # Ссылка и изображение Ссылки бывают относительными и абсолютными. **Абсолютная** ссылка начинается с указания протокола `http://` и нужна для указания любого адреса в Интернете. **Относительная** ссылка указывается относительно текущей директории и нужна для указания на локальный файл. Синтаксис: [текст ссылки](адрес_ссылки) `[текст ссылки](адрес_ссылки)` Абсолютная: [example](http://example.com) `[example](http://example.com)` Относительная: [readme](README.md) `[readme](README.md)` Так же можно указывать адрес ссылки в каком-нибудь другом месте: [ссылка 1][ярлык] Если текст ссылки совпадает с названием ярлыка, можно обойтись одним ярлыком: [ссылка2] Так же можно указывать адрес ссылки после её обозначения: [ссылка][ярлык] . . . [ярлык]: example.com [ссылка2]: test.com Для вставки изображений используется похожая конструкция: `` Альтернативное содержание отображается в случае, если изображение по какой-то причине окажется недоступно. Оно необязательно и обычно не пишется. Адрес изображения можно указать после объявления так же, как в случае ссылки.  Кавказские горы ![закат] Закат в Краснодарском крае  Кавказские горы ![закат] Закат в Краснодарском крае . . . [закат]: img/sunset.png [ярлык]: example.com [ссылка2]: test.com [img]: img/caucasian-mountains-with-clouds.jpg [закат]: img/sunset.png # Горизонтальная линия Для разделения блоков текста в маркдаун для этого используется... *** ...горизонтальная линия, которая обозначается стоящими в начале строки тремя и более звездочками `***` В маркдаун для этого используется горизонтальная линия... *** ...горизонтальная линия. Точно так же можно использовать три и более символа дефис `---` В маркдаун для этого используется горизонтальная линия... ------------ ...горизонтальная линия. # Блочная цитата Цитаты обозначаются знаком угловой скобки `>` и отделяются друг от друга так же, как абзацы. Цитаты так же можно вкладывать (поэтому они и называются блочными). > Цитата 1 > Всё ещё цитата 1 > > Цитата внутри цитаты > Цитата 2 > Цитата 1 > Всё ещё цитата 1 > > Цитата внутри цитаты > Цитата 2 # Список Списки бывают **маркированные** и **нумерованных**. Для **немаркированных** рекомендуется использовать знак дефис `-` (хотя так же есть `+` и `*`). - Первый элемент - Второй элемент - Первый от второго элемент - Первый от первого от второго элемент - Третий элемент ``` - Первый элемент - Второй элемент - Первый от второго элемент - Первый от первого от второго элемент - Третий элемент ``` Для **нумерованных** ставиться цифра с точкой `1.` Нумеровать можно совершенно любыми числами, однако первое число в списке задаёт, с какого числа идёт нумерация. Вложенные списки начинать необходимо с единицы. 1. Первый элемент (список начинается с тройки) 2. Второй элемент 1. Первый от второго элемент 1. Первый от первого от второго элемент 3. Третий элемент ``` 3. Первый элемент (список начинается с тройки) 15. Второй элемент 1. Первый от второго элемент 1. Первый от первого от второго элемент 5. Третий элемент ``` Важно! Маркер должен отделяться от содержимого как **минимум одним** пробелом. Список считается вложенным, только если его маркер стоит за маркером элемента выше.  # Код Зачастую стоит задача вставить перформатированный (плоский) текст, который следует отображать моноширенным шрифтом и не интерпретировать ничего внутри ни как html-теги, ни как md-разметку. Существует два типа кода: строчный и блочный. Строчный `<код>` оборачивается в . Строчный `<код>` выглядит так. Блочный код можно обозначить код табуляцией или четырьмя пробелами. Блочный код можно обозначить... А теперь идёт код или плоский текст. Здесь используется табуляция или отступ в 4 пробела. Так же код может... Так же код может обозначается помощи трех обратных кавычек ``` с новой строки. После открывающих кавычек _можно_ указать (без пробела) язык разметки. Это опционально и применяется только для подсветки синтаксиса. ```language Непосредственно код или плоский текст. ``` # Форматирование - ~~зачеркнутый:~~ `~~зачеркнутый~~` - _наклонный:_ `_наклонный_` или `*наклонный*` - **жирный:** `__жирный__` или `**жирный**` - **_комби:_** `**_комби_**`, `***комби***` etc. - А так нельзя: `*__тарабарщина_**`, `*тарабарщина_` # Таблица | Left-aligned | Center-aligned | Right-aligned | | --- | :------------: | -----------: | | git status | git status | git status | | git diff | git diff | git diff | Таблица состоит из ячеек, разделенных вертикальными чертами `|`. Каждая строка содержит один ряд. Соответственно, переносить строку внутри можно только через html-тег `
`. Первым рядом всегда идет заголовок, за которым ряд, каждая ячейка которого содержит не менее трёх тире `-`. Если на конец разделителя добавить двоеточие `:` так `---:`, то все содержимое ячейки будет выровнено по правому краю. Аналогично, если поставить двоеточия с обоих концов (`:---:`), выравнивание будет по центру. Хотя двоеточие в начале разделителя (`:---`) грамматически правильно, оно не имеет смысла. ``` | Left-aligned | Center-aligned | Right-aligned | | --- | :------------: | ------------: | | git status | git status | git status | | git diff | git diff | git diff | ``` К сожалению, таблицы маркдаун крайне топорны и подходят лишь под самые простые задачи. Для чего-то более сложного следует использовать html-таблицы. # LaTeX В маркдаун для написания формул используется LaTeX-синтаксис. Формулы делятся на строчные и блочные. Строчная формула $(a+b)^2 = a^2 + b^2$ оборачивается в одинарные знаки доллара `$` вот так: `$(a+b)^2 = a^2 + b^2$`. Блочная формула оборачивается в двойные знаки доллара `$$`. Важно! Блочная формула должна являться одним абзацем. Чтобы нумеровать формулу, используйте `\tag{}` $$ f(x) = \int_{-\infty}^\infty f(\hat\xi)\,e^{2 \pi i \xi x} \,d\xi $$ $$\tag{2.3} x+y^{2x}$$ $$ f(x) = \int_{-\infty}^\infty f(\hat\xi)\,e^{2 \pi i \xi x} \,d\xi $$ $$\tag{2.3} x+y^{2x}$$ # Иные соглашения Здесь указаны не относящиеся к маркдаун, но все же важные рекомендации. Будет проще понять друг друга, если мы будем придерживаться одних и тех же правил написания. Как минимум, соблюдение этих рекомендаций есть проявление хорошего тона. ---------- Названия фалов должны быть написаны на латинице в нижнем регистре с цифрами. Все **пробелы** заменяются символами дефис `-` Использование символа нижнего подчёркивания `_` допускается, но **не рекомендуется**. Использование других символов не допускается. Именовать файлы следует на **английском языке**. Калька с **русского** допускается, но **настоятельно не рекомендуется**. Если загружается вложение, его имя следует изменить на соответствующее стандарту. В случае, если обеспечить уникальность имени файла трудно, то лучше добавить в начало дату его создания, а не прибегать к абстрактным пометкам. Правильно: variety-of-life.md 2022-07-10-mechanobiotes.md maxwell-equation.md Неправильно: raznoobrazie_zhizni.md Machanobiotes_3-pochti_gotovo.md Uravnenija_Maxvella.md Недопустимо: Разнообразие жизни.md механобиоты готово на 95%.md уравнения Максвелла.md Названия файлов должны быть ёмкими и однозначными. Помните, что это - лицо документа! Название файла даже важнее заголовка, потому что именно на название будут ссылаться другие документы; именно по названию вы ищите документ среди всех прочих. ---------- В начале документа, первой же строкой, следует писать название документа в форме **заголовка первого уровня**. Второй строкой идут метаданные (дата и хэштеги), вторым абзацем - аннотация. ---------- Хорошим тоном будет писать дату публикации в формате `yyyy-mm-dd` в начале документа _(время последнего редактирования и так известна из метаданных файла)_ (к примеру: `2022-07-10`). Такой формат записи даты на американский манер разнится с принятым в СНГ `dd.mm.yyyy` (к примеру: `10.07.2022`). Однако данный формат - негласный стандарт в IT-среде. ---------- Хэштег - это слово, начинающееся с решетки _(hash)_ `#`. Хэштеги в официальных документах называются _ключевыми словами_. Они предназначены для поиска документов по выбранной тематике. Планировать новые хэштеги бесполезно: добавлять новые следует по мере использования. Отдельно отметим, что хэштег обозначает _глобальную тему документа._ И, разумеется, следует пользоваться существующими тегами, если это возможно. Не рекомендуется выставлять больше 5-6 хэштегов. Хотя, разумеется, могут быть ситуации, когда и большее их количество оправдано. Если тег состоит из нескольких слов, пробелом должен выступать символ нижнего подчеркивания `_` в соответствии с общей практикой использования хэштегов. Заглавные буквы в тегах не используются. > К примеру: `#кулинария` `#черное_море` `#ewewe` ---------- Первым хэштегом следует указывать автора документа. Имя автора пишется латиницей с маленькой буквы, берется только первая часть имени: `Frenck Thompson = #frenck` ---------- Аннотация - краткое описание документа и его содержания. Это 5-10 предложений, один абзац. Аннотация не нужна маленьким документам (`< 3500 символов`). А крупный документ (`>3500 символов`) нужно разбивать на главы. Это существенно упрощает его восприятие.