vuepress-plugin-component-catalog

This plugin is for generating a component catalog of Vue.js. The catalog page is generated by adding it to the VuePress plugin.

Status: alpha

This plugin is for VuePress Next(v1.x.x).

Setup

Available in 2 steps.

Install

$ yarn add -D vuepress@next vuepress-plugin-component-catalog

Add plugin

.vuepress/config.js

module.exports = {
  // ...
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Components', link: '/components/' },
    ]
  },
  plugins: [
    ['vuepress-plugin-component-catalog'],
  ],
};

Scan the project and complete the setup automatically.

Depending on the project it may not work.

Docs block

This plugin uses custom blocks of SFC.

Basic example

<docs>
# Base Button

Can be written with Markdown.

VuePress markdown extensions are also available.

[[toc]]

When you write a component, it will be mounted and displayed.

<base-button>Sample Button</base-button>
</docs>

<template>
  <button type="button"><slot /></button>
</template>

<script>
export default {
  // ...
}
</script>

Code playgrounds

Code blocks tagged with @playground will be rendered as code examples:

<docs>
```html
@playground
<base-button variation="primary">Primary Button</base-button>
```
</docs>

You can use SFC syntax in a playground example:

<docs>
```html
@playground
<template>
  <BaseButton @click="handleClick">Primary Button</BaseButton>
</template>
<script>
  export default {
    methods: {
      handleClick() {
        alert('button clicked')
      }
    }
  }
</script>
```
</docs>

You can also use imports. Just make sure to use the correct path aliases:

<docs>
```html
@playground
<template>
  <BaseImage :src="logo"/>
</template>
<script>
  import logo from '@/assets/logo.png'
  export default {
    data() {
      return {
        logo
      }
    }
  }
</script>
```
</docs>

Options

module.exports = {
  plugins: [
    [
      'vuepress-plugin-component-catalog',
      {
        // All options
        rootDir: '<your project root dir>',
        include: ['**/components/**']  // Specify the target to create a catalog
        exclude: ['**/views/**', '**/App.vue']  // Specify a target that does not create a catalog

        distDirPrefix: 'components',

        alias: { // import path alias
          '@': \<your project alias\>,
        },
        vueCli: {  // vue cli option
          configPath: path.join(PROJECT_DIR, 'vue.config.js'),
        },
        nuxt: {  // nuxt option
          configPath: path.join(PROJECT_DIR, 'nuxt.config.js'),
        },
      },
    ],
  ],
};

`rootDir`(option)

type: string
default: process.cwd()

`staticDir`(option)

Directory path of static resources.

type: string
deafult: null

`include`(option)

Specify the target to create a catalog. Can use glob.

type: string or Array<string>

e.g.

{
  include: ['**/components/**'],
}

`exclude`(option)

Specify a target that does not create a catalog. Can use globs.

type: string or Array<string>

`distDirPrefix`(option)

type: string
default: components

It becomes the URL path.

http://localhost:8080/components/your-component

`vueCli.configPath`(option)

type: string
default: process.cwd() + vue.config.js

Please try to set it when the alias such as @ can not be resolved automatically.

`nuxt.configPath`(option)

type: string
default: process.cwd() + nuxt.config.js

Please try to set it when the alias such as @(~) can not be resolved automatically.

FAQ

What if an error occurs in the application?

It is not possible to process docs custom blocks, and errors may occur in the build of your application.

Please load and use the prepared webpack loader. Here is a sample.

Vue CLI v3

vue.config.js

module.exports = {
  // ...
  chainWebpack: config => {
    config.module
      .rule('docs')
      .oneOf('docs')
      .resourceQuery(/blockType=docs/)
      .use('through-loader')
      .loader('vuepress-plugin-component-catalog/dist/through-loader')
      .end();
  },
};

Nuxt.js

nuxt.config.js

module.exports = {
  // ...
  build: {
    extend(config) {
      config.module.rules.push({
        resourceQuery: /blockType=docs/,
        loader: 'vuepress-plugin-component-catalog/dist/through-loader',
      });
    },
  },
};