MIT License
A markdown-it plugin implemented with vue-docgen-api for parsing documentation comments of Vue components. It is used with the <vue-docgen />
tag.
npm install markdown-it-vue-docgen
Write your Vue component and add relevant comments:
<script lang="ts" setup>
import { defineExpose, ref } from 'vue'
withDefaults(
defineProps<{
title: string
/**
* This is an `optional` value
*/
type?: 'text' | 'number' | 'digit' | 'password' | 'textarea'
}>(),
{
type: 'text',
},
)
const emit = defineEmits<{
/**
* This is a `click` event
*/
(type: 'click', event: string | number): void
}>()
const value = ref('')
defineExpose({
/**
* This is the component property that I `expose`
* @type {string|number}
*/
a: value,
})
</script>
<template>
<!-- @slot This is a default slot -->
<slot />
<!-- @slot This is a slot with a `name` -->
<slot name="body" />
</template>
In your markdown file, use the <vue-docgen>
tag and provide the src:
<vue-docgen src="./Button.vue" />
The tag will parse and generate relevant markdown information:
You can provide a title attribute which will be added to the beginning of each line, which is useful for distinguishing multiple components:
<vue-docgen title="Button" src="./Button.vue" />
The generated markdown will be:
## Button Props
<!-- ... -->
## Button Events
<!-- ... -->
You can customize the component path being used by setting the plugin's options:
import { resolve } from 'node:path'
import vueDocgen from 'markdown-it-vue-docgen'
md.use(vueDocgen, {
dir: resolve(__dirname, '../../components/')
})
Then refer to the custom dir path using the ~
identifier:
<vue-docgen src="~/Button.vue" />
You can also set the container for the popup that displays the prop type. For example, you can customize the container using vue3-popup
loaded with vitepress
(assuming you have registered the popup
component globally):
md.use(vueDocgen, {
popup: (text, content) => `<popup content="${content}">${text}</popup>`
})