Vuedoc Markdown Documentation Generator

Generate a Markdown Documentation for a Vue file

Table of Contents

• Install
• Features
• Command line usage
• Command line options
• Programmatic Usage
• Documentation Syntax
• Specific Tags for Props
• Using Plugins
• Examples
  • Generate a documentation for an SFC component
  • Generate a MDN-like documentation for a method
• Related projects
• Contribute
• Versioning
• License

Install

This package is ESM only : Node 16+ is needed to use it and it must be imported instead of required.

NPM

1# using in your project
2npm install --legacy-peer-deps @vuedoc/parser @vuedoc/md
3
4# using in command line
5npm install --legacy-peer-deps --global @vuedoc/parser @vuedoc/md

Yarn

1# using in your project
2yarn add @vuedoc/parser @vuedoc/md
3
4# using in command line
5yarn global add @vuedoc/parser @vuedoc/md

Features

• Generate documentation for component props
• Generate documentation for component data
• Generate documentation for computed properties with their dependencies
• Generate documentation for component events
• Generate documentation for component slots
• Generate documentation for component methods
• Support of JSDoc, Class Component, Vue Property Decorator, TypeDoc
• Support of @description, @desc and @example
• Composition API support (from version Vuedoc Parser 4.0.0-beta9)

Command line usage

1# display the Vuedoc Markdown version
2vuedoc-md --version
3
4# this print documentation in the standard output
5vuedoc-md components/textarea.vue
6
7# generate a Markdown documentation in a file docs/textarea.md
8vuedoc-md components/textarea.vue --output docs/
9
10# generate a Markdown documentation all components
11vuedoc-md components/*.vue --output docs/
12
13# update the API section of README.md with generated documentation
14vuedoc-md components/textarea.vue --section "API" --output README.md
15
16# combine generated documentations of all components into one
17vuedoc-md --join components/*.vue --output README.md
18
19# using pipe
20cat components/textarea.vue | vuedoc-md
21
22# using a configuration file
23vuedoc-md --config vuedoc.config.js components/*.vue
24
25# using the configuration file vuedoc.config.js
26vuedoc-md -c components/*.vue

Bellow an output sample of test/fixtures/textarea.example.vue:

1# MyTextarea
2
3**Author:** Arya Stark
4
5The custom HTML `<textarea>` component.
6
7- **license** - MIT
8
9## Slots
10
11| Name      | Description                             |
12| --------- | --------------------------------------- |
13| `label`   | Use this slot to set the label          |
14| `default` | Use this slot to set the textarea value |
15
16## Props
17
18| Name            | Type            | Description                                                                                                                                                  | Default                      |
19| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
20| `v-model`       | `string`        | Use this directive to create two-way data bindings with the component. It automatically picks the correct way to update the element based on the input type. |                              |
21| `id` *required* | `string`        | Defines a unique identifier (ID) which must be unique in the whole document.                                                                                 |                              |
22| `disabled`      | `boolean`       | This Boolean property indicates that the user cannot interact with the control.                                                                              | `false`                      |
23| `theme`         | `TextareaTheme` | Define a custom theme for the component.                                                                                                                     | `new DefaultTextareaTheme()` |
24
25## Events
26
27| Name    | Description                                                                                                                                                                                                                                                                                                                                       |
28| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29| `input` | Fired when the value is changed.<br/>**Arguments**<br/><ul><li>**`value: string`** — The updated value</li></ul>                                                                                                                                                                                                                                  |
30| `keyup` | Fired when a key is released.<br/>**Arguments**<br/><ul><li>**`event: KeyboardEvent`** — Object describes a user interaction with the keyboard</li><li>**`event.code: DOMString`** — The code value of the physical key represented by the event</li><li>**`event.key: DOMString`** — The key value of the key represented by the event</li></ul> |
31
32## Methods
33
34### Textarea.replace()
35
36The `replace()` method returns a new string with some or all matches of a
37`pattern` replaced by a `replacement`. The `pattern` can be a string or a
38RegExp, and the `replacement` can be a string or a function to be called for
39each match. If `pattern` is a string, only the first occurrence will be
40replaced.
41
42The original string is left unchanged.
43
44**Example**
45
46```js
47const p = 'The quick brown fox jumps over the lazy dog. If the dog reacted, was it really lazy?';
48const regex = /dog/gi;
49
50console.log(p.replace(regex, 'ferret'));
51// expected output: "The quick brown fox jumps over the lazy ferret. If the ferret reacted, was it really lazy?"
52
53console.log(p.replace('dog', 'monkey'));
54// expected output: "The quick brown fox jumps over the lazy monkey. If the dog reacted, was it really lazy?"
55```
56
57**Syntax**
58
59```typescript
60const newStr = str.replace(pattern|substr, newSubstr|callback)
61```
62
63**Parameters**
64
65- **`str: unknown`**
66
67- **`newSubstr: String`**<br/>
68  The String that replaces the substring specified by the specified regexp or
69  substr parameter. A number of special replacement patterns are supported; see
70  the "Specifying a string as a parameter" section below.
71
72- **`pattern: RegExp`**<br/>
73  A RegExp object or literal. The match or matches are replaced with newSubstr
74  or the value returned by the specified function.
75
76- **`substr: String`**<br/>
77  A String that is to be replaced by newSubstr. It is treated as a literal
78  string and is not interpreted as a regular expression. Only the first
79  occurrence will be replaced.
80
81- **`callback: Function`**<br/>
82  A function to be invoked to create the new substring to be used to replace the
83  matches to the given regexp or substr. The arguments supplied to this function
84  are described in the "Specifying a function as a parameter" section below.
85
86**Return value**
87
88A new string, with some or all matches of a pattern replaced by a replacement.

Command line options

1-j, --join                    # Combine generated documentation for multiple component files into only one
2-c, --config <filename>       # Use this config file (if argument is used but value is unspecified, defaults to vuedoc.config.js)
3-l, --level <integer>         # Set the title level. An integer between 1 and 6
4-w, --wordwrap <integer>      # The width of the text before wrapping to a new line. Set to `false` to disable word wrapping. Default is `80`
5-o, --output <file or dir>    # The output directory. If absent, the STDOUT will be used
6-s, --section <section name>  # Inject the generated documentation to a section. Works with `--output file`
7--ignore-name                 # Ignore the component name on parsing
8--ignore-description          # Ignore the component description on parsing
9--ignore-keywords             # Ignore the component keywords on parsing
10--ignore-slots                # Ignore the component slots on parsing
11--ignore-props                # Ignore the component props on parsing
12--ignore-computed             # Ignore the component computed properties on parsing
13--ignore-data                 # Ignore the component data on parsing
14--ignore-methods              # Ignore the component methods on parsing
15--ignore-events               # Ignore the component events on parsing

Overwrite Vuedoc Parser configuration using vuedoc.config.js

1// vuedoc.config.js
2import { Loader } from '@vuedoc/parser';
3import { PugLoader } from '@vuedoc/parser/loaders/pug';
4
5export default {
6  output: 'docs/',
7  parsing: {
8    features: ['name', 'description', 'keywords', 'slots', 'model', 'props', 'events', 'methods'],
9    loaders: [
10      Loader.extend('pug', PugLoader),
11    ],
12  },
13};

And then:

1vuedoc-md --config vuedoc.config.js components/*.vue
2# or
3vuedoc-md -c components/*.vue

See Vuedoc Parser documentation for parsing options.

Programmatic Usage

Options

Name	Type	Description
level	Integer	Set the title level. An integer between 1 and 6
output	String	The output of the documentation. Can be a directory or a Markdown file. If absent, the STDOUT will be used
section	String	Inject the generated documentation to a section. Works with options.output as Markdown file output
parsing	Object	Overwrite the default Vuedoc Parser configuration
join	Boolean	Combine generated documentation for multiple component files into only one
filenames	String[]	List of component filenames to parse and render. If options.join === true, options.filenames will parsing will be joined and rendered as a single component
wordwrap	Integer	The width of the text before wrapping to a new line. Set to 0 to disable word wrapping. Default is 80
labels	Record<I18nKey, String>	I18n labels for translation. See @vuedoc/md/I18n

Usage

1import { renderComponent } from '@vuedoc/md';
2
3const options = {
4  join: true,
5  filenames: [
6    'components/input.mixin.vue',
7    'components/checkbox.vue',
8  ],
9};
10
11renderComponent(options)
12  .then((document) => console.log(document))
13  .catch((err) => console.error(err))

Overwrite the default Vuedoc Parser configuration

1import { renderComponent } from '@vuedoc/md';
2import { TypePugLoader } from '@vuedoc/parser/loaders/pug';
3import { Loader } from '@vuedoc/parser';
4
5const options = {
6  filenames: [
7    'test/fixtures/checkbox.vue',
8  ],
9  parsing: {
10    features: ['name', 'description', 'keywords', 'slots', 'model', 'props', 'events', 'methods'],
11    loaders: [
12      Loader.extend('pug', TypePugLoader),
13    ],
14  },
15};
16
17renderComponent(options)
18  .then((document) => console.log(document))
19  .catch((err) => console.error(err));

See Vuedoc Parser documentation for parsing options.

Documentation Syntax

For the complete documentation syntax, please follow this link:

• Vuedoc Syntax: https://gitlab.com/vuedoc/parser#syntax

Example

1export default {
2  name: 'CheckboxInput',
3  props: {
4    /**
5     * The input format callback
6     * @public
7     */
8    format: Function,
9  },
10  methods: {
11    /**
12     * This will be ignored on parsing and rendering
13     * @private
14     */
15    validate() {},
16    /**
17     * This will be ignored on parsing and rendering
18     * @protected
19     */
20    commit() {},
21  },
22};

Specific Tags for Props

You can assign a reference to a type using @typeref {url}

Example

1export default {
2  props: {
3    /**
4     * UI Schema Descriptor to use for rendering.
5     *
6     * @typeref https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
7     */
8    descriptor: {
9      type: Object,
10    },
11  },
12};

This will render:

1| Name         | Type                                                                                                 | Description                                 |
2| -------------| ---------------------------------------------------------------------------------------------------- | ------------------------------------------- |
3| `descriptor` | [`Object`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)  | UI Schema Descriptor to use for rendering.  |

You can also define typeref for union type:

1export default {
2  props: {
3    /**
4     * Initial input value
5     * @typeref https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
6     * @typeref https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
7     */
8    value: {
9      type: [Number, String],
10    },
11  },
12};

Using Plugins

To use a plugin, it needs to be added to the devDependencies of the project and included in the plugins array in the vuedoc.config.js config file. For example, to provide support of Vue Router, the official @vuedoc/plugin-vue-router can be used:

1$ npm add -D @vuedoc/plugin-vue-router

1// vuedoc.config.js
2import { Loader } from '@vuedoc/parser';
3import { VueRouterPlugin } from '@vuedoc/plugin-vue-router';
4
5export default {
6  output: 'docs/',
7  parsing: {
8    plugins: [
9      VueRouterPlugin,
10    ],
11  },
12};

You can found the list of official plugins on the Vuedoc Parser documentation.

Examples

Vuedoc Markdown has been used to generate documentation of bellow components:

Generate a documentation for an SFC component

Component file	Markdown output
test/fixtures/checkbox.example.vue	test/fixtures/checkbox.output.md
test/fixtures/textarea.example.vue	test/fixtures/textarea.output.md

Generate a MDN-like documentation for a method

Component file	Markdown output
test/fixtures/mdn.event.example.vue	test/fixtures/mdn.event.output.md
test/fixtures/mdn.string.example.vue	test/fixtures/mdn.string.output.md
test/fixtures/mdn.regexp.example.vue	test/fixtures/mdn.regexp.output.md

Find more examples here: test/fixtures

Related projects

• jsdoc-vuedoc: https://github.com/ccqgithub/jsdoc-vuedoc
• rollup-plugin-vuedoc: https://github.com/h-ikeda/rollup-plugin-vuedoc

Contribute

Please follow CONTRIBUTING.md.

Versioning

Given a version number MAJOR.MINOR.PATCH, increment the:

• MAJOR version when you make incompatible API changes,
• MINOR version when you add functionality in a backwards-compatible manner, and
• PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

See SemVer.org for more details.

License

Under the MIT license. See LICENSE file for more details.