Markdown в документации ioBroker
Документация написана на языке разметки Markdown: это язык разметки, выбранный таким образом, чтобы файл оставался читаемым даже без рендеринга. Желающие внести свой вклад в написание статьи могут ознакомиться с процедурой в разделе Напишите статью.
Эта страница состоит из двух частей. Во-первых, что здесь применимо, то есть, особенности данной документации. Затем подробно рассматривается синтаксис Markdown.
Что здесь применимо
Заголовок каждого файла
---
title: "Kurzer Seitentitel"
lastChanged: "08.09.2026"
---
title - это название страницы, lastChanged - дата последнего изменения содержимого в формате TT.MM.JJJJ. Однако название в меню берется не отсюда, а из content.md.
Поле translatedFrom означает: файл был переведен машинным способом и будет перезаписан при следующем запуске перевода. Не редактируйте такие файлы.
Блоки уведомлений
Цветные прямоугольники создаются двумя строками в начале строки:
?> Ein Hinweis. Nützlich, aber nicht dringend.
!> Eine Warnung. Wer sie überliest, macht etwas kaputt.
Используйте с осторожностью. Страница, на которой выделено всё, ничего не выделяет.
Ссылки
Всегда указывайте простой путь от корня документации, а не относительно файла:
| Цель | Обозначение |
|---|---|
| Страница документации | §§LLLLL_0§§ |
| Страница адаптера | §§LLLLL_0§§ |
| Список адаптеров | §§LLLLL_0§§ |
| Статистика | §§LLLLL_0§§ |
| Статистика | [Статистика](/статистика) |
Всегда используйте ссылки с полным путем, даже в пределах одной страницы. Они работают только до третьего уровня заголовка: ссылка #### не получает идентификатора и не может быть использована в качестве ссылки.
Фотографии
Изображения находятся в папке media рядом со страницей, и доступ к ним осуществляется оттуда:

Текст в квадратных скобках не является декоративным: он отображается там, где изображение не может быть загружено, и будет зачитан вслух. Если изображение должно быть уже текстовой области, этого можно добиться, указав ширину:
<img src="/ru/community/media/dateiname.png" alt="Kurze Beschreibung" width="630" />
Что может делать рендерер
Помимо оригинального синтаксиса Markdown, доступны следующие варианты:
- Таблицы в нотации GitHub (
| столбец | столбец |) - Блоки кода с тремя обратными кавычками, с указанием языка для раскрашивания.
- Зачеркнутый текст с
~~двумя тильдами~~ - Встроенный HTML, для случаев, которые не охватывает Markdown.
Обозначения
- Перенос строки после 80 символов.
- Каждый документ начинается с заголовка первого уровня, и только с одного заголовка.
- Используйте знак минус в качестве тире, а не длинное тире.
- Технические термины сохранены в оригинале:
state,role,level,string. Всем, кто ищет...
level. выполняет поиск, но не находит «Шаги».
- Имена файлов короткие, содержат только символы
a-z,0-9,_и..
Полные технические характеристики изложены в Руководство по стилю.
Подробное описание синтаксиса Markdown
Следующий раздел представляет собой перевод оригинального описания синтаксиса Джона Грубера; исходный код и лицензия указаны в конце страницы. В нем описывается Markdown 1.0.1, поэтому он не включает таблицы или блоки кода с обратными кавычками; однако и то, и другое присутствует здесь, как упоминалось выше.
О происхождении этого описания
Философия
При разработке Markdown основной идеей было обеспечение максимальной простоты чтения и написания текста.
Главная цель здесь - читаемость. Документ, отформатированный в Markdown, должен публиковаться в своем базовом виде, не создавая впечатления, что он содержит теги или команды форматирования (как это происходит с HTML).
Таким образом, синтаксис Markdown состоит только из символов, тщательно подобранных таким образом, чтобы их внешний вид соответствовал их значению. Например, звездочки вокруг слова выглядят как выделение. Списки в Markdown выглядят как списки. Даже блоки цитат выглядят как цитируемые фрагменты текста, как в электронных письмах.
Встроенный HTML
Синтаксис Markdown предназначен для одной цели: написание текстов для веб-сайтов.
Markdown не заменяет HTML, даже близко. Его синтаксис очень прост, представляя собой лишь малую часть всех HTML-тегов. Markdown не предназначен для упрощения вставки HTML-тегов; HTML и так достаточно прост. Идея Markdown заключается в том, чтобы сделать текст максимально удобным для чтения, написания и редактирования. HTML - это формат для публикации; Markdown - это формат для написания. Поэтому его синтаксис учитывает только контент, который может быть передан в виде простого текста.
Для форматирования, которое невозможно выполнить с помощью Markdown, можно просто использовать HTML. Нет необходимости размечать HTML, чтобы отличить его от остального.
Он просто вписывается в текст.
Единственное ограничение касается блочных элементов, таких как <div>, <table>, <pre>, <p> и так далее. Они должны быть отделены от окружающего содержимого пустыми строками, а начальный и конечный теги не должны быть отступлены пробелами или табуляцией. Markdown достаточно интеллектуален, чтобы не добавлять лишние (нежелательные) теги <p> вокруг HTML-блоков.
Вот как, например, встроить HTML-таблицу в статью, размещённую в формате Markdown:
Это обычный абзац.
| Foo |
Это по-прежнему обычный абзац.
Следует отметить, что синтаксис Markdown не интерпретируется внутри HTML-блоков. Например, выделение нельзя использовать внутри HTML-блоков.
Встроенные HTML-теги, такие как <span>, <cite> или <del>, можно использовать в любом месте абзаца, элемента списка или заголовка Markdown.
HTML-теги можно даже использовать вместо соответствующего форматирования Markdown. Вполне допустимо использовать <a> или <img> вместо синтаксиса Markdown для ссылок или графики.
В отличие от блочных тегов, синтаксис Markdown интерпретируется внутри строчных тегов.
Автоматическое маскирование специальных символов
В HTML есть два символа, требующие специальной обработки: < и &.
Левая угловая скобка используется для открытия HTML-тегов, а амперсанд (&) используется для описания именованных символов (сущностей). Если эти символы должны использоваться «сами по себе» в HTML-документах, их необходимо экранировать как сущности, т.е. как < и &.
Амперсанд (&) особенно неудобен для веб-разработчиков. Если вы хотите написать о "AT&T", вам нужно написать "AT&T". Амперсанд даже в URL-адресах необходимо экранировать. (В ссылке на страницу...)
http://images.google.com/images?num=30&q=larry+bird
URL-адрес должен быть закодирован следующим образом:
http://images.google.com/images?num=30&q=larry+bird
Об этом легко забыть, и это, пожалуй, самая распространенная ошибка при проверке корректно сформированных HTML-документов.
Markdown позволяет использовать эти символы обычным способом. Он сам обрабатывает кодировку. Если в сущности используется амперсанд, он не кодируется; в противном случае он преобразуется в &.
Например, если вы хотите ввести символ авторского права, вы можете просто...
©
Напишите это, и Markdown это не изменит. Но из
AT&T
будет Markdown
AT&T
Поскольку Markdown поддерживает встроенный HTML, угловые скобки обрабатываются как обычный HTML в соответствующем случае. Только в таких случаях, как...
4 < 5
будет Markdown
4 < 5
Сделайте следующее. В блоках кода или тега угловые скобки и амперсанд всегда кодируются. Это упрощает написание HTML-кода в Markdown (в отличие от чистого HTML, где кодирование каждого < и & обычно представляет собой кошмар).
Элементы блоков
Абзацы и переносы строк
Абзац состоит из одной или нескольких строк текста, разделённых одной или несколькими пустыми строками. (Пустая строка - это любая строка, которая выглядит как пустая строка; строка, содержащая только пробелы и табуляцию, считается пустой.) Обычные абзацы не должны иметь отступов с использованием пробелов или табуляции.
Правило «одна или более строк» подразумевает одно: Markdown поддерживает абзацы с «жесткими разрывами». Это существенное отличие от большинства других форматировщиков текста в HTML (включая опцию «Преобразовать разрывы строк» в Movable Type), которые форматируют каждый разрыв строки в абзаце как <br />.
Если вы хотите использовать <br /> в качестве переноса строки, вы можете просто закончить строку двумя или более пробелами.
Хотя это небольшое дополнительное усилие для генерации <br />, простое правило «каждый перенос строки - это <br />» не сработало бы в Markdown.
В Markdown формат Цитаты и [список записей]](#listen), напоминающий электронные письма и содержащий несколько абзацев, лучше всего работает и выглядит лучше при использовании переносов строк.
Заголовки
В данном случае Markdown поддерживает только один тип форматирования заголовков: ATX.
Заголовки в стиле ATX используют от 1 до 6 символов решетки в начале строки, соответствующих уровням 1-6. Например:
# Dies ist ein H1
## Dies ist ein H2
###### Dies ist ein H6
Кавычки
В Markdown, как и в электронной почте, для цитирования используется символ >. Если у вас есть опыт работы с цитатами в электронных письмах, вы также знаете, как создавать цитаты в Markdown. Лучше всего это выглядит, если переносить текст на каждую строку и добавлять > перед каждой строкой:
> Dies ist ein Zitat mit zwei Absätzen. Lorem ipsum dolor sit amet, > consectetuer adipiscing elit. Aliquam hendrerit mi posuere > lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet > vitae, risus. > > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. > Suspendisse id sem consectetuer libero luctus adipiscing.
Markdown также позволяет вам полениться и использовать > только на первой строке абзаца с прямым переносом строки:
> Dies ist ein Zitat mit zwei Absätzen. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.
Цитаты могут быть вложенными (т.е. цитата внутри цитаты) с помощью дополнительных >:
> Dies ist die erste Zitat-Ebene. > > > Dies ist ein verschachteltes Zitat. > > Zurück auf der ersten Ebene.
В цитатах могут содержаться другие элементы Markdown, включая заголовки, списки и блоки кода:
Это заголовок.
- Это первый элемент списка.
- Это второй элемент списка.
Вот пример кода: > > return shell_exec("echo $input | $Markdown_script");
Любой приличный текстовый редактор должен упрощать цитирование в стиле электронных писем. Например, в BBEdit вы можете выделить фрагмент текста, выбрать Text из меню §§SSSS_0§§, а затем выбрать Increase Quote Level.
Слушать
Markdown поддерживает отсортированные (нумерованные) и неотсортированные списки (перечисления).
В несортированных списках в качестве маркеров используются звездочки, знаки плюса и тире - взаимозаменяемые:
* Красный
* Зеленый
* Синий
всё то же самое:
- Красный + Зеленый + Синий
И:
- Красный
- Зеленый
- Синий
В отсортированных списках за цифрами следует точка:
- Собака
- Кот
- Мышь
Важно понимать, что сами числа никак не влияют на вывод Markdown. Markdown генерирует следующий HTML-код из последнего списка:
- Собака
- Кошка
- Мышь
Если же вы составите список следующим образом:
- Собака
- Кот
- Мышь
Или даже:
3-я собака
- Кот
- Мышь
Каждый раз генерируется один и тот же список. При желании вы можете правильно пронумеровать свои списки вручную. Но если вам лень, вы можете просто использовать один и тот же номер каждый раз.
Однако список всё же следует начинать с номера 1. В будущем Markdown может добавить возможность указания начального номера для первого элемента списка.
Элементы списка обычно начинаются с левого поля документа, но могут иметь отступ до трех пробелов вправо.
Маркеры списка должны быть отделены от последующего текста одним или несколькими пробелами или табуляцией.
Для более удобного форматирования списков отдельные записи можно дополнительно отодвинуть, как показано здесь:
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit miposere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
* Donec сидеть amet nisl. Aliquam semper ipsum сидит амет велит.
Suspendisse id sem consectetuer libero luctus adipiscing.
Следующий пример генерирует тот же код, но он менее чистый:
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit miposere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
* Donec сидеть amet nisl. Aliquam semper ipsum сидит амет велит.
Suspendisse id sem consectetuer libero luctus adipiscing.
Если элементы списка разделены пустыми строками, Markdown заключит их в <p> и </p>.
Например, это позволит:
- Варштайнер
- Король
к
- Варштайнер
- Король
Но вот что:
-
Варштайнер
-
Король
будет
Варштайнер
Король
Элементы списка могут состоять из нескольких абзацев. Каждый последующий абзац в элементе списка должен иметь отступ не менее четырех пробелов или символа табуляции:
- Это элемент списка, состоящий из двух абзацев. Лорем ipsum dolor
сидите с уважением, consectetuer adipiscing elit. Aliquam hendrerit miposere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus. Donec сидеть амет нисл. Aliquam semper ipsum сидит амет велит.
2. Suspendisse id sem consectetuer libero luctus adipiscing.
Хорошо бы смотрелось, если бы каждая строка следующего абзаца была с отступом, но, опять же, Markdown позволяет ленивому человеку сделать отступ только для первой строки:
- Это пункт списка, состоящий из двух абзацев.
Это второй абзац в этом пункте списка. Отступ нужно сделать только для первой строки. Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
- Еще один пункт в том же списке.
Чтобы использовать цитату в элементе списка, цитата должна быть с отступом:
- Пункт списка, содержащий цитату:
Это цитата в списке.
Чтобы использовать блок кода внутри элемента списка, его необходимо отступить дважды - на 8 пробелов или две табуляции:
- Элемент списка с примером кода:
<Вставьте код здесь>
Возможно непреднамеренное создание списков, например, путем написания следующего кода:
1986 год. Какой замечательный год.
Другими словами: последовательность число-точка-пробел в начале строки. Чтобы избежать этой проблемы, точку можно экранировать обратной косой чертой:
1986 год. Какой замечательный год.
Блоки кода
Предварительно отформатированные блоки кода используются для перезаписи исходного кода программы или разметки. Вместо формирования обычных абзацев, строки внутри блока кода интерпретируются так, как они находятся. Markdown включает блоки кода с тегами <pre> и <code>.
Чтобы создать блок кода в Markdown, просто сделайте отступ в каждой строке блока не менее чем на четыре пробела или табуляцию. Например, из следующего входного файла...
Это обычный абзац.
Это блок кода.
...Markdown делает следующее:
Это обычный абзац.
Это блок кода.
Из каждой строки отступа удаляется один уровень - 4 пробела или 1 табуляция. Например...
Пример на AppleScript:
сообщить приложению "Foo" звуковой сигнал конец сообщить
...становится
Пример на AppleScript:
tell application "Foo" beep end tell
Блок кода заканчивается на первой строке без отступа (или в конце документа).
Внутри блока кода амперсанд (&) и угловые скобки (< и >) автоматически преобразуются в HTML-сущности. Это значительно упрощает добавление HTML-фрагментов - достаточно скопировать HTML-код в документ, сделать отступ, и Markdown позаботится о кодировании амперсанда и угловых скобок. Например:
становится:
<div class="footer"> © 2004 Foo Corporation </div>
Обычный синтаксис Markdown не обрабатывается внутри блоков кода. Это означает, что звёздочки - это просто звёздочки внутри блока кода и не указывают на подсветку текста. Следствием этого является то, что легко говорить о Markdown внутри самого Markdown.
Горизонтальные строки Тег для горизонтальных строк (<hr />) можно создать, написав 3 или более дефисов или звездочек в одной строке. Пробелы между символами также допускаются. Все приведенные ниже примеры создадут горизонтальную строку:
* * *
***
*****
- - -
---------------------------------------
Элементы Span
Ссылки
Markdown поддерживает два типа ссылок: встроенные и ссылки.
В обоих стилях текст ссылки помечен [квадратными скобками].
Чтобы создать встроенную ссылку, напишите обычные круглые скобки сразу после закрывающей квадратной скобки. Внутри этих скобок укажите URL-адрес, на который вы хотите сослаться, а также необязательно заголовок ссылки в кавычках. Примеры:
Это пример для встроенной ссылки.
Эта ссылка не имеет атрибута title.
В результате получается:
Это пример встроенной ссылки.
Эта ссылка не имеет атрибута title.
Если вы хотите ссылаться на контент, находящийся на том же сервере, вы можете использовать относительные пути:
Дополнительную информацию можно найти на странице Обо мне.
Для создания ссылок используется второй набор квадратных скобок, в которых записывается произвольно выбранный идентификатор ссылки:
Это пример для справочной ссылки.
При желании между скобками можно также вставить пробел:
Это [пример] id для справочной ссылки.
Затем, где-то в документе, ссылка определяется на отдельной строке следующим образом:
Так:
- Квадратные скобки, содержащие идентификатор ссылки (опционально с
с отступом до трех пробелов);
- с последующим двоеточием;
- за которым следует один или несколько пробелов (или табуляций);
- за которым следует URL-адрес ссылки;
- (по желанию) далее следует текст атрибута title ссылки.
заключено в скобки, одинарные или двойные кавычки.
Следующие три определения идентичны:
Примечание: В Markdown 1.0.1 обнаружена известная ошибка, из-за которой одинарные кавычки не могут использоваться в качестве разделителей для заголовков ссылок.
URL-адрес ссылки можно дополнительно заключить в угловые скобки:
Атрибут title также может быть установлен на следующую строку и иметь отступ с помощью дополнительных пробелов или табуляции. Это лучше смотрится с длинными URL-адресами:
"Здесь может быть необязательный заголовок"
Определения ссылок используются только для создания ссылок в процессе обработки документа Markdown и удаляются из документа перед выводом HTML-кода.
Ссылки могут состоять из букв, цифр, пробелов и знаков препинания. Они не зависят от регистра.
[Ссылка на текст][a] [Ссылка на текст][A]
Оба определения связи эквивалентны.
Неявный идентификатор ссылки позволяет опустить сам идентификатор ссылки. В этом случае в качестве идентификатора используется текст ссылки. Просто добавьте к тексту ссылки пустые квадратные скобки:
Затем определяется связь:
Поскольку идентификаторы ссылок могут содержать пробелы, это сокращение работает даже для нескольких слов в тексте ссылки:
Для получения дополнительной информации посетите Daring Fireball.
Затем определяется связь:
Ссылки можно размещать в любом месте документа Markdown. Как правило, лучше размещать их после абзаца, в котором они используются. Однако их также можно перечислить вместе в конце документа, как сноски.
Небольшой пример:
Я получаю в десять раз больше трафика от Google 1, чем от Yahoo 2 или MSN 3.
Используя аббревиатуру через подразумеваемый идентификатор ссылки, можно также записать следующее:
Я получаю в десять раз больше трафика из Google, чем из Yahoo или MSN.
В обоих примерах получится следующий HTML-код:
Я получаю в десять раз больше трафика с сайта Google, чем с сайта Yahoo или MSN.
Для сравнения, тот же абзац приводится ниже с использованием встроенных ссылок Markdown:
Я получаю в десять раз больше трафика с Google, чем с Яху или МСН.
Идея использования ссылок не в том, что их проще писать. Идея в том, что они делают документы гораздо более читабельными. Пример абзаца содержит всего 80 символов со ссылками, но без них его длина составляет целых 181 символ; в формате HTML это 239 символов, больше разметки, чем контента.
Ссылки в Markdown делают исходный документ более похожим на конечный формат, отображаемый в браузере. Возможность извлекать метаданные для разметки из абзаца позволяет интегрировать ссылки в текст, не нарушая его связность.
В Markdown для выделения текста звездочками (*) и подчеркиваниями (_) считаются индикаторы выделения. Текст, заключенный в одинарный тег * или _, обозначается тегом <em>, а повторяющиеся теги * или _ помечаются тегом <strong>. Например:
Отдельные звездочки
Одиночные подчеркивания
Двойные звёздочки
Двойные подчеркивания
В результате будет выведено следующее:
Одиночные звездочки
<em>Одиночное подчеркивание</em>
Двойная звездочка
Двойные подчеркивания
Стиль можно выбирать свободно. Единственное ограничение заключается в том, что один и тот же символ должен использоваться для открытия и закрытия области выделения.
Выделение может быть использовано в середине слова:
Таинство Господа Бога
Однако, если * или _ заключены в пробелы, они рассматриваются как простая звездочка или простое подчеркивание.
Чтобы написать звездочку или нижнее подчеркивание в месте, где они будут восприняты как выделение, их можно замаскировать обратной косой чертой:
Этот текст заключен в звездочки.
Код Чтобы обозначить блок кода, он заключается в обратные кавычки (`). В отличие от блока кода, блок кода форматирует код внутри обычного абзаца:
Используйте функцию printf() для вывода текста.
Становится:
Для вывода текста используйте функцию printf().
Если в области кода необходимо отобразить обратную кавычку, то до и после области кода можно использовать несколько обратных кавычек:
Irgendwo hier (`) имеет скрытую обратную кавычку.
В результате получится:
Здесь где-то спрятана обратная кавычка (`).
В качестве разделителей диапазона кодов обратными кавычками могут использоваться пробелы - один после открывающей обратной кавычки и один перед закрывающей. Это позволяет использовать обратные кавычки внутри диапазона кодов, даже в начале или конце.
Одиночная обратная кавычка в кодовой области: `
Строка в обратных кавычках в разделе кода: `foo`
становится:
Одиночная обратная кавычка в блоке кода: `
Строка в блоке кода, заключенная в обратные кавычки: `foo`
В разделах кода амперсанд (&) и угловые скобки кодируются как HTML-сущности.
Никто не использует теги <blink>.
В результате получится:
Никто не использует теги .
Также подойдет следующий вариант:
— - это десятичный эквивалент —.
Это приведет к
— - это десятичный эквивалент —.
Графика Следует признать, что найти «естественный» синтаксис для встраивания графики в текст довольно сложно.
В Markdown для этого используется синтаксис, призванный имитировать стиль ссылок. Это позволяет использовать два типа ссылок: встроенные и ссылочные.
Встроенный синтаксис выглядит следующим образом:


Так:
- Восклицательный знак:
!; - за которым следуют квадратные скобки, указывающие значение
alt атрибуты, включенные для графического изображения;
- за которыми следуют скобки, содержащие URL-адрес или путь к изображению.
а также значение необязательного атрибута title, заключенное в кавычки.
В стиле оформления ссылок изображения выглядят следующим образом:
Здесь "id" - это имя определенной ссылки на изображение. Ссылки на изображения определяются с использованием того же синтаксиса, что и ссылки на объекты:
В настоящее время в Markdown отсутствует синтаксис для указания размера изображения. Если это необходимо, можно просто использовать стандартный HTML-тег <img>.
Разнообразный
Маскирование обратной косой черты
Markdown позволяет использовать экранирование обратными косыми чертами для написания символов, которые в синтаксисе Markdown имеют определенное значение.
Например, если вы хотите заключить слово в звездочки (вместо HTML-тега <em>), вы можете поставить обратные косые черты перед звездочками:
Обведено звездочками
Markdown предоставляет такую возможность для следующих символов:
\ Обратная косая черта ` Обратная кавычка
- звездочка
_ Подчеркивание {} Фигурные скобки [] Квадратные скобки () Круглые скобки
Хэш + знак плюса
- Знак минус (дефис)
Точка! Восклицательный знак
Происхождение и лицензия
Данная работа распространяется под лицензией Creative Commons Attribution-ShareAlike (BY-SA) 4.0 International License]by-sa.
Это перевод оригинальной документации по синтаксису, подготовленной Джоном Груберсом (версия Markdown 1.0.1). Данный перевод отражает состояние Markdown по состоянию на 15 декабря 2013 года. Точность перевода не гарантируется. Пожалуйста, отправьте краткое сообщение на адрес lasar@liepins.net, если вы обнаружите какие-либо ошибки.
Любые другие отзывы также приветствуются.