Display Vue examples inside VuePress documentation

Writing documentation with VuePress is a breeze! Not only does it have support for Markdown files that get automatically converted to HTML, but it also contains a big collection of Markdown extensions out-of-the-box, including syntax highlighting in code blocks. But that's not all, it also includes site search capability, i18n, custom themes, and the list goes on.

One of the best features though is that you can use Vue components directly inside your Markdown files, thus making it the perfect documentation tool for Vue projects.

What's often needed while documenting software projects is to display "live" examples along with the source code side-by-side. This is where vuepress-plugin-vue-example comes in. It's a VuePress plugin that uses Vue SFCs for displaying Vue examples inside VuePress documentation pages.

The plugin is inspired by a similar functionality available on the Vuetify documentation site.

How it works:

Upon initialization of the plugin you have to provide the folder in which all your examples reside. The examples will be just regular .vue SFC files.

// .vuepress/config.js
const VueExamplePlugin = require('vuepress-plugin-vue-example');

module.exports = {
  plugins: [
    VueExamplePlugin({
      // You need to provide a directory that all the example .vue files will be stored.
      // You can use sub-directories to separate examples into categories.
      componentsPath: '/examples/'
    })
  ],
};

Then inside your .md files you just have to include a vue-example component tag passing to the file prop the filename of your Vue example component (without the .vue extension)

<vue-example file="example" />

That's it!

There's now a section inside your VuePress page, containing the live example and the syntax highlighted contents of the template/script/style SFC tags.

You can check out vuepress-plugin-vue-example here.

Have fun writing docs with VuePress!

GIF