Представляю вам бандл библиотек для создания web-документов с использованием разметки Markdown.
Сразу хочу сказать, библиотек такого направления в сети много, но эта имеет принципиальные отличия и обладает большим функционалом по сравнению с ними. Что называется powered by.
Это рассказ о прототипе и полной документации еще нет. Возможны (и нужны) изменения в коде и архитектуре библиотеки, но язык разметки и шаблон страницы уже практически стабильны.
Самый простой способ создания online-справки или веб-сайта. Туториал.
Для создания нам потребуется любой текстовый редактор.
Вариант 1. Стартовый.
Для начала создадим шаблон страницы или скачаем по ссылке page template.html. Если по этой ссылке в вашем браузере откроется сам шаблон, а не загрузится его файл, просто скажите браузеру Save As (HTML only), для начала нужен только HTML код. Если все правильно, в файлике находится примерно вот такой простой шаблон странички:
<!DOCTYPE html>
<html lang="ru-RU">
<head>
<meta charset="utf-8">
<title>Example</title>
<script src="document.min.js" id='DOC' onerror="var l=document.createElement('link'),s=document.createElement('script');l.rel='stylesheet';l.href='http://netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css';l.id='bootstrap.css';l.auto='1';document.head.insertBefore(l,document.getElementById('DOC'));s.src='https://aplib.github.io/document.min.js';document.head.appendChild(s);"></script>
</head>
<body>
<!--fixed-top-bar
%navbar(
* [Home](index.html)
* [Page1](page1.html)
)%navbar
-->
<!--header-panel
# Insert header here
site description
-->
<!--content-panel
# content text
## content text
### content text
content text
-->
<!--footer-panel
footer here
-->
<noscript><div class="alert alert-warning">This Website requires your browser to be JavaScript enabled.</div></noscript>
</body></html>Пояснение для осторожных: при отсутствии скрипта, загружается css с родного bootstrap CDN, а скрипт из репозитория на гитхабе, зловредов там нет.
Далее мы используем этот код в качестве шаблона.
Если открыть эту страничку в браузере мы видим форматированный текст. Это Markdown разметка текста для его форматирования. Очень распространенный в интернет вариант разметки текста, большинство читателей наверное с ним уже встречались.
Приведенный выше микро-шаблон уже работает в ограниченном режиме, даже без дополнительных файлов. Можно редактировать текст, и публиковать в таком виде на своем сайте. Правда это будет не очень отзывчиво, а временами подлагивать, поскольку бандл в этом режиме загружается с моего репозитория. Чуть проще сказав — если не добавлять скрипт document.min.js и css – может чуть подтормаживать и не работает в offline. Впрочем, для каких-то нужд и так сгодится, а из преимуществ — простота создания.
Вариант 2. Одностраничный сайт или сайт из двух-трех страниц.
Заходим на aplib.github.io/markdown-site-template/, качаем шаблон, достаем из архива document.min.js и bootstrap.css и кладем их в папку рядом с нашими страницами. Это собственно сам бандл и css, то есть библиотеки. Для просмотра сайта (или документа) в нормальном режиме и в offline этого достаточно. Хотя это еще не все.
Вариант 3. Почти полный.
Темы
На месте bootstrap.css может быть любой bootstrap-совместимая тема или родной bootstrap, но с пользовательской настройкой, то есть customized. Посмотрите подборку бесплатных тем на bootswatch.com/. Не без отдельных недостатков, но безусловно прекрасная подборка. На сайте проекта можно посмотреть как эти темы изменяют внешний вид сайта.
user.js
Долой копипасту! Меню навигации, шапку и подвал лучше вынести в отдельный общий файл. Можно увидеть в этом же архиве в качестве примера user.js содержащий общие элементы страницы.
Компоненты
А ведь есть еще подключаемые компоненты и моды. Подключаются они копированием в определенную папку на сайте.
Это то что отличает данный бандл от всех остальных. Markdown разметка она и так расширяется простым html кодом, а тут еще и произвольно программными компонентами, причем в конечном варианте будет еще и с произвольной вложенностью. Посмотрите на сайте примеры из раздела компоненты, будет понятнее. Компонент может быть и элементом оформления, и управляющей программой, формулой или разметкой сайта. И в компоненте, в его тексте если он визуальный, мы тоже можем построить свою маленькую вселенную. Это как вложенные шаблоны, но только лучше. И компоненты могут загружаться в фоновом режиме, шаблоны так не умеют.
sitemap.xml
Если вы добрались до этого пункта, возможно вы захотите разместить сайт сделанный по такому принципу в сети и хотите индексации его в гугле. Я так и сделал. Поскольку это JS сайт, для нормальной индексации в гугле вам потребуется скормить поисковой системе sitemap.xml, иначе гугл не видит внутренние ссылки. Этот файл можно создать с помощью sitemap.html. Альтернатива sitemap.xml — после создания страниц генерация статических html, вариант более надежный и такая возможность есть, но документацию по этому режиму еще нужно написать.
Проект.
Вроде бы обзорно упомянул самые важные особенности. Теперь о том как и из чего это сделано. В основном это склеенные очень популярные библиотеки jquery, bootstrap, marked, doT немного отполированные сверху с помощью uglifyjs. controls.js является ядром компонентной системы, позволяющей расширять язык разметки. Сборка библиотек простым скриптом, без грунта.
Несмотря на то что этот проект для меня учебный, к сожалению серьезных трудностей при реализации я не встретил и рассказать о преодолениях не могу. Могу только отметить иногда нетривиальные правила разметки Markdown в сложных случаях. Он конечно простой, но некоторые особенности форматирования я довольно долго не мог понять и запомнить.
Лицензия наиприятнейшая. Это вам не GPL, это MIT, торжество свободы и равноправия.
Сайт aplib.github.io/markdown-site-template/
Репозиторий github.com/aplib/markdown-site-template
Это первый обзорный пост и пока нет результатов бета-тестирования и обсуждения, поэтому о внутренностях не пишу, хотя внутри все довольно интересно, бандл это такая маленькая веб-ОС и есть о чем рассказать.
Автор: aplic
