Хочу представить вам новый проект по ведению открытой документации для MODX Revolution.
Зачем?
Затем, что система далеко не новая, а нормальной русскоязычной документации до сих пор нет. Всё, что есть, разбросано по разным сообществам и блогам, которых несколько десятков, и любой начинающий пользователь бегает туда-сюда, задавая вопросы.
Официальная документация на русском не ведётся. Не знаю, как сейчас, но год назад у них просто не сохранялась кириллица.
Почему не сделать это на сайте n или z?
Потому, что у этих сайтов есть хозяева, у них нужно просить логиныпароли и нет никакой гарантии, что завтра сайт не пропадёт, оставив ваш вклад в кэше гугла.
Например, я пробовал писать про свои дополнения на официальном сайте, а потом они его переделали, и мой логин пароль больше не подходит. Просто зарегистрироваться нельзя — нужно получать их через письмо в поддержку. Конечно, повторно это делать нет желания.
К тому же, сообщество MODX не может похвастаться сплоченностью, и основных разработчиков просто не собрать в одном месте, чтобы они что-то там написали.
И что ты предлагаешь?
Очень просто — нужно вести документацию в GitHub, в общеизвестном формате Markdown.
Такая система гарантирует нам:
- Сохранность всех текстов. Каждый человек может скопировать репозиторий и разместить у себя.
- История изменений. Все правки как на ладони, видно кто и что написал.
- Независимость. Вы можете писать о любой теме, касающейся MODX, на любом языке. И вам не нужно просить для этого доступ — достаточно иметь аккаунт на GitHub.
Идея не новая, и подсмотрел я её у проекта daux.io. Это PHP скрипт, который генерирует сайт по готовым файлам markdown.
Он очень простой, и позволяет запустить свой сайт с документацией, не обладая вообще никакими навыками, на любом . Однако, на мой взгляд, у него есть несколько недостатков (которые являются продолжением достоинств).
Например, я вовсе не уверен, что динамическая генерация сайта по файлам, без кэширования, будет хорошо работать на нескольких тысячах страниц. Таже, там нет поиска, нет управления адресами страниц, удобного переключения между языковыми версиями, и еще по мелочи.
Так что, для показа нашей документации я использовал любимую систему — MODX.
Как работает?
Это обычный сайт на MODX, построенный с использованием стандартных дополнений, но все его страницы импортируются из файлов.
Это даёт:
- Кэширование. Все документы будут загружаться из кэша, и не нужно каждый раз шерстить все файлы документации.
- Управление url документов — их можно перемещать и не терять при этом переходы из поисковиков.
- Возможность организовать поиск на сайте.
- Удобная работа с языковыми версиями. Их может быть сколько угодно.
Вёрстку я набросал на Bootstrap 3, чтобы было удобно читать с телефонов и планшетов. Для работы используются:
- pdoTools — вывод соседних документов, всех меню и хлебных крошек.
- mSearch2 — морфологический поиск.
- DateAgo — приятное форматировние дат
- yTranslit — генерация url страниц через переводы Яндекс.
- MinifyX — склейка и сжатие скриптов и стилей, для быстрой загрузки страниц.
- Markdown — новый сниппет для вывода текстов в этом формате. Написал специально для этого проекта.
Еще раз напоминаю, что эта документация никому не принадлежит. Я сделал свою версию сайта для её вывода, а вы можете склонировать репозиторий и запустить его на том же daux.io — структура директорий и файлов совместима.
Цель проекта, дать наконец то инструмент сообществу, чтобы собрать всю информацию в одном месте, и дружно ей пользоваться. Присоединяйтесь!
Ссылки
Репозиторий документации на Gitub.
Сайт с выводом этой документации.
Готовый сниппет Markdown.
Наш репозиторий с дополнениями, на которых работает сайт.
Планы на будущее: разработка простенького API, для интеграции текстов на другие сайты и (возможно) сокращалка url.
Автор: bezumkin
