DEV Community

altrusl
altrusl

Posted on

Vuesence Book - documentation system component

#vue #javascript

Hello guys

VB-preview

A couple of times I needed to install a simple help system on the site. Unpretentious, with three columns - the general menu, the current article and the content menu of the article. The search for the ready-to-use component/library did not lead to success. Therefore, I had to write my own, which i'de like to share.

Most existing documentation systems are static site generators. That is, with a small change in the content, everything needs to be regenerated, which is not very convenient. Also, not every one of them has a right-hand column, not everyone who has it works as needed (is clickable and tracks and highlights the current position on the article’s page). Not everyone has a tree menu with the necessary nesting depth. Not everyone is easily customizable with CSS styles. And a lot of other "not everyone." An attempt was made to eliminate most of these shortcomings (everything is subjective, of course).

Features

  • Lightweight (30KB in UMD with Markdown in gzip in the browser version)
  • User-friendly template
  • Fully styled by custom CSS
  • Convenient for use as an embedded documentation/help systems component
  • Content format - HTML and Markdown. The menu structure and article content are located in the vbcfg.json file and in separate.html or .md files, and can be easily modified without rebuilding the application.
  • Optional article preloading
  • Optional vue-router - allows users to bookmarks in the browser individual articles
  • Initially does not have dependencies (libraries). marked, hightligh.js and vue-router are optional
  • Unlimited nesting levels of menu items. The right menu of article content is automatically generated out of H1-H6 tags.

SEO was not required, so this issue was not considered. There are external tools and libraries that can help with that.

The vuesence-book component can be used both in the Node.js application and in the browser as a stand-alone js script.

Example of usage as a script:

<!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.4.50"></script>

            <link rel="stylesheet" href="https://unpkg.com/browse/@vuesence/book@0.4.50/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">
                <vuesence-book
                    header-title="My Book"
                    article-path="pages/"
                    :use-router="false"
                />
            </div>
        </body>

        <script>
            new Vue({ el: '#app' })
        </script>

    </html>
Enter fullscreen mode Exit fullscreen mode

Links

NPM

GitHub

You can experiment with Vuesence Book in the sandbox - https://codesandbox.io/s/vuesence-book-0rfh5 (the version there might be slightly outdated)

Detailed component documentation is here - (https://altrusl.github.io/vuesence-book/)
Documentation site is an example of the Vuesence Book launched in a browser mode (100/95 points on PageSpeed Insight, by the way, without network optimization).

Bugs, issues and contributions are welcome
If you like it - give it a GitHub star

Top comments (0)