27.05.2020 10:54
gmtd 1 1600 Источник

VB-preview


Пару раз понадобилось встроить в сайт справочную систему. Простенькую, с тремя колонками — общее меню, текущая статья и меню содержания статьи. Поиски готового компонента/библиотеки не привели к успеху совсем. Поэтому пришлось написать свой, который предлагается к использованию.


Большинство существующих систем документирования представляют собой генераторы статичных сайтов. То есть, при небольшом изменении контента всё надо перегенерировать, что не очень удобно. Также, не у всех есть правая колонка, не у всех, у кого есть, она работает в полной мере (кликабельна и отслеживает и показывает текущее положение страницы статьи). Не у всех дерево меню имеет необходимую глубину вложенности. Не все легко кастомизируются стилями. И еще много разных "не все". Была сделана попытка большую часть этих недостатков (всё субъективно, конечно) устранить.


Особенности


  • Легкий (30KB в UMD с Markdown в gzip-e в браузерной версии)
  • Быстрый, юзер-френдли шаблон
  • Полностью стилизуемый кастомным СSS
  • Удобен для использования во встроенных системах документирования/справки
  • Формат контента — HTML и Markdown. Структура меню и контент статей располагается в vbcfg.json файле и в отдельных .html или .md файлах, и легко модифицируется без ребилда приложения.
  • Опциональная предзагрузка статей
  • Опциональный роутер — позволяет пользователям сохранять в закладки браузера ссылки на отдельные статьи
  • Изначально без зависимостей (библиотек). Для маркдауна подключается marked (или аналог на выбор), для цветовой дифференциации программного кода в блоках — hightligh.js. Для роутинга — vue-router
  • Вложенность пунктов меню неограничена. Правое меню контента статьи генерируется автоматически по H1-H6 тэгам.

SEO был не нужен, поэтому этот вопрос не рассматривался. Если понадобится — есть внешние средства, позволяющие "озрячить" поисковики, и не вносящие в проект и код приложения ненужную тяжесть.

Компонент vuesence-book можно использовать как в Node.js приложении так и в браузере, подключая скриптом.


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>

Browser 
<!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 элемента


VuesenceBook props
  • 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

Конфигурационный файл


Пример vbcfg.json 
{
    "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. Тип контента определяется по расширению файла.


Ссылки


NPM, GitHub


Поэкспериментировать с Vuesence Book можно в песочнице


Подробная документация по компоненту здесь
Этот же сайт представляет собой пример Vuesence Book, запущенного в режиме браузера (100/95 баллов на PageSpeed, кстати, без сетевой оптимизации).


Bugs, issues, feature and pull requests are welcome
Понравилось — GitHub star.