使用vue styleguidist编写组件文档

示例代码地址

vue-styleguidist-demo

安装与基本配置

npm包安装

npm install --save-dev vue-styleguidist

加入styleguide相关命令

package.json

{
   
  "scripts": {
   
    "styleguide": "vue-styleguidist server",
    "styleguide:build": "vue-styleguidist build"
  }
}

• vue-styleguidist server: 运行开发服务器。
• vue-styleguidist build：生成静态 HTML 样式指南。

选项	描述
–config	指定配置文件的路径
–open	在默认浏览器中打开 Styleguidist
–verbose	打印调试信息

基本配置

最小配置

// styleguide.config.js
module.exports = {
   
    title: 'Vue Styleguidist 示例',
    components: 'src/components/**/[A-Z]*.vue',
    version: '1.1.1',
    styleguideDir: 'styleguide-dist',
    // 在编辑器的右上角添加一个小按钮，用于将编辑器的内容复制到剪贴板
    copyCodeButton:true,
    // 是否每个章节是一个独立的页面. 默认:false
    pagePerSection: true,
    // props/events/slot的说明默认是展开还是收缩: expand / collapse / hide
    usageMode: 'expand',
    // 左侧导航默认是展开还是收缩: expand / collapse / hide
    tocMode: 'expand',
    // 显示 prop、事件、槽或方法是否来自当前文件或在 mixin 或扩展组件中配置。如果它是外部的，它会显示组件的名称，并在悬停时显示文件的相对路径。
    displayOrigins: true
}

加载和公开组件

默认情况下，Styleguidist 会加载您的组件并在全局范围内公开它们以供您的示例使用。您可以使用localRegisterComponents来避免全局注册。这仅在其附加ReadMe.md文件或<docs>块中的示例中加载记录的组件。

查找组件

默认情况下，Styleguidist 将使用此glob 模式搜索组件: src/components/**/*.vue

也可自行修改:

module.exports = {
   
  components: 'src/components/**/[A-Z]*.vue'
}

但会忽略测试文件夹__tests__

章节配置

如果不进行额外的配置章节, 那么每个组件会是一个章节

• name: 章节标题
• content: 包含概览内容的 Markdown 文件的位置
• components: glob 模式字符串、组件路径数组或 glob 模式字符串，或返回组件列表或 glob 模式字符串的函数。相同的规则适用于 root components选项
• sections: 子章节数组（可以嵌套）
• description: 本章节的简短说明
• sectionDepth: 单页的子节数，仅在启用pagePerSection 时可用。
• exampleMode: 代码示例选项卡的初始状态，使用exampleMode。
• usageMode: 道具和方法选项卡的初始状态，使用usageMode。
• ignore: 不应包含在该部分中的字符串/glob 数组。
• href: 要导航到的 URL，而不是导航到部分内容
• external: 如果设置，链接将在新窗口中打开

module.exports = {
   
  sections: [
    {
   
      name: 'Introduction',
      content: 'docs/introduction.md'
    },
    {
   
      name: 'Documentation',
      sections: [
        {
   
          name: 'Installation',
          content: 'docs/installation.md',
          description: 'The description for the installation section'
        },
        {
   
          name: 'Configuration',
          content: 'docs/configuration.md'
        },
        {
   
          name: 'Live Demo',
          external: true,
          href: 'http://example.com'</