vue-docgen-cli
Generate documentation markdown files from VueJs components using the vue-docgen-api.
Install
Install the module directly from npm:
yarn add -D vue-docgen-cli
Usage
In a terminal window type the following command at the root of your project. If your components are in the src/components
folder, this will generate one .md
file per component.
yarn vue-docgen src/components/**/*.vue docs/components
Config
Command Line Args
vue-docgen
can take two nameless arguments. The components
glob to locate components and the destination
directory.
-w
or --watch
Should vue-docgen whatch for modifications of your components and update generated markdown files accordingly?
yarn vue-docgen -w
-c
or --config
Specify the path of your configuration file. By default, docgen will look for docgen.config.js
in the current folder.
yarn vue-docgen -c config/docgen.config.js
Config File
If you specify a docgen.config.js
file you can be more specific. But each of those configurations is optional.
const path = require('path')
module.exports = {
componentsRoot: 'src/components',
components: '**/[A-Z]*.vue',
outDir: 'docs',
apiOptions: {
...require('./webpack.config').resolve,
jsx: true
},
getDocFileName: (componentPath: string) =>
componentPath.replace(/\.vue$/, '.md'),
getDestFile: (file: string, config: DocgenCLIConfig) =>
path.join(config.outDir, file).replace(/\.vue$/, '.doc.md'),
templates: {
component: require('templates/component'),
events: require('templates/events'),
methods: require('templates/methods'),
props: require('templates/props'),
slots: require('templates/slots'),
functionalTag: '**functional**'
}
}
components
type: string | string[]
, default: "src/components/**/[a-zA-Z]*.{vue,js,jsx,ts,tsx}"
Glob string used to get all the components to parse and document.
outDir
type: string
, default: "docs"
The root directory for the generation of the markdown files
outFile
type: string
, optional
If you specify this, all documentation will be generated in one single page. The path of this file is relative to the outDir.
The following configuration will generate one single file: myDocs/components.md
module.exports = {
outDir: 'myDocs',
outFile: 'components.md'
}
componentsRoot
type: string
, default: path.dirname(configFilePath)
The folder where cli will start searching for components. Since the folder structure will be kept from source to destination, it avoids having uselessly deep scaffodlings.
src
└───components
├───Button.vue
├───CounterButton.vue
├───Functional.vue
└───Input.vue
If you simply use src/components/**/[A-Z]*.vue
as source glob and docs
as outDir, you will get this.
src
└───components
├───Button.vue
├───CounterButton.vue
├───Functional.vue
└───Input.vue
docs
└───src
└───components
├───Button.vue
├───CounterButton.vue
├───Functional.vue
└───Input.vue
Specifying componentsRoot: 'src/components'
and using **/[A-Z].vue
will skip the two useless levels of hierarchy.
apiOptions
type: DocGenOptions
, optional
Allows you to give vue-docgen-api some config. Most notably, you can specify wether your components contain JSX code and the alias configured in your webpack.
getDocFileName
type: (componentPath: string) => string
, default: (componentPath) => path.resolve(path.dirname(componentPath), 'Readme.md')
By default it will find the Readme.md
sibling to the component files. Use this to point docgen to the files that contain documentation specific to a component.
getDestFile
type: (file: string, config: DocgenCLIConfig) => string
, default: (file, config) => path.resolve(config.outDir, file).replace(/\.\w+\$/, '.md')
Function returning the absolute path of the documentation markdown files. If outFile is used, this config will be ignored.
watch
type: boolean
, default: false
Should vue-docgen keep on watching your files for changes once generation is done?
templates
type: Templates
, optional
An object specifying the functions to be used to render the components.
For example:
file: component.ts
export default function component(
renderedUsage: RenderedUsage,
doc: ComponentDoc,
config: DocgenCLIConfig,
fileName: string
): string {
const { displayName, description, docsBlocks } = doc
return `
# ${displayName}
${description ? '> ' + description : ''}
${renderedUsage.props}
${renderedUsage.methods}
${renderedUsage.events}
${renderedUsage.slots}
${docsBlocks ? '---\n' + docsBlocks.join('\n---\n') : ''}
`
}
And the partial for slots
import { SlotDescriptor } from 'vue-docgen-api'
import { cleanReturn } from './utils'
export default (slots: {
[slotName: string]: SlotDescriptor
}): string => {
const slotNames = Object.keys(slots)
if (!slotNames.length) {
return ''
}
return `
## Slots
| Name | Description | Bindings |
| ------------- | ------------ | -------- |
${slotNames
.map(slotName => {
const { description, bindings } = slots[slotName]
const readableBindings = // serialize bindings to display them ina readable manner
bindings && Object.keys(bindings).length
? JSON.stringify(bindings, null, 2)
: ''
return cleanReturn(
`| ${slotName} | ${description} | ${readableBindings} |`
) // remplace returns by <br> to allow them in a table cell
})
.join('\n')}
`
}
pages
type: Array<DocgenCLIConfig>
, optional
Allows to group components into pages. Each page will inherit its parent properties.
const path = require('path')
module.exports = {
componentsRoot: 'src/components',
outDir: 'docs',
pages: [
{
components: 'atoms/**/[A-Z]*.vue',
outFile: 'atoms.md'
},
{
components: 'molecules/**/[A-Z]*.vue',
outFile: 'molecules.md'
}
]
}
defaultExamples
type: boolean
, default: false
Generate example for components that have neither <docs>
block nor a markdown file to provide examples of usage.
cwd
type: string
, optional
Force the Current Working Directory. Useful in monorepos.
Change log
The change log can be found on the Changelog Page.
Authors and license
Bart Ledoux
MIT License.