Vue.js компонент для справки/документации
- четверг, 28 мая 2020 г. в 00:37:03
Пару раз понадобилось встроить в сайт справочную систему. Простенькую, с тремя колонками — общее меню, текущая статья и меню содержания статьи. Поиски готового компонента/библиотеки не привели к успеху совсем. Поэтому пришлось написать свой, который предлагается к использованию.
Большинство существующих систем документирования представляют собой генераторы статичных сайтов. То есть, при небольшом изменении контента всё надо перегенерировать, что не очень удобно. Также, не у всех есть правая колонка, не у всех, у кого есть, она работает в полной мере (кликабельна и отслеживает и показывает текущее положение страницы статьи). Не у всех дерево меню имеет необходимую глубину вложенности. Не все легко кастомизируются стилями. И еще много разных "не все". Была сделана попытка большую часть этих недостатков (всё субъективно, конечно) устранить.
vbcfg.json
файле и в отдельных .html
или .md
файлах, и легко модифицируется без ребилда приложения.marked
(или аналог на выбор), для цветовой дифференциации программного кода в блоках — hightligh.js
. Для роутинга — vue-router
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>
false
openSidebar()
, closeSidebar()
и toggleSidebar()
методы на компоненте). По умолчанию: true
false
false
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.