Модуль «Раздел документации»
626
20.04.2023
#Markdown #Битрикс

Краткое описание Markdown

Markdown - простой язык разметки текста, обычно используемый для дальнейшего преобразования текста в HTML.

Разметка markdown поддерживает базовые HTML-теги для работы с данными: заголовки, абзацы, списки, ссылки, таблицы, изображения, ссылки, цитаты, код и т.д.

Приведём примеры работы с основными тегами.

Абзацы создаются при помощи пустой строки. Если вокруг текста сверху и снизу есть пустые строки, то текст превращается в абзац.

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

Заголовки отмечаются символом решётки # в начале строки, от одного до шести. Например:

# Заголовок h1
## Заголовок h2
### Заголовок h3
#### Заголовок h4
##### Заголовок h5
###### Заголовок h6

Результат:

Заголовок h1

Заголовок h2

Заголовок h3

Заголовок h4

Заголовок h5
Заголовок h6

В декоративных целях заголовки можно «закрывать» с обратной стороны, например:

### Заголовок h3###

Результат:

Заголовок h3

Списки

Для разметки неупорядоченных списков можно использовать или *, или -, или +, после символа обязательно должен быть пробел, для запрета символ можно экранировать символом \, например так \- пункт меню:

Вложенные пункты создаются четырьмя пробелами перед маркером пункта.

* элемент 1
* элемент 2
    * вложенный элемент 2.1
        * вложенный элемент 2.1.1
        * вложенный элемент 2.1.2
    * вложенный элемент 2.1
    * вложенный элемент 2.2
* элемент 3

Результат:

  • элемент 1
  • элемент 2
    • вложенный элемент 2.1
      • вложенный элемент 2.1.1
      • вложенный элемент 2.1.2
    • вложенный элемент 2.1
    • вложенный элемент 2.2
  • элемент 3

Упорядоченный список:

1. элемент 1
2. элемент 2
    1. вложенный
    2. вложенный
3. элемент 3

Результат:

  1. элемент 1
  2. элемент 2
    1. вложенный
    2. вложенный
  3. элемент 3

На самом деле не важно как в коде пронумерованы пункты, главное, чтобы перед элементом списка стояла цифра (любая) с точкой. Можно сделать и так:

0. элемент 1
0. элемент 2
0. элемент 3
0. элемент 4

Результат:

  1. элемент 1
  2. элемент 2
  3. элемент 3
  4. элемент 4

Список с абзацами:

* Раз абзац. Lorem ipsum dolor sit amet, consectetur adipisicing elit.

* Два абзац. Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

* Три абзац. Ea, quis, alias nobis porro quos laborum minus sed fuga odio dolore natus quas cum enim necessitatibus magni provident non saepe sequi?

    Четыре абзац (Четыре пробела в начале или один tab).

Результат:

  • Раз абзац. Lorem ipsum dolor sit amet, consectetur adipisicing elit.

  • Два абзац. Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

  • Три абзац. Ea, quis, alias nobis porro quos laborum minus sed fuga odio dolore natus quas cum enim necessitatibus magni provident non saepe sequi?

    Четыре абзац (Четыре пробела в начале или один tab).

Цитаты

Цитаты оформляются как в емейлах, с помощью символа >.

> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

Результат:

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

В цитаты можно помещать всё что угодно, в том числе вложенные цитаты:

>
> 1.   This is the first list item.
> 2.   This is the second list item.
>
> > Вложенная цитата.
>
> Here's some example code:
>
>     return shell_exec("echo $input | $markdown_script");

Результат:

  1. This is the first list item.
  2. This is the second list item.

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

Here's some example code:

return shell_exec("echo $input | $markdown_script");

Исходный код

В чистом Маркдауне блоки кода отбиваются 4 пробелами в начале каждой строки.

Но есть более удобный способ: ставим по три апострофа (на букве Ё) до и после кода. Также можно указать язык исходного кода. Внимание! В примере, указанном ниже, вместо трёх апострофов используется два, чтобы в данной документации было возможным показать это визуально.

``html  
<a href="/details/">Подробнее</a>
``

Результат:

<a href="/details/">Подробнее</a>

Самое приятное, что в коде не нужно заменять угловые скобки < > и амперсанд & на их html-сущности.

Инлайн код

Для вставки кода внутри предложений нужно заключать этот код в апострофы (на букве Ё). Пример:

`<html class="ie no-js">`

Результат:

<html class="ie no-js">

Если внутри кода есть апостроф, то код надо обрамить двойными апострофами:

``There is a literal backtick (`) here.``

Результат:

There is a literal backtick (`) here.

Горизонтальная черта

hr создается тремя звездочками или тремя дефисами.

---

Результат:

Ссылки

Ссылки задаются в следующем формате: [Яндекс](https://ya.ru), результат:

Яндекс

Для ссылок можно задавать всплывающую подсказку: [Яндекс](https://ya.ru "Подсказка")

Яндекс

С помощью ссылок можно делать сноски:

А вот [пример][1] [нескольких][2] [ссылок][id] с разметкой как у сносок. Прокатит и [короткая запись][] без указания id.
[1]: http://example.com/ "Optional Title Here"
[2]: http://example.com/some
[id]: http://example.com/links (Optional Title Here)
[короткая запись]: http://example.com/short

Результат:

А вот пример нескольких ссылок с разметкой как у сносок. Прокатит и короткая запись без указания id.

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

Выделение, подчеркивание

Выделять слова можно при помощи *. Одним символ для наклонного текста, два символа для жирного текста, три — для наклонного и жирного одновременно.

Например, это *italic*. А вот так уже **strong**. А так ***жирный и наклонный*** одновременно.

Результат:

Например, это italic. А вот так уже strong. А так жирный и наклонный одновременно.

Зачеркивание

Чтобы зачеркнуть текст используйте две тильды ~~ до и после текста.

~~Зачеркнуто~~

Результат:

Зачеркнуто

Картинки

Картинка без alt текста

![](https://www.1c-bitrix.ru/images/content_ru/products/box/bus.png)

Результат:

Картинка с альтом и тайтлом:

![Битрикс](https://www.1c-bitrix.ru/images/content_ru/products/box/bus.png "Битрикс: Управление сайтом")

Результат:

Битрикс

Запомнить просто: синтаксис как у ссылок, только перед открывающей квадратной скобкой ставится восклицательный знак.

Картинки «сноски»:

![1С-Битрикс: Управление сайтом][bus]
![1С-Битрикс: Интернет-магазин + CRM][im]
![1С-Битрикс: Enterprise][ep]
![Битрикс24][b24]

[bus]: https://www.1c-bitrix.ru/images/content_ru/products/box/bus.png "1С-Битрикс: Управление сайтом"
[im]: https://www.1c-bitrix.ru/images/content_ru/products/box/im.png "1С-Битрикс: Интернет-магазин + CRM"
[ep]: https://www.1c-bitrix.ru/images/content_ru/products/box/ep.png "1С-Битрикс: Enterprise"
[b24]: https://www.1c-bitrix.ru/images/content_ru/products/box/b24.png "Битрикс24"

Результат:

1С-Битрикс: Управление сайтом 1С-Битрикс: Интернет-магазин + CRM 1С-Битрикс: Enterprise Битрикс24

Картинки-ссылки:

[![1С-Битрикс: Управление сайтом](https://www.1c-bitrix.ru/images/content_ru/products/box/bus.png)](https://www.1c-bitrix.ru/)

Результат:

1С-Битрикс: Управление сайтом

Таблицы

Пример формирования таблиц

First Header Second Header
Content Cell Content Cell
Content Cell Content Cell

Для красоты можно и по бокам линии нарисовать:

First Header Second Header
Content Cell Content Cell
Content Cell Content Cell

Можно управлять выравниванием столбцов при помощи двоеточия.

Left-Aligned Center Aligned Right Aligned
col 3 is some wordy text $1600
col 2 is centered $12
zebra stripes are neat $1

Внутри таблиц можно использовать ссылки, наклонный, жирный или зачеркнутый текст.

Использование HTML внутри Markdown

Если возможностей markdown Вам недостаточно, используйте HTML прямо внутри markdown. Mожно смешивать Markdown и HTML. Если на какие-то элементы нужно поставить классы или атрибуты, смело используем HTML:

Например, это <em class="a1">italic</em> и это тоже *italic*. А вот так уже <b>strong</b>, и так тоже <strong>strong</strong>.

Результат:

Например, это italic и это тоже italic. А вот так уже strong, и так тоже strong.

Дополнение от Webdebug: вставка видео из YouTube и RuTube

Конечно, видео можно вставлять через iframe как обычный HTML, но это неудобно.

Мы доработали механизм преобразования, теперь можно указывать видео как ссылки на видео из YouTube и RuTube - в первом случае поддерживаются обычные ссылки, встраиваемые и сокращённые, во втором - обычные и встраиваемые. Дополнительно делать что-то не нужно, всего лишь разместить картинку со ссылкой на видео, например:

![](https://www.youtube.com/watch?v=4XvTRUwFElI)

Результат:

Пример кода:

//open the big XML file
$reader = new XMLReader();
$reader->open('big_file.xml');

//create a SimpleXML object for reading the XML data
$simpleXml = new SimpleXMLElement('<root/>');
$index = 0;

//read the XML data and add it to the SimpleXML object
while($reader->read()){
    if($reader->nodeType == XMLReader::ELEMENT){
        $index = $simpleXml->count();
        $simpleXml->addChild("record{$index}");
        while($reader->moveToNextAttribute()){
            $attributeName = $reader->name;
            $attributeValue = $reader->value;
            $simpleXml->{"record{$index}"}->addAttribute($attributeName, $attributeValue);
        }
    }
    elseif($reader->nodeType == XMLReader::TEXT || $reader->nodeType == XMLReader::CDATA){
        $simpleXml->{"record{$index}"} = $reader->value;
    }
}

//output the results
echo $simpleXml->asXML();

//close the XML file and free up memory
$reader->close();
unset($reader);
unset($simpleXml);

Примеры прикреплённых изображений