Пару раз понадобилось встроить в сайт справочную систему. Простенькую, с тремя колонками — общее меню, текущая статья и меню содержания статьи. Поиски готового компонента/библиотеки не привели к успеху совсем. Поэтому пришлось написать свой, который предлагается к использованию.
Большинство существующих систем документирования представляют собой генераторы статичных сайтов. То есть, при небольшом изменении контента всё надо перегенерировать, что не очень удобно. Также, не у всех есть правая колонка, не у всех, у кого есть, она работает в полной мере (кликабельна и отслеживает и показывает текущее положение страницы статьи). Не у всех дерево меню имеет необходимую глубину вложенности. Не все легко кастомизируются стилями. И еще много разных "не все". Была сделана попытка большую часть этих недостатков (всё субъективно, конечно) устранить.
Особенности
- Легкий (30KB в UMD с Markdown в gzip-e в браузерной версии)
- Быстрый, юзер-френдли шаблон
- Полностью стилизуемый кастомным СSS
- Удобен для использования во встроенных системах документирования/справки
- Формат контента — HTML и Markdown. Структура меню и контент статей располагается в
vbcfg.jsonфайле и в отдельных.htmlили.mdфайлах, и легко модифицируется без ребилда приложения. - Опциональная предзагрузка статей
- Опциональный роутер — позволяет пользователям сохранять в закладки браузера ссылки на отдельные статьи
- Изначально без зависимостей (библиотек). Для маркдауна подключается
marked(или аналог на выбор), для цветовой дифференциации программного кода в блоках —hightligh.js. Для роутинга —vue-router - Вложенность пунктов меню неограничена. Правое меню контента статьи генерируется автоматически по H1-H6 тэгам.
SEO был не нужен, поэтому этот вопрос не рассматривался. Если понадобится — есть внешние средства, позволяющие "озрячить" поисковики, и не вносящие в проект и код приложения ненужную тяжесть.
Компонент vuesence-book можно использовать как в Node.js приложении так и в браузере, подключая скриптом.
npm install @vuesence/book --save<template>
<div id="app" class="app">
<vuesence-book
header-title="My Book"
:use-router="false"
/>
</div>
</template>
<script>
import VuesenceBook from "@vuesence/book";
export default {
name: "App",
components: {
VuesenceBook
}
};
</script>
<style>
@import './css/default.css';
/* @import './css/vuepress-style.css'; */
/* @import './css/google-style.css'; */
</style><!DOCTYPE html>
<html lang="en">
<head>
<meta name="viewport" content="width=device-width,initial-scale=1.0,user-scalable=no">
<title>vuesence-book demo</title>
<script src="https://unpkg.com/vue"></script>
<script src="https://unpkg.com/@vuesence/book@0.3.42"></script>
<link rel="stylesheet" href="https://unpkg.com/browse/@vuesence/book@0.3.42/src/css/default.css">
<!-- You can plug in any custom CSS here to style the Vuesence Book-->
<!-- <link rel="stylesheet" href="css/vuepress-style.css"> -->
<!-- <link rel="stylesheet" href="css/google-style.css"> -->
</head>
<body>
<div id="app" class="app">
<!-- рядом с данным html файлом должен лежать vbcfg.json
и директория pages со статьями -->
<vuesence-book
header-title="My Book"
article-path="pages/"
:use-router="false"
/>
</div>
</body>
<script>
new Vue({ el: '#app' })
</script>
</html>Атрибуты vuesence-book элемента
- article-lazy-load — загрузка статей по запросу или при создании компонента. По умолчанию:
false - cfg-path — путь к конфигурационному файлу. По умолчанию: "vbcfg.json"
- article-path — путь к статьям. По умолчанию: "pages/"
- header-title — заголовок хедера. По умолчанию: "Vuesence.Book"
- show-header — показывать хедер или нет. Если нет, то открывать боковое меню в мобильном виде надо программно (
openSidebar(),closeSidebar()иtoggleSidebar()методы на компоненте). По умолчанию:true - hide-header-in-desktop-view — спрятать хедер в десктопе виде. Используется, чтобы настроить поках хедера только в мобильном представлении. По умолчанию:
false - hide-root-in-article-navigation — не показывать корневой заголовок в меню в правой колонке (часто совпадает с названием статьи) По умолчанию:
false - use-router — использовать Vue-router или нет. Содержащее VuesenceBook Node.js приложение должно добавить
routeдля VuesenceBook контента. Для браузерной версии должно быть установлено наfalse. По умолчанию:true
Конфигурационный файл
{
"startArticle": "overview",
"data": [{
"title": "TOC",
"sections": [
{
"id": "overview",
"title": "Overview",
"url": "overview.html"
},
{
"title": "Setup",
"sections": [
{
"id": "install",
"title": "Installation",
"url": "installation.md"
}
]
}
]
},
{
"title": "Examples",
"id": "design",
"sections": [
{
"id": "5",
"title": "Inline HTML",
"content": "<h2>Inline HTML article</h2><p>This text is embedded in the <b>vbcfg.json</b> file. Other articles are in separate HTML and MD files.</p> "
}
]
}
]
}Если у статьи есть атрибут content — используется его значение (без изменения формата). В противном случае статья загружается по url. Тип контента определяется по расширению файла.
Ссылки
Поэкспериментировать с Vuesence Book можно в песочнице
Подробная документация по компоненту здесь
Этот же сайт представляет собой пример Vuesence Book, запущенного в режиме браузера (100/95 баллов на PageSpeed, кстати, без сетевой оптимизации).
Bugs, issues, feature and pull requests are welcome
Понравилось — GitHub star.
