Tutorial

An Introduction to VuePress

Published on April 16, 2018
    Default avatar

    By Joshua Bemenderfer

    An Introduction to VuePress

    While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.

    You may have heard of VuePress recently, it appeared almost overnight and shortly thereafter became Product of the Day on ProductHunt. What is it about VuePress that makes it so special? What is VuePress? Well, it’s effectively a static site generator. Particularly, a Vue.js-powered static site generator aimed toward building documentation websites. Why’s that so special? The creator, Evan You, has a knack for building incredibly simple but flexible software. After all, he made Vue.js. VuePress is no different. After running two commands, you’ll have a zero-configuration prerendered, SEO-friendly SPA with full Vue.js support. A few lines of config and it will be personalized to fit your needs.

    Getting Started

    Step 1: Install VuePress.

    $ npm install -g vuepress
    

    Step 2: Write something.

    Create README.md in a folder and write some markdown (mixed with Vue.js expressions!) in it.

    README.md
    ## Hello VuePress!
    
    _How are you doing?_
    > **I'm doing fine, thanks!**
    
    _Great, I was wondering what `49 + 32` is?_
    > **{{49 + 32}}**
    
    _Could you repeat that a few times?_
    
    > **Sigh...**
    <p v-for="i of 3">{{49 + 32}}</p>
    

    Run $ vuepress dev in that folder and visit the resulting URL. (It has hot module reloading!)

    The result should look something like this:

    The default VuePress look, with no sidebar or navbar.

    As you can see, if you’re familiar with Vue’s templating system at all, you’ll feel right at home with VuePress. Also, if you’re paying attention, you’ll see that headers in the page become anchors that you can link to, which comes in handy.

    Step 3: Build It.

    When you’re ready to publish your site, run $ vuepress build. The resulting output will be in .vuepress/dist, nicely built and minified with Webpack.

    But you’ll probably want to make a few tweaks first, won’t you? A single page is a bit boring.

    Post Metadata

    First things first, go ahead and create a couple more markdown files in your project directory.

    Page-1.md
    # This is Page 1
    
    Duis aute irure dolor in reprehenderit in voluptate velit esse
    cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
    proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
    
    Page-2.md
    # This is Page 2
    
    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
    tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
    consequat.
    

    If you check your browser now, you’ll notice that some magical next / previous post links have appeared. The text of those links will be the same as the first header in those posts. In this case, that means This is Page 1/2. That’s not quite what we want.

    Go ahead and add a YAML Front-matter block at the top of the two page markdown files.

    Page-1.md
    ---
    title: Page 1
    # We can even add meta tags to the page! This sets the keywords meta tag.
    # <meta name="keywords" content="my SEO keywords"/>
    meta:
      - name: keywords
      - content: my SEO keywords
    ---
    
    # This is Page 1
    
    ...
    
    Page-2.md
    ---
    title: Page 2
    ---
    
    # This is Page 2
    
    ...
    

    With that, your links should now say Page 1 and Page 2 instead of This is Page ....

    Here’s the full list of front-matter metadata.

    Adding a Sidebar

    Navigating with forward / next links is kind of inconvenient, isn’t it? Also, the pages seem kind of out-of-order. Wouldn’t it be nice if there was a sidebar or something that could solve both of those problems?

    VuePress’ default theme comes with support for a powerful sidebar, but to enable it, you’ll need to create a simple configuration file.

    Go ahead and create .vuepress/config.js in your project directory and enable the sidebar.

    .vuepress/config.js
    module.exports = {
      themeConfig: {
        sidebar: [
          '/',
          '/Page 1',
          '/Page 2'
        ]
      }
    }
    

    That’s all you need for a basic sidebar, but there are a variety of other configuration options as well.

    Enabling the Navbar

    So you’ve got pages and sidebars, but the site still feels a little bland. Why not spruce things up by adding a navbar and search functionality?

    .vuepress/config.js
    module.exports = {
      title: 'My VuePress Site',
    
      themeConfig: {
        sidebar: [
          ...
        ],
    
      }
    }
    

    Turns out all you need to do to create the navbar and search field is add a title to your site! Talk about convenient! And the search functionality works out-of-the-box!

    (There are a few other things you can do to configure the navbar, of course.)

    Using Vue Components

    Let’s kick things up a notch. The true power of VuePress lies in its ability to use Vue components in pages.

    Note, your Vue components must be SSR capable, so you shouldn’t do anything that modifies the DOM or interfaces with browser-only APIs outside of the mounted() hook or event listeners.

    Let’s create a Vue component that lets us increment and decrement a number. (Really important stuff here, folks.) VuePress automatically detects Vue components created in .vuepress/components, so let’s go ahead and create .vuepress/components/NumberModifier.vue

    .vuepress/components/NumberModifier.vue
    <template>
      <div class="number-modifier">
        <button @click="increment()">+</button>
        <strong> {{value}} </strong>
        <button @click="decrement()">-</button>
      </div>
    </template>
    
    <script>
    export default {
      props: ['start'],
    
      // We have to copy the value because we can't use v-model with
      // nothing to bind to.
      // (VuePress doesn't have support for reactive page variables at the moment.)
      data() {
        return {
          value: this.start
        }
      },
    
      methods: {
        increment() { this.value++ },
        decrement() { this.value-- }
      }
    }
    </script>
    

    And just like that, we can use it in any post. For example, Page-1.md

    Page-1.md
    ...
    # This is Page 1
    
    **Our Component:**
    <NumberModifier :start="5"></NumberModifier>
    
    Duis aute irure dolor in reprehenderit in voluptate velit esse
    cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
    proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
    

    A VuePress post with an embedded Vue component. The sidebar and navbar are enabled.

    The same method applies to any component. This makes it an excellent way to demonstrate the components you write inline with your documentation for them, or even build more advanced sites! It’s all up to you.

    Custom Themes

    Not everyone wants their static site to look just like every other one built with the same tools, so most likely you’ll eventually want to start customizing things.

    Basic modifications

    The default theme uses Stylus as its CSS preprocessor. If all you want to do is change a color or two, you can accomplish that by adding .vuepress/override.styl and modifying a few values in it. You could even add a few CSS overrides in there if needed.

    The default theme is basic enough that all you’ll probably want to change is the accent color.

    .vuepress/override.styl
    // Color configuration
    $accentColor = #3eaf7c
    $textColor = #2c3e50
    $borderColor = #eaecef
    $codeBgColor = #282c34
    
    // Layout configuration
    $navbarHeight = 3.6rem
    $sidebarWidth = 20rem
    $contentWidth = 740px
    

    Creating a new theme

    In VuePress, themes are just collections of Vue components and related assets. If you want to get started with your own theme, the easiest way is to eject the default theme using $ vuepress eject. All this does is copy the default theme files to .vuepress/theme.

    If you take a look at the default theme, you’ll discover that it’s incredibly easy to understand. Fewer than 25 files with an average of ~70 lines apiece. Basically no boilerplate.

    You can go ahead and start customizing the theme right off the bat. Components will be hot-reloaded just like the rest of your site! For more details on custom themes, take a look at the docs.

    Conclusion

    VuePress is just getting started, and I can already say it looks awesome. Even if you’re not planning on building anything with it right away, keep an eye on the offical docs. Things are only going to get better from here.

    Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

    Learn more about us


    About the authors
    Default avatar
    Joshua Bemenderfer

    author

    Still looking for an answer?

    Ask a questionSearch for more help

    Was this helpful?
     
    Leave a comment
    

    This textbox defaults to using Markdown to format your answer.

    You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

    Try DigitalOcean for free

    Click below to sign up and get $200 of credit to try our products over 60 days!

    Sign up

    Join the Tech Talk
    Success! Thank you! Please check your email for further details.

    Please complete your information!

    Get our biweekly newsletter

    Sign up for Infrastructure as a Newsletter.

    Hollie's Hub for Good

    Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

    Become a contributor

    Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

    Welcome to the developer cloud

    DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

    Learn more
    DigitalOcean Cloud Control Panel