Skip to content

Разметка

Меню навигации

Меню навигации строится в файле конфигурации ..\mkdocs\mkdocs.yml в разделе nav. Для добавления нового пункта меню, в раздел nav необходимо добавить строку вида: 

nav:
    - Наименование пункта меню(статьи): <путь_до_файла_статьи/файл_статьи.md>

далее по такому принципу: "один пункт меню" = "один файл статьи" строится всё меню.

Пример

структура файла mkdocs.yml mkdocs.yml

Результирующий вид меню:

mkdocs.yml

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

    - Наименование раздела:

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

nav:
    - Раздел 1:
        - Статья 1: <путь_до_файла_статьи_1>
        - Статья 2: <путь_до_файла_статьи_2>
        - Подраздел 1: <путь_до_файла_подраздел_1>
            - Статья 3: <путь_до_файла_статьи_3>

Пример

структура файла mkdocs.yml

Результирующий вид меню:

mkdocs.yml

Базовое форматирование текста

Markdown включает в себя следующие элементы:

  1. Блочные элементы

  2. Параграфы и разрывы строк;

  3. Заголовки;
  4. Цитаты;
  5. Списки
  6. Блоки кода;

  7. Горизонтальные (разделительные) линии.

  8. Строчные элементы

  9. Ссылки;

  10. Выделение текста;
  11. Таблицы.
  12. Изображения.

Блочные элементы

Параграфы и разрывы строк

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

Заголовки

Язык разметки Markdown поддерживает 2 стиля обозначения заголовков:

  • выделение символом («#»).
    При выделении заголовков с помощью символа («#») используется от одного до шести данных символов, которые устанавливаются в начале строки (перед заголовком). В данном случае количество символов соответствует уровню заголовка. 

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

    Результат

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

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

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

  • Выделение заголовков с помощью подчеркивания производится знаками равенства («=») в случае, если заголовок первого уровня, и дефисами («-») в случае, если заголовок второго уровня. Количество знаков подчеркивания не ограничивается.
    Заголовки первого и второго уровней, выполненные с помощью подчеркивания, выглядят следующим образом: 

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

    Результат

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

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

Цитаты

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

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

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

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

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

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

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

Результат:

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

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

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

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

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

Результат:

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

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

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

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

Списки

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

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

Результат:

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

Неупорядоченные списки:

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

или

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

или

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

Результат всех трех вариантов:

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

Также в список можно вставлять цитаты: 

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

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

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

Результат:

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

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

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

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

Результат:

  1. Элемент списка, содержащий исходный код 
        <исходный_код>
  2. Элемент списка
Блоки кода

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

Примечание

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

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

    `<текст_кода>`
    или
    ```
        <текст_кода>
    ```

Результат:

<текст_кода>
или

    <текст_кода>

Горизонтальные линии (разделители)

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

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

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

Или

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

---

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

Результат:

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

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

Примечание

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

Строчные элементы

Ссылки
  [пример](http://example.com/ "Необязательная подсказка")

Результат:

пример

Примечание

При ссылке на локальную директорию возможно использование относительного пути (от текущей страницы, сайта и т.п.)

Для создания ссылки-якоря на какую-то часть текста внутри статьи потребуется воспользоваться HTML.

На примере текущей статьи, сделаем ссылку на заголовок "Базовое форматирование текста":
В тексте куда необходимо сослаться создаем "якорь" в HTML-формате 

    <a name="BaseFormat"></a>Базовое форматирование текста

И далее, там где необходимо, можем ссылаться на это место 

    [Ссылка на "Базовое форматирование текста"](#BaseFormat);
    или
    [Ссылка на "Базовое форматирование текста"](../help/#BaseFormat);
    или
    [Ссылка на "Базовое форматирование текста"](https://docs.ks-sakh.ru/help/#BaseFormat]

Результат:

Ссылка на "Базовое форматирование текста";

Выделение текста
Стиль Синтаксис Пример Результат
Жирный ** ** или __ __ **Этот текст жирный** Этот текст жирный
Курсив * * или _ _ *Этот текст курсивный* Этот текст курсивный
Зачеркнутый ~~ ~~ ~~Этот текст зачеркнутый~~ Этот текст зачеркнутый
Жирный и Курсив ** ** и _ _ **Этот _текст смешаный_** Этот текст смешаный

Внимание

К сожалению mkdocs не распознает синтаксис для зачеркнутого текста и markdown не имеет синтаксиса для подчеркивания текста.
Это можно обойти посредством пары html-тегов:

Стиль Синтаксис Пример Результат
Зачеркнутый <del></del> <del>Этот текст жирный</del> Этот текст зачеркнутый
Подчеркнутый <ins></ins> <ins>Этот текст курсивный</ins> Этот текст подчеркнутый
Таблицы

Чтобы создать таблицу, как в предыдущем подразделе статьи, достаточно воспользоваться символом |, для разделения колонок и -, для выделения загоровка. Эта таблица создана таким образом: 

    Колонка1|Колонка2|Колонка3|Колонка4
    --------|--------|--------|--------
    Текст1|Текст2|Текст3|Текст4
    Текст5|Текст6|Текст7|Текст8
    Текст9|Текст10|Текст11|Текст12

Результат:

Колонка1 Колонка2 Колонка3 Колонка4
Текст1 Текст2 Текст3 Текст4
Текст5 Текст6 Текст7 Текст8
Текст9 Текст10 Текст11 Текст12
Изображения

Вставка изображения производится аналогично ссылкам, только с символом ! вначале.
Сохраняем изображение на сервере или находим на Интернет-ресурсе и указываем ссылку на него:

Для изображения, хранящегося на сервере: 

    ![](/Help/Img/Help_test_image.png)

Для изображения, хранящегося в сети интернет: 

    ![](http://s1.iconbird.com/ico/2013/9/452/w480h5121380477037photo.png)

Результат:

Дополнительные возможности MkDocs

Заметка

Примеры дополнительных возможностей здесь