Vuedoc Markdown Documentation Generator
Generate a Markdown Documentation for a Vue fileTable of Contents
- Install
- Features
- Command line usage
- Command line options
- Programmatic Usage
- Documentation Syntax
- Specific Tags for Props
- Using Plugins
- Examples
Install
This package is ESM only : Node 16+ is needed to use it and it must be imported instead of required.NPM
# using in your project
npm install --legacy-peer-deps @vuedoc/parser @vuedoc/md
# using in command line
npm install --legacy-peer-deps --global @vuedoc/parser @vuedoc/md
Yarn
# using in your project
yarn add @vuedoc/parser @vuedoc/md
# using in command line
yarn 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
# display the Vuedoc Markdown version
vuedoc-md --version
# this print documentation in the standard output
vuedoc-md components/textarea.vue
# generate a Markdown documentation in a file docs/textarea.md
vuedoc-md components/textarea.vue --output docs/
# generate a Markdown documentation all components
vuedoc-md components/*.vue --output docs/
# update the API section of README.md with generated documentation
vuedoc-md components/textarea.vue --section "API" --output README.md
# combine generated documentations of all components into one
vuedoc-md --join components/*.vue --output README.md
# using pipe
cat components/textarea.vue | vuedoc-md
# using a configuration file
vuedoc-md --config vuedoc.config.js components/*.vue
# using the configuration file vuedoc.config.js
vuedoc-md -c components/*.vue
Bellow an output sample of test/fixtures/textarea.example.vue:
````md
MyTextarea
Author: Arya StarkThe custom HTML
<textarea>
component.- license - MIT
Slots
| Name | Description | | --------- | --------------------------------------- | |label
| Use this slot to set the label |
| default
| Use this slot to set the textarea value |Props
| Name | Type | Description | Default | | --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | |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. | |
| id
required | string
| Defines a unique identifier (ID) which must be unique in the whole document. | |
| disabled
| boolean
| This Boolean property indicates that the user cannot interact with the control. | false
|
| theme
| TextareaTheme
| Define a custom theme for the component. | new DefaultTextareaTheme()
|Events
| Name | Description | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |input
| Fired when the value is changed.Arguments
value: string
— The updated value
keyup
| Fired when a key is released.Arguments
event: KeyboardEvent
— Object describes a user interaction with the keyboardevent.code: DOMString
— The code value of the physical key represented by the eventevent.key: DOMString
— The key value of the key represented by the event
Methods
Textarea.replace()
Thereplace()
method returns a new string with some or all matches of a
pattern
replaced by a replacement
. The pattern
can be a string or a
RegExp, and the replacement
can be a string or a function to be called for
each match. If pattern
is a string, only the first occurrence will be
replaced.The original string is left unchanged.
Example
const p = 'The quick brown fox jumps over the lazy dog. If the dog reacted, was it really lazy?';
const regex = /dog/gi;
console.log(p.replace(regex, 'ferret'));
// expected output: "The quick brown fox jumps over the lazy ferret. If the ferret reacted, was it really lazy?"
console.log(p.replace('dog', 'monkey'));
// expected output: "The quick brown fox jumps over the lazy monkey. If the dog reacted, was it really lazy?"
Syntax
const newStr = str.replace(pattern|substr, newSubstr|callback)
Parameters
str: unknown
newSubstr: String
pattern: RegExp
substr: String
callback: Function
Return value
A new string, with some or all matches of a pattern replaced by a replacement. ````
Command line options
-j, --join # Combine generated documentation for multiple component files into only one
-c, --config <filename> # Use this config file (if argument is used but value is unspecified, defaults to vuedoc.config.js)
-l, --level <integer> # Set the title level. An integer between 1 and 6
-w, --wordwrap <integer> # The width of the text before wrapping to a new line. Set to `false` to disable word wrapping. Default is `80`
-o, --output <file or dir> # The output directory. If absent, the STDOUT will be used
-s, --section <section name> # Inject the generated documentation to a section. Works with `--output file`
--ignore-name # Ignore the component name on parsing
--ignore-description # Ignore the component description on parsing
--ignore-keywords # Ignore the component keywords on parsing
--ignore-slots # Ignore the component slots on parsing
--ignore-props # Ignore the component props on parsing
--ignore-computed # Ignore the component computed properties on parsing
--ignore-data # Ignore the component data on parsing
--ignore-methods # Ignore the component methods on parsing
--ignore-events # Ignore the component events on parsing
Overwrite Vuedoc Parser configuration using
vuedoc.config.js
// vuedoc.config.js
import { Loader } from '@vuedoc/parser';
import { PugLoader } from '@vuedoc/parser/loaders/pug';
export default {
output: 'docs/',
parsing: {
features: ['name', 'description', 'keywords', 'slots', 'model', 'props', 'events', 'methods'],
loaders: [
Loader.extend('pug', PugLoader),
],
},
};
And then:
vuedoc-md --config vuedoc.config.js components/*.vue
# or
vuedoc-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 | I18n labels for translation. See @vuedoc/md/I18n
|Usage
import { renderComponent } from '@vuedoc/md';
const options = {
join: true,
filenames: [
'components/input.mixin.vue',
'components/checkbox.vue',
],
};
renderComponent(options)
.then((document) => console.log(document))
.catch((err) => console.error(err))
Overwrite the default Vuedoc Parser configuration
import { renderComponent } from '@vuedoc/md';
import { TypePugLoader } from '@vuedoc/parser/loaders/pug';
import { Loader } from '@vuedoc/parser';
const options = {
filenames: [
'test/fixtures/checkbox.vue',
],
parsing: {
features: ['name', 'description', 'keywords', 'slots', 'model', 'props', 'events', 'methods'],
loaders: [
Loader.extend('pug', TypePugLoader),
],
},
};
renderComponent(options)
.then((document) => console.log(document))
.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
export default {
name: 'CheckboxInput',
props: {
/**
* The input format callback
* @public
*/
format: Function,
},
methods: {
/**
* This will be ignored on parsing and rendering
* @private
*/
validate() {},
/**
* This will be ignored on parsing and rendering
* @protected
*/
commit() {},
},
};
Specific Tags for Props
You can assign a reference to a type using@typeref {url}
Example
export default {
props: {
/**
* UI Schema Descriptor to use for rendering.
*
* @typeref https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object
*/
descriptor: {
type: Object,
},
},
};
This will render:
````md | Name | Type | Description | | -------------| ---------------------------------------------------------------------------------------------------- | ------------------------------------------- | |
descriptor
| Object
| UI Schema Descriptor to use for rendering. |
````You can also define
typeref
for union type:export default {
props: {
/**
* Initial input value
* @typeref https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
* @typeref https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
*/
value: {
type: [Number, String],
},
},
};
Using Plugins
To use a plugin, it needs to be added to thedevDependencies
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:$ npm add -D @vuedoc/plugin-vue-router
// vuedoc.config.js
import { Loader } from '@vuedoc/parser';
import { VueRouterPlugin } from '@vuedoc/plugin-vue-router';
export default {
output: 'docs/',
parsing: {
plugins: [
VueRouterPlugin,
],
},
};
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-vuedocrollup-plugin-vuedoc
: https://github.com/h-ikeda/rollup-plugin-vuedoc
Contribute
Please follow CONTRIBUTING.md.Versioning
Given a version numberMAJOR.MINOR.PATCH
, increment the:MAJOR
version when you make incompatible API changes,MINOR
version when you add functionality in a backwards-compatible manner,
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.