Нетрудно заметить, что я весьма активно пользуюсь технологией Markdown, и не только для ведéния этого блога. Данная технология есть мой основной способ организации личного информационного пространства и оформления документов среднего объёма (для серьёзных объёмов есть LaTeX).
Сегодня речь пойдёт о замечательном инструменте, который резко расширяет границы возможного применения Markdown. Встречаем — MDwiki. Лёгкий, эффективный и удобный способ организации Markdown-файлов в псевдовики. Причём не требует никакого софта.
Вообще-то вики-средства на основе данного языка разметки существуют, и среди них есть очень даже хорошие — взять хоть Trunk Notes, которой я сам с удовольствием пользуюсь. Но практически у всех у них есть общий недостаток: они либо оффлайновые, либо существуют не под все платформы, либо и то и другое разом. Или, как вариант, если оно онлайновое и мультиплатформенное, то требует прикручивания к серверу немеряной кучи всяких допов с модами и патчами, причём способ установки-настройки каждого допа радикально зависит от типа сервера, отчего всякие апгрейды и переезды вызывают острое желание взять в руки BFG. :)
MDwiki решает проблему просто и изящно — это один HTML-файл, который делает всё на стороне пользователя в его браузере. Соответственно, установка приложения сводится к простому складыванию кучи файлов в одно место, а от сервера не требуется вообще ничего сверх элементарного умения отдавать файлы по http.
Как это работает? Страница, написанная на HTML5+JavaScript, на лету транслирует Markdown-файлы и показывает их как часть себя. В результате для пользователя создаётся видимость полноценного сайта с вики-подобным интерфейсом. Посмотреть пример можно здесь — там же и документация и ссылка на скачивание.
Разумеется, чтобы это действительно работало, нужен нормальный браузер. Лично проверено, что работает в…
- десктопных Safari, Chrome, Firefox под виндовс и макось;
- их мобильных аналогах под iOS.
В некоторых случаях будет прекрасно работать даже в файловом оффлайн-варианте, но лучше всё же поднять сервер. Сие не проблема, так как все современные десктопные операционки имеют http-серверы в своём составе… для тех, кто в танке, виндовс содержит в себе IIS, который нужно только включить и указать ему стартовый каталог сайта.
Кстати, IIS требует небольшой подстройки: нужно добавить ему пару MIME-типов, дабы он знал, что файлы *.md и *.json надлежит отдавать как простой текст. Делается за одну минуту ровно.
Что получается в результате… иными словами, что пользователь получит на выходе?
- Сайт с двухуровневой навигацией (глобальная по сайту плюс локальная по каждой странице), оформление страниц — возможности разметки Markdown плюс, если нужно, допускается прямое использование HTML.
- Около дюжины тем оформления (лучшие, на мой взгляд, это
ceruleanиreadable— для любителей шрифтов без засечек и с засечками соответственно). В оффлайн-варианте доступна толькоbootstrap. -
Куча плагинов, позволяющих, в частности:
- Отображать математические формулы посредством MathJax;
- Вставлять на страницы ролики с YouTube и карты Google Maps;
- Интегрироваться с GitHub;
- В ограниченных пределах интегрироваться с Twitter и Facebook.
- Прикручивать к страницам обсуждения посредством Disqus.
При этом важно понимать, что полноценной вики результат не является — это именно что псевдовики. По двум причинам:
- Нет средств редактирования сайта из него самого — это делается внешним редактированием образующих сайт файлов.
- Нет средств динамического формирования контента (теги, условия, включения файлов и т.п.) — это при желании можно делать с помощью JavaScript или PHP (если сервер поддерживает), но никакого API для этого не предоставляется.
Так что если нужно организовать полноценную вики среду с совместной работой над наполнением — это не сюда, однозначно. А вот организовать кучу заметок в полноценный сайт — то что доктор прописал.
Как организовать сайт в MDwiki
Кладём в корень сайта файл приложения mdwiki.html и (очень рекомендуется) переименовываем его в index.html (или в то, что сервер отдаёт по умолчанию).
Рядом с ним создаём файл config.json, для начала пустой, просто чтобы с него 404 не генерировалось. Потом, если что, в него можно будет прописать некоторые настройки (см. документацию).
Рядом с ними кладём favicon.ico и apple-touch-icon.png, если хочется, чтобы сайт имел нормальное дополнительное оформление в браузерах, в том числе мобильных.
Далее складываем туда же Markdown-файлы, образующие контент сайта. Они должны быть в кодировке UTF8 и иметь расширение *.md (русскоязычное содержание обрабатывается абсолютно нормально, но имена файлов лучше всё же держать в латинице — проверено, что IIS работает с русскими именами правильно, про другие ситуации ручаться нельзя).
Файл index.md будет корнем сайта, отображаемым по умолчанию.
Файл navigation.md превратится в горизонтальное меню, включаемое в верхнюю часть каждой страницы сайта. Указанные в нём ссылки превратятся в элементы меню и подменю, подробности см. в документации. Лучше чтобы этот файл присутствовал, пусть даже и пустой — опять же, чтобы 404 с него не генерировалось.
Все остальные *.md файлы будут страницами сайта. Один файл — одна страница. Ссылки на них ставятся стандартными средствами Markdown. Можно раскидывать по папкам, указывая в ссылках соответствующие пути.
Как файл превращается в страницу сайта
Лучше, чтобы файл имел в самом начале заголовок первого уровня, тогда он станет видимым заголовком страницы. Можно иметь на странице ещё заголовки первого уровня, они отображаются нормально.
По заголовкам второго уровня (если они есть и если их на странице более одного) будет сформировано навигационное меню содержания. И только по ним. Заголовки остальных уровней выполняют чисто оформительскую функцию.
Для разметки страницы используется стандартный Markdown с расширениями в стиле GitHub. Таблицы, вынесенный программный код с подсветкой синтаксиса, выделение текста зачёркиванием, разрывы строк как в исходном тексте (можно переключить на стандартные в config.json). Шпаргалка здесь.
Сноски и списки определений отсутствуют! Списки определений можно при желании сделать прямо через HTML, но со сносками это значительно сложнее. К счастью, есть полезное добавление от разработчиков MDwiki.
Если абзац содержит сигнальное слово типа «Note», «Warning», «Hint», за которым следует двоеточие или восклицительный знак, то этот абзац будет выделен цветом. Есть несколько таких слов и несколько цветов, см. документацию. Подредактировав файл приложения, можно добавить к ним и русские варианты.
Вставка изображений делается обычными средствами Markdown, при этом изображения на страницах помещаются в увеличиваемые лайтбоксы. В зависимости от того, как команды вставок размещаются относительно абзацев, изображения могут быть различным образом разложены и выровнены на странице (см. документацию, это сделано умно и хорошо).
