vue-sfc-md

read vue sfc, or sfc string, output md modules. @vuedoc/paser

Install

1npm i vue-sfc-md

Config

1const opts = {
2  encoding,
3  features,
4  loaders,
5  ignoredVisibilities,
6  jsx,
7  commentExtra,
8  removeEmptyColumns: true, // 是否需要移除空列
9  emptyFlags: ['-'], // 空列的判断标识，默认是['-']
10}
11
12parsed(vueFileStr, opts)
13
14// commentExtra
15// file commont map
16{
17  design: '自定义',
18  val: 'VAL'
19}

Usage

1const fs = require('fs')
2const path = require('path')
3const { parsed } = require('vue-sfc-md')
4/**
5 * 主线程
6 */
7async function main() {
8  const sourceStr = fs.readFileSync(path.join(__dirname, './Btn.vue'), 'utf8')
9
10  let docModules = await parsed(sourceStr, {
11    jsx: true,
12    removeEmptyColumns: true,
13    emptyFlags: ['-', '`false`'],
14  })
15
16  let sfcDoc = docModules
17    .filter((m) => !m.empty)
18    .map((m) => m.doc)
19    .join('\n')
20  console.log(sfcDoc)
21}
22
23main()

Support

file top comment

支持文件注释解析 title 文件标题，h1

1<!--
2* Button组件的描述部分，描述补充，介绍部分
3* @title 组件Title
4* @design 统一button的表现
5* @expect
6  1. 测试
7  2. 看看
8-->
9<template></template>

slot bind

1<!--
2* 这是一个title slot
3* @bind `{ size, type }`大小和类型
4-->
5<slot name="title" v-bind="{ size, type }"></slot>

prop optional

1{
2  /**
3  * 尺寸
4  * @optional mini|small|medium|large
5  */
6  size: {
7   type: String,
8   default: 'medium',
9  },
10}

Example

a example sfc:

1<!--
2* Button组件
3* @design 统一button的表现
4* @expect 按钮统一，提供多种类型
5-->
6<template>
7  <div class="na">
8    这是一个btn
9    <header class="header">
10      <!--
11      * 这是一个title slot
12      * @bind `{ size, type }`大小和类型
13      -->
14      <slot name="title" v-bind="{ size, type }"></slot>
15    </header>
16
17    <!-- 这是默认的slot -->
18    <slot></slot>
19  </div>
20</template>
21
22<script>
23export default {
24  name: 'button',
25  model: {
26    prop: 'value',
27    event: 'change',
28  },
29  props: {
30    /**
31     * 尺寸
32     * @optional mini|small|medium|large
33     */
34    size: {
35      type: String,
36      default: 'medium',
37    },
38    /**
39     * 禁用状态
40     */
41    disabled: Boolean,
42  },
43  methods: {
44    /**
45     * 点击事件
46     * @param {Event} event - description event.
47     */
48    click(event) {
49      let obj = { key: 'k', value: 'v' }
50      /**
51       * 变化事件
52       * @arg {string} value - The input value
53       * @arg {object} obj - `{ key: 'k', value: 'v'}`
54       */
55      this.$emit('onChange', this.value, obj)
56    },
57    /**
58     * @private
59     * 这是一个私有方法
60     */
61    demo() {
62      /**
63       * @ignore
64       * 在文档中忽略当前事件
65       */
66      this.$emit('change', '111')
67    },
68  },
69}
70</script>

output markdown source:

1## 组件说明
2
3Button 组件
4
5## 设计初衷
6
7统一 button 的表现
8
9## 组件期望
10
11按钮统一，提供多种类型
12
13## Props
14
15| name       | description | type      | optional                  | required | default    |
16| ---------- | ----------- | --------- | ------------------------- | -------- | ---------- |
17| `disabled` | 禁用状态    | `Boolean` | -                         | `false`  | -          |
18| `size`     | 尺寸        | `String`  | `mini,small,medium,large` | `false`  | `"medium"` |
19
20## Events
21
22| name       | description | args                                                                     |
23| ---------- | ----------- | ------------------------------------------------------------------------ |
24| `onChange` | 变化事件    | `value：string` The input value，`obj：object` `{ key: 'k', value: 'v'}` |
25
26## Methods
27
28| name    | description | params                            |
29| ------- | ----------- | --------------------------------- |
30| `click` | 点击事件    | `event：Event` description event. |
31
32## Slots
33
34| slot      | description         | bind                       |
35| --------- | ------------------- | -------------------------- |
36| `default` | 这是默认的 slot     | -                          |
37| `title`   | 这是一个 title slot | `{ size, type }`大小和类型 |