Pull to refresh

Веб-справка, веб-документы. Еще проще

Reading time 4 min
Views 18K
Представляю вам бандл библиотек для создания 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='http://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

Это первый обзорный пост и пока нет результатов бета-тестирования и обсуждения, поэтому о внутренностях не пишу, хотя внутри все довольно интересно, бандл это такая маленькая веб-ОС и есть о чем рассказать.
Tags:
Hubs:
+18
Comments 8
Comments Comments 8

Articles