О проекте
Open Source документация MODX Revolution, распространяемая через GitHub.
Для того, чтобы внести свой вклад в развитие документации, вам нужно просто сделать pull-request в репозиторий.
Такая организация гарантирует:
- Сохранение истории всех изменений.
- Использование простого языка разметки Markdown.
- Возможность не переживать за проект - вы всегда можете запустить копию у себя.
Идея
Сам принцип подсмотрен у проекта daux.io, который генерирует сайт налету по статичным страницам. Для работы нужен только его скрипт и директория с определённой структурой и файлами в формате Markdown.
Однако, на мой взгляд у daux.io есть несколько серьёзных недостатков:
- Неудобное управление шаблоном.
- Отсутствие мультиязычности в оформлении страниц.
- Нет кэширования, неизвестно каких объемов документацию он потянет.
- Нет встроенного поиска.
- Нет перенаправления с одного адреса на другой, при переносе документа.
- Довольно много ошибок в коде.
В общем, для небольших объёмов это хорошее решение, но для нашего проекта мы используем MODX.
Принцип остаётся тот же: директория с файлами Markdown, из которых строится сайт. Но теперь это самостоятельный сайт, со всеми наворотами, который обновляет свои страницы из GitHub. Мы избавились от всех недостатков daux.io и добавили преимущества MODX.
Правила оформления документации
Структура
Формат репозитория определяется следующей структурой:
- Языковая версия
- Раздел
- Тема
- Дальше структура определяется в зависимости от темы
- Чтобы указать порядок директорий и файлов, мы используем числовые префиксы.
Вот путь к файлу с описанием сниппета HybridAuth на русском:
/ru/02_Компоненты/04_HybridAuth/01_Сниппеты/01_HybridAuth
Заголовки
Для заголовков мы используем хештэги ## и между ними и текстом ставим пробел. Например: ## Заголовок
Заголовки должны быть не больше h2, то есть, 2 решетки ##:
- h2 = ##
- h3 = ###
- h4 = ####
Между заголовком и текстом сверху оставляется одна пустая строка. Между заголовком и текстом снизу отступов делать не нужно.
Ссылки
Ссылки на документы нужно проставлять в конце страницы, чтобы их было удобно искать и обновлять. В markdown это делается так:
[Название ссылки][1]
[Название другой ссылки][2]
[1]: http://mylink.com/
[2]: http://mylink.com/test.html
Помимо прочего, это позволяет использовать одну ссылку несколько раз на странице:
[Ссылка 1][1]
[Ссылка 2][2]
[1]: http://mylink.com/
Ссылки на страницы репозитория необходимо указывать от корня, с ведущим слешем, тогда по ним можно переходить прямо на GitHub:
[Ссылка на русский раздел pdoTools][3];
[3]: /ru/01_Компоненты/01_pdoTools
Проще всего открывать нужную страницу на GitHub и копировать адрес из url.
Ссылки на изображения можно вставлять сразу в тексте. Для указания изображений лучше использовать сервис на file.modx.pro (требует авторизацию). Он автоматически сгенерирует уменьшенную копию и код markdown для вставки.
[](https://file.modx.pro/files/8/5/3/85333575318f1fb2e7fe2881eb25559a.png)
Выделение
Cистемные параметры нужно выделять жирным текстом, например: **¶metr** будет выглядеть, как ¶metr.
Плейсхолдеры оборачиваются в одинарные обратные апострофы. Например: `[[+placeholder]]` будет выглядеть, как [[+placeholder]]
.
Для обрамления кода нужно использовать 3 обратных апострофа ``` перед секцией кода, и после:
Здесь код
Сам код начинается с новой строки. Пустые строки до и после кода - по желанию.
Перенос строки
Для принудительного переноса строки нужно добавить 2 пробела на конце. Парсер заменит их на тег br
.
Таблицы
Вы можете использовать таблицы для удобного отображения различных данных, например параметров какого-то сниппета:
First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
First Header | Second Header |
---|---|
Content Cell | Content Cell |
Content Cell | Content Cell |
Основы Markdown
Подробная документация на сайте у автора.
Обратите внимание, что на этом сайте используется Markdown Extra, в котором можно использовать таблицы и другие навороты.
Проверить, как будет выглядеть ваш документ можно на bezumkin.ru/utils/markdown.