vue-cli-plugin-docs
v1.0.2
Published
vue-cli plugin to generate readme files based on .vue file docs tags.
Downloads
33
Readme
vue-cli-plugin-docs
documentation consolidator plugin for vue-cli
Purpose
The goal of this project is to provide a way to store your vue components documentation within your single file format and then compile it into a single README.md file for distribution. Since Vuter already supports syntax highlighting for markdown inside a <docs></docs>
tag it allows us to keep a components documentation inside the same file we define our component.
<docs>
# My Component Documentation
</docs>
<template>
...
</template>
<script>
export default {
name: 'MyComponent'
}
</script>
<style>
</style>
Then when we are ready to generate our documentation, this plugin gathers up all of these components documentation and combines them into a single README.md file
npm run document
Installing in an Already Created Project
vue add vue-cli-plugin-docs
Configurations
The vue-cli-plugin-docs plugin allows for the following configurations to be added to your vue.config.js file inside the following location.
module.exports = {
pluginOptions: {
docs: {
// Configurations go here...
}
}
}
auto
If you want the plugin to generate your README each time you execute a npm run build
command, add the auto: true
configuration.
module.exports = {
pluginOptions: {
docs: {
auto: true
}
}
}
This value is false
by default.
outputDir
Be default the plugin places your combined README file in the root of the vue working directory. If you want to change this to another location you can override this by setting the outputDir
configuration.
const { resolve } = require('path');
module.exports = {
pluginOptions: {
docs: {
outputDir: resolve(__dirname, '/dist'))
}
}
}
Note:
This expects an absolute path. Use path.resolve and the __dirname to get to the root directory.
fileName
Be default the plugin generates a file with the name README.md. If you want to change this to a different file name you can override this by setting the fileName
configuration.
const { resolve } = require('path');
module.exports = {
pluginOptions: {
docs: {
fileName: "NotReadme.md"
}
}
}
Generating the documentation file.
As stated above, if you set the auto
configuration to true
then the plugin will generate the file every time you run nmp run build
. But if you do not want this process to run automatically and would prefer to generate the file on demand you can execute the following command:
npm run document
or
vue-cli-service document
This will start the process of gathering up the .vue file docs sections and combining them into the single file.
What this project is NOT
We are not trying to compete with Vue Styleguidist or vue-docgen-cli as these are both excellent products that can offer you JDOC and Prop extraction along with a React driven hot reload feature. My goal in this project was simple, I did not need all of those features and simply wanted a way to keep the documentation markdown for my components in the same file as my component, and then extract it during build time into a full README.md file for distribution. I thought someone else might find this useful as well so decided to create this package and share it on npm.
Please do not ask me to add features such as JDOC extraction or Component Prop mapping as I have no intentions of adding these features. I prefer full control over my documentation markdown and simply wanted a way to organize it better without losing the full README document. If you like the overall plugin and want JDOC support, feel free to Fork this repo and add it in for yourself.
I am not saying I won't add features if requested, just please understand that I am not trying to recreate an existing product.
Some Suggestions
Since the plugin starts at the root folder and processes files in each folder, then that folders subdirectories, If you want a Table of Contents or main head sections for your README.md file I suggest adding that markdown in the App.vue
file or whatever your main entry point .vue file is. This will usually be at the root of your src
folder.