docs.modx.pro
mxLocDoc
mxLocDoc
Просмотр локальной Markdown-документации проекта в менеджере MODX Revolution 2 и 3 — навигация из манифеста, безопасный рендер, защищённые ассеты, поиск с кэшем, языки.
  1. Компоненты
  2. mxLocDoc
  3. Синтаксис Markdown

Синтаксис Markdown ​

Документы пишутся на Markdown и отображаются в менеджере через Parsedown в безопасном режиме. Ниже — что поддерживается, что нет, и короткая шпаргалка для тех, кто с Markdown раньше не работал.

Полный справочник: Markdown Guide (разделы «Basic Syntax» и «Extended Syntax»).

Что поддерживается ​

Заголовки ​

markdown
# Заголовок первого уровня
## Второго уровня
### Третьего уровня

Выделение текста ​

markdown
**жирный**, *курсив*, ~~зачёркнутый~~

Списки ​

markdown
- пункт
- пункт
  - вложенный пункт

1. первый
2. второй

Ссылки и картинки ​

markdown
[текст ссылки](guide/setup.md)
![подпись под картинкой](images/diagram.svg)

Относительные ссылки на .md-файлы открываются внутри mxLocDoc, а относительные картинки отдаются через защищённый connector: mxLocDoc проверяет путь, расширение и размер файла и не выпускает запрос за пределы корня документации. Внешние ссылки и картинки остаются обычными.

Ссылки на раздел (якоря) ​

Появилось в 1.0.1-pl (MODX 2) и 2.0.1-pl (MODX 3)

В более ранних версиях ссылка с якорем просто открывала документ с начала.

markdown
[к разделу этого документа](#настройки)
[к разделу другого документа](guide/setup.md#настройки)

Якорь — это заголовок, записанный строчными буквами, где пробелы и знаки препинания заменены дефисами: ## Настройки пакета → #настройки-пакета. Кириллица работает наравне с латиницей. Якорь можно ставить на заголовок любого уровня, с первого по шестой, — не только на те, что попадают в оглавление справа.

По такой ссылке mxLocDoc прокручивает панель документа к нужному разделу, не трогая адрес страницы и не сдвигая саму админку. Если раздела с таким якорем нет, документ просто откроется с начала — ошибки не будет.

Если в документе два одинаковых заголовка, якорь ведёт к первому из них.

Общий каталог картинок ​

markdown
![схема](/assets/scheme.png)

Путь, начинающийся со слэша, отсчитывается от корня документации, а не от папки текущего файла. Так один каталог с картинками обслуживает документы любой вложенности: писать ../../../assets/scheme.png не нужно.

Две оговорки:

  • в многоязычной документации корнем считается папка своего языка (docs/ru/, docs/en/), поэтому каталог с картинками нужен внутри каждой языковой папки;
  • правило действует для картинок. Ссылка на не-.md файл ([бланк](/assets/form.pdf)) остаётся обычной ссылкой и ведёт в корень сайта, а не документации.

Код ​

Внутри строки — в одинарных обратных кавычках. Блоком — в тройных обратных кавычках, можно указать язык:

markdown
```php
echo 'hello';
```

Код показывается моноширинным шрифтом. Подсветка синтаксиса не выполняется.

Цитаты, разделитель и таблицы ​

markdown
> цитата

---

| Колонка | Значение |
|---------|----------|
| A       | 1        |
| B       | 2        |

Что не поддерживается ​

  • Списки задач - [ ] пункт / - [x] пункт — покажутся как обычный текст со скобками.
  • Сноски [^1], списки определений, аббревиатуры, инлайн-атрибуты{.класс} — это расширения ParsedownExtra, которых в пакете нет.
  • Сырой HTML (<div>, <iframe>, <details> и т.п.) — намеренно экранируется и показывается как текст. Это защита от небезопасного содержимого.
  • Подсветка синтаксиса в блоках кода.
  • Небезопасные ссылки (javascript: и подобные) вырезаются.

Шпаргалка ​

Что нужноКак написатьРезультат
Заголовок## Названиезаголовок раздела
Жирный текст**текст**текст
Курсив*текст*текст
Зачёркнутый~~текст~~текст
Список- пунктмаркированный список
Нумерация1. пунктнумерованный список
Ссылка[текст](адрес)кликабельная ссылка
Ссылка на раздел[текст](#раздел)переход к разделу документа
Цитата> текстблок цитаты

Совет: оставляйте пустую строку между абзацами, заголовками и списками — без неё блоки могут «слипнуться» в один абзац.