The Situation

Vuepress is simple.

Being simple is rather difficult. In the case of Vuepress, the difficulty can show up in unexpected places.

Starting with Vuepress is simple enough. Equally simple is enabling navigation on your site at multiple levels through a “sidebar” and/or a “navbar”. Specifically for the sidebar - you can enable in by adding a couple of lines in /docs/.vuepress/config.js.

module.exports = {
  //...
  themeConfig: {
    sidebar: [
      { title: "Home", children: [""] },
      {
        title: "Misc",
        children: ["more"],
      },
    ],
  },
  //...
};

The above change will create a sidebar for your site with links under Home and Misc. The title of links will be either -

• the title of the page (or)
• the first header element within the markdown files that the links point to

This is how it looks -

As you can see: the H2 headers will be links grouped below the file links.

But, what if you need to do more -

1. you want to create different sidebars for different pages. For e.g. if you are creating a site that has a bunch of different guides instead of one guide with multiple chapters. When you go to specific pages (which are represented as folders in Vuepress root folder), the navigation links have to change to point to different markdown files in a specific folder
2. you may want to continue having H2 behaviour be Vuepress default - show the links within the specific markdown files
3. you don’t want to write links to all the files by hand. Instead you want the system to automatically “see” the content to be linked

In a recent project I needed the “Admin”, “Developer” and other folders to have their own sidebars with navigation links. -

This sidebar is slightly different from Vuepress default, which seemingly assumes that all of the content is one big happy family. Vuepress by default enables links just point to the different markdown files in the document root, and to the H2 elements when the parent links are expanded.

Solutions

Let’s look at how we can customise sidebar in Vuepress.

Vuepress is after all powered by Vue - so customisation is not really a complex problem. However, I did not find this as straight forward as something like Gridsome. In Gridsome you just create a component for navigation like any sane developer and the system will exactly do what it has to - render the navbar.

Vuepress’s navbar is driven by config (and if applicable, plugins) - so this seemed not so elegant(!?) at first. But as always - all you need to solve world’s problems are good docs and some time.

Given below are three solutions that I tried to different degrees of success. The solution that worked for me is at the end because I am heartless and believe in making people scroll.

Solution 1. Use vuepress-plugin-auto-sidebar plugin

The plugin vuepress-plugin-auto-sidebar seemed to do exactly what I wanted.

To install a plugin in Vuepress, all you have to do is -

1. Install the package using npm/yarn
2. Use the plugin in config

Let’s get this going. Go to Vuepress folder and install package.

npm install --save vuepress-plugin-auto-sidebar

Include plugin in /docs/.vuepress/config.js-

module.exports = {
  // ...
  plugins: {

"vuepress-plugin-auto-sidebar": {
      titleMap: {
        "salesforce-for-students": "Salesforce for Students",
        "pd1-guide": "Platform Developer I Certification Guide",
        "admin-guide": "Admin Certification Guide",
        "why-learn-salesforce": "Why Learn Salesforce?",
        misc: "Miscellany"
      }
    },
// ...
}

This configuration will provide custom titles for the different folders and automatically pick up the files within the folder to create distinct, dynamic navigation bars.

In the ideal world, this should have been it and I should not have been sitting around to create a blog post about all the circus. But hey - ideal world is not exciting.

1. Getting started was bit of a bother. The documentation of the package is in Chinese and there are not many examples. Google translation helped to an extent
2. I could not quite figure out how autoNext and autoPrev worked. My files were not exactly sorted in the folder and sort order of the links in the sidebar was messed up
3. There were random failures. You could never say when sidebars generation failed (silently), and for the life of me, I could not figure out why. With dozens of files in different folders, I was quite frustrated with all the cut/pasting of content just to see what caused the program to fail
4. If you have a sub-folder with a README in the root, the README does not show in the navigation. This is expected as per Vuepress, but I could never say when the README appeared as a separate link and when it wouldn’t

Solution 2: Use vuepress-bar

vuepress-bar was another ready solution that seemed promising.

First, install the package.

npm i --save vuepress-bar

Next, include the plugin in /docs/.vuepress/config.js -

const getConfig = require("vuepress-bar");

module.exports = {
  themeConfig: {
    ...getConfig(`${__dirName}/..`),
  },
};

That’s it - you should have the new sidebars working. This worked more reliably than solution (1), but I could not figure out how to generate distinct sidebars for indidvidual content folders. All links appeared under one title - which was not ideal for my case.

Consider using this library if you just want a dynamic sidebar (and/or a navbar).

Solution 3: Go custom

My final solution was just doing everything myself. This was not as scary as it initially appeared - all it took was a couple of lines of code.

Get started by doing changes in /docs/.vuepress/config.js -

const fs = require("fs");
const path = require("path");

module.exports = {
  //...
  themeConfig: {
    sidebar: {
      "/why-learn-salesforce/": getSideBar(
        "why-learn-salesforce",
        "Why Salesforce?"
      ),
      "/admin-guide/": getSideBar("admin-guide", "Admin Certification Guide"),
      "/pd1-guide/": getSideBar("pd1-guide", "PD1 Certification Guide"),
      "/salesforce-for-students/": getSideBar(
        "salesforce-for-students",
        "Salesforce for Students"
      ),
    },
  },
  //...
};

function getSideBar(folder, title) {
  const extension = [".md"];

  const files = fs
    .readdirSync(path.join(`${__dirname}/../${folder}`))
    .filter(
      (item) =>
        item.toLowerCase() != "readme.md" &&
        fs.statSync(path.join(`${__dirname}/../${folder}`, item)).isFile() &&
        extension.includes(path.extname(item))
    );

  return [{ title: title, children: ["", ...files] }];
}

And voila, you have the brand new sidebar -

You can see that -

1. There’s a distinct sidebar for each folder - first level links are the files within the folder
2. Links to README and other files are consistent

Here’s a distilled-down version of my experience with Vuepress.

The Situation

I create static sites that are “real” websites. Typically the following factors in a static site generator help -

1. A cool, easy-to-customise home page
2. Themes/starter projects that make life easy
3. Plugins that can extend functionality of core software

Although I had played around Vuepress quite a bit, I always ended up choosing non-Vue technologies like Hugo, or Vue-based static site generators like Gridsome or Saber.land.

More recently however, I decided to have this long drawn out project to create a free tutorial website. With great delight and big plans, I chose Vuepress.

This is that true story.

What exactly is Vuepress?

A Vue-based static site generator, which is created by Evan Yu and supported by the Vue team. If that is not enough to get you going, there are other factors too. Read on.

Vuepress was created for documentation sites but has official themes/plugins to create a blog as well.

• Create documentation sites
• Create full-scale websites (we will get back to this point)
• Create blogs
• Create eCommerce sites
• Make sites interactive with the power of Vue

Vuepress is simple, provides a standard experience, (kind of) easy to configure and easy to get started.

Getting Started on Vuepress

Create a project folder and install Vuepress.

mkdir awedocs
cd awedocs
yarn init
yarn add -D vuepress

And then.. be prepared to act surprised - because there is nothing really there. There is little to see fresh out of the box. We need a few more steps to get there.

Open the awedocs folder in your VSCode. Create a sub directory called docs in the root folder. Then, create a file named README.md in docs folder. Enter following content in the file..

Hello world

md or markdown files will contain the content of your site. This file should be good for initial tests.

Open package.json and enter scripts to run Vuepress. Your entire file may look like below -

{
  "name": "awedocs",
  "version": "0.0.1",
  "description": "Awesome docs.",
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  },
  "main": "index.js",
  "repository": "https://github.com/techformist/awedocs",
  "author": "Prashanth Krishnamurthy",
  "license": "MIT",
  "devDependencies": {
    "vuepress": "^1.2"
  },
  "dependencies": {}
}

Go back to command prompt, and issue the command ..

yarn dev

.. and ta da - you have your Vuepress site up and running.

You can make a few smart observations -

1. Vuepress is minimal (at least in the beginning)
2. Vuepress comes with a default theme
3. Content and presentation layer is well isolated with the presentation layer

This means that -

1. you can get started really really quickly. Install Vuepress -> start creating documents / blog posts
2. you don’t need to learn Vue/Vuepress to use Vuepress to create a documentation site or blog

Making Vuepress your own

The site generated so far is functional but too minimal. Let’s add some jazz.

Update README.md with following content -

---
home: true
heroImage: /images/dog.jpg
heroText: Awedocs
tagline: docs. docs. docs.
actionText: Get Started →
actionLink: /more
features:
  - title: Good
    details: Know everything.
  - title: Better
    details: Know something.
  - title: Best
    details: Know nothing.

footer: MIT Licensed
---

# Hello world!

The content between --- is called frontmatter. This tells Vuepress to mete out some special treatment to the file.

Now do two things to support above content -

1. Add a file called more.md alongside README.md.

   # Morrreee
   
   This is much more information than I can handle.
   

2. Create a new folder /docs/.vuepress/images. Save a sample image and name it dog.jpg.

Stop Vuepress dev server. Start it again.

yarn dev

You have something that resembles a typical website.

The /docs/.vuepress folder will have any and all customisations for your Vuepress instance. This includes -

• Vue Components
• Navigation bars
• Additional Javascript
• Styles

Content stays in the /docs folder.

Add more UI elements

Lets add a sidebar and navbar.

Create a file called /docs/.vuepress/config.js, which will house all the configuration for Vuepress. Introduce following content in the file -

module.exports = {
  base: "/",

  title: "awedocs",
  description: "Awesome docs",

  themeConfig: {
    label: "English",
    editLinkText: "Edit this page on GitHub",
    lastUpdated: "Last Updated",
    nav: require("./nav"),
    sidebar: [
      { title: "Home", children: [""] },
      {
        title: "Misc",
        children: ["more"],
      },
    ],
    repo: "techformist/awedocs",
    editLinks: true,
  },

  plugins: {
    "@vuepress/back-to-top": {},
  },
};

Create a file called .vuepress/nav.js.

module.exports = [
  {
    text: "Let Me Google",
    link: "https://google.com",
  },
  {
    text: "About",
    items: [
      { text: "About", link: "/about" },
      { text: "Terms", link: "/terms" },
    ],
  },
];

Restart Vuepress to see this -

Build and Deploy

Once you are ready, you do a simple -

yarn build

This will create a docs/.vuepress/dist folder. Upload this folder to your host and you are done!

What could I do next?

Well, sky’s the limit. Vuepress is based off Vue and Javascript - so you can do nothing short of magic.

There are a few things that can be highlighted here -

1. Add simple Vue components and interactivity

We can include interactive components in markdown.

Create a Vue component called AddNum.vue in docs/.vuepress/components/.

<template>
  <div>
    <div>
      <label for="a">Num 1</label>
      <input id="a" v-model="a" type="number" />
    </div>
    <div>
      <label for="b">Num 2</label>
      <input id="a" type="number" v-model="b" align="right" />
    </div>

    <div style="font-weight:bold; margin-top:15px">
      <div>
        <label for="sum">Sum =</label>
        <input id="sum" type="number" :value="sum" align="right" />
      </div>
    </div>
  </div>
</template>

<script>
  export default {
    data() {
      return {
        a: 0,
        b: 0,
      };
    },
    computed: {
      sum() {
        return +this.a + +this.b;
      },
    },
  };
</script>

<style lang="css">
  input {
    text-align: center;
  }
</style>

Include this component in more.md.

# Morrreee

This is much more information than I can handle.

But, I could do a sum for you.

<AddNum/>

See the magic of adding numbers on the fly.

Create even more complex components

Let us have a Vue gallery for our glorious site.

In the root folder do an install.

yarn add vue-gallery

Create /docs/.vuepress/Galleria.vue.

<template>
  <!-- code from https://www.npmjs.com/package/vue-gallery -->
  <div class="padme">
    <gallery :images="images" :index="index" @close="index = null"></gallery>
    <div
      class="image"
      v-for="(image, imageIndex) in images"
      :key="imageIndex"
      @click="index = imageIndex"
      :style="{
        backgroundImage: 'url(' + image + ')',
        width: '300px',
        height: '200px'
      }"
    ></div>
  </div>
</template>

<script>
  import VueGallery from "vue-gallery";

  export default {
    data: function () {
      return {
        images: [
          "https://dummyimage.com/800/ffffff/000000",
          "https://dummyimage.com/1600/ffffff/000000",
          "https://dummyimage.com/1280/000000/ffffff",
          "https://dummyimage.com/400/000000/ffffff",
        ],
        index: null,
      };
    },

    components: {
      gallery: VueGallery,
    },
  };
</script>

<style scoped>
  .image {
    float: clear;
    background-size: cover;
    background-repeat: no-repeat;
    background-position: center center;
    border: 1px solid #ebebeb;
    margin: 5px;
  }

  .padme {
    padding-top: 2.5em;
    padding-bottom: 2.5em;
  }
</style>

Include this component in our more.md.

# Morrreee

This is much more information than I can handle.

## Sum

But, I could do a sum for you.

<AddNum/>

## Gallery

Or, I could show a gallery. Click on the image to view full screen.

<Galleria/>

You have a fully functioning gallery!

Note that we did not add this component anywhere other than creating a vue file, nor did we use the component.

3. Use a Vue plugin

Since Vuepress has Vue behind the scenes, we could hop on to the same magic train for our own nefarious schemes.

Do yet another install.

yarn add vue-typed-js

Create a new Vue file - /docs/.vuepress/components/.

<template>
  <div>
    <vue-typed-js
      :strings="[
        'once',
        'twice',
        'thrice',
        'four times',
        'five times',
        'infinity'
      ]"
      :loop="true"
    >
      <h4 style="color:red">Going.. <span class="typing"></span></h4>
    </vue-typed-js>
  </div>
</template>

Again, add this new component to our more.md.

# Morrreee

This is much more information than I can handle.

## Sum

But, I could do a sum for you.

<AddNum/>

## Gallery

Or, I could show a gallery. Click on the image to view full screen.

<Galleria/>

## Typing Ahoy

I could even show this cool type simulator.

<TypeAhoy/>

You now have some typing magic :)

Custom themes and plugins

So far you have seen themes provided by default in Vuepress. You can extend the theme or use a theme developed by third parties.

Similarly, you can develop custom functionality using plugins. Vuepress provides a number of core-team and community maintained plugins that do everything from enabling a blog on your site to creating a sitemap, creating diagrams using MermaidJS, or displaying your content as a presentation.

See themes and plugins listed on Vuepress.tools.

That was easy. Time to go crazy?

Well, it depends. Vuepress has its positives and not-so-positives.

For starters -

1. Vuepress is easy to get started with. It’s out-of-box theme is great and anyone can get started in no time
2. Provides a great user experience (similar to a single page app)
3. It is easy to understand for non-techies. Provides a good isolation b/w content creation and presentation layers
4. Has the full power of Vue behind it - you can provide super interactivity using Vue components and plugins
5. Theming is quite strong
6. It has some good plugins. You can also roll out your own plugin quite easily

On the other hand..

1. Is not as flexible as more developer-friendly solutions like Gridsome. Yes, this is opinionated and YMMV
2. I struggled a bit to implement adhoc taxonomies
3. With dependency on Webpack, it does not lend itself well for lot of content
4. It has a big initial payload, which is increasingly viewed as something that we live with (but wanted to mention it anyway)

Starting a documentation site and using a couple of plugins was easy enough, but my experience customising Vuepress was not that great (again, this is a ‘me’ experience). I found Gridsome or Saber.land easier to understand and customise to my heart’s content.

That said, I will probably use Vuetify for all the documentation sites going forward since it is quite simple and fast to get started with.