Vue.js компонент для справки/документации

    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.

    Похожие публикации

    AdBlock похитил этот баннер, но баннеры не зубы — отрастут

    Подробнее
    Реклама

    Комментарии 1

      +1
      Неужели html/css для такой задачи не хватает?

      Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

      Самое читаемое