Vue Component Development Kit

# VuePress Plugins

The Vue Component Development Kit also comes with several VuePress (opens new window) plugins whose goal it is to document and showcase your components. There are currently two plugins.

  1. API Documentation Plugin: This plugin makes it easy to render API documentation of your components. It works by parsing your *.vue–files.
  2. Component Demo Plugin: This plugin allows you to render a component demo alonside the source code for the demo. It works by using the built-in syntax highlighing capabilities of VuePress.

You can use those two plugins alone or in combination in order to nicely document your components. Both plugins are using on this page in order to document every component.

# API Documentation Plugin

@vue-cdk/vuepress-plugin-api is a VuePress (opens new window) plugin that generates API documentation for your single file components.

The plugin works by parsing your *.vue–files. After your *.vue–files have been parsed the plugin generates VuePress–pages.

Under the Hood

Under the hood this plugin uses vuese (opens new window). Usually just adding normal comments (if at all) to your components is good enough. For the special cases vuese has a special comment syntax. You can try it out using vuese Explorer (opens new window).

# Installation

You install this plugin via NPM – just like any other VuePress–plugin:

$ npm install @vue-cdk/vuepress-plugin-api --save-dev

# Usage

Now you have to add @vue-cdk/vuepress-plugin-api to your .vuepress/config.js–file:

module.exports = {
  plugins: [
    [
      '@vue-cdk/vuepress-plugin-api', {
        items: [
          {
            localPath: '/path/to/a/component/button.vue',
            path: 'api/button'
          }
        ]
      }
    ]
  ]
}

# items–Option

items must be an array of objects. Each item must have the following shape:

  • localPath: Absolute path to a single file component
  • path: Relative path for the API documentation for the correspoding component.

# renderer–Option (optional)

After a *.vue–file has been parsed it is the renderers job to actually create a human readable API documentation page. You may specify a different renderer. The default one should be good enough for most scenarios though.

# indexPath–Option

@vue-cdk/vuepress-plugin-api is able to automatically generate a page that lists all documented components and allows a developer to quickly navigate to API pages. You do that by setting an indexPath like this:

module.exports = {
  plugins: [
    [
      '@vue-cdk/vuepress-plugin-api', {
        indexPath: 'api/README.md',
        items: [/* … */]
      }
    ]
  ]
}

From now on /api/ will always be a page that lists all of your documented components. To see how such an index page looks like simply visit the API index page of this site.

# Example

Any component API documentation on this site has been generated by using @vue-cdk/vuepress-plugin-api. For your convenience here are a few direct links for some documented components:

# Component Demo Plugin

This plugin makes it easy to demo your components alongside with nicely rendered source code.

# Installation

You install this plugin via NPM – just like any other VuePress–plugin:

$ npm install @vue-cdk/vuepress-plugin-demo --save-dev

# Usage

Now you have to add @vue-cdk/vuepress-plugin-demo to your .vuepress/config.js–file:

module.exports = {
  plugins: [
    [
      '@vue-cdk/vuepress-plugin-demo', { /* options (see below) */ }
    ]
  ]
}

By default, @vue-cdk/vuepress-plugin-demo will recursively look for files in the current working directory that match the pattern **/__examples__/**/*.vue.

# Displaying a Demo

You can display a demo for your any of your examples by using the Demo–component:

## Normal Button Demo

<Demo for="buttons/normal.vue" />

A demo looks like this:

Show Code
 
<template>
  <div class="box">
    <button ref="button" @click="toggle">Toggle 'clean' Popover</button>
    <CPopover
      ref="popover"
      placement="bottom"
      :target="() => $refs.button"
      with-arrow
      theme="clean"
    >
      <CPopoverContent>I am a Popover. Wheeee. 😉</CPopoverContent>
    </CPopover>
  </div>
</template>

<script>
import '@vue-cdk/popover/themes/clean.css'
export default {
  methods: {
    toggle() {
      this.$refs.popover.toggle()
    },
  },
}
</script>

<style scoped>
.box {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 200px;
}
</style>

If you are using the default options then this assumes the following directory structure:

.
├── packages
│   ├── buttons
│   │   ├── __examples__
│   │   │   ├── normal.vue
│   │   │   └── …
│   │   └── …
│   └── …
└── …

Nesting

The assumed directory structure above is not telling the whole story. For example the directory packages can have any name. It does not matter.

The example from above will work with any directory structure that has (anywhere) a directory called buttons that has a child directory called __examples__ in which is a file called normal.vue.

You can have more directories inside any __examples__ directory.

# Options

If you don't like the defaults you can tweak the options of @vue-cdk/vuepress-plugin-demo. The options–object should conform to the following shape:

// Normalized options type
export interface _Options {
  // A globby-pattern used to determine which examples should be 'demoable'
  examplesPattern: string
  // The directory used as a starting point for the search for examples
  cwd: string
  // Returns the package name of an example
  packageNameFromPath(path: string): string
  collectionPathComponentsFromPath(path: string): string[]
  exampleNameFromPath(path: string): string
  // Options for the Playground Button Integration
  // This defaults to `false` – which means that no playground button is displayed.
  playground: false | _PlaygroundOptions
}

export interface _PlaygroundOptions {
  // The package.json as a JS-object of the project that will be generated on the fly.
  package: { [key: string]: any },
  setupModule: {
    // The code of the setup module. The code must export a function by default. This
    // function will be called with the Vue-constructor.
    // ```js
    // export default ({ Vue }) => {
    //    // configure Vue to fit your needs
    // }
    // ```
    code: string
  }
}

// Type that represents the 'raw' options we support
export type Options = Partial<_Options>
Playground