Пару раз понадобилось встроить в сайт справочную систему. Простенькую, с тремя колонками — общее меню, текущая статья и меню содержания статьи. Поиски готового компонента/библиотеки не привели к успеху совсем. Поэтому пришлось написать свой, который предлагается к использованию.
Большинство существующих систем документирования представляют собой генераторы статичных сайтов. То есть, при небольшом изменении контента всё надо перегенерировать, что не очень удобно. Также, не у всех есть правая колонка, не у всех, у кого есть, она работает в полной мере (кликабельна и отслеживает и показывает текущее положение страницы статьи). Не у всех дерево меню имеет необходимую глубину вложенности. Не все легко кастомизируются стилями. И еще много разных "не все". Была сделана попытка большую часть этих недостатков (всё субъективно, конечно) устранить.
Особенности
- Легкий (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.
ссылка на оригинал статьи https://habr.com/ru/post/502258/
Добавить комментарий