vuepress-plugin-component-catalog

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',
      });
    },
  },
};

How to use with Vuex?

Please use .vuepress/enhancedApp.js. In the future, if you are using Nuxt.js, it will be loaded automatically.

How do you use sass resource loader?

Please use VuePress Build Pipeline.

Refer to the project in the example directory.

How to use with UI framework?

Sorry, I haven't tried it yet. I'm planning to make samples.

Probably I will use .vuepress/enhancedApp.js.

Example

See example directory.

• Vue Cli v3
• Nuxt.js

In the future

There is such an idea.