青训营笔记-组件库开发（四）文档站搭建-vitepress文档站搭建vitepress搭建文档站，大家学会了也可用来搭建

五、文档站搭建

组件弄得差不多了，我们就该为我们的组件库搭建一个文档站啦

这里我使用的vitepress vitejs.cn/vitepress/

在packages下创建docs目录，然后在docs目录下

pnpm init
yarn add --dev vitepress

在docs目录下创建 index.md

1、index.md

vitepress的布局整体可以分为四种，分别是 doc page home 和 empty空白页面

layout:doc | page | home

以上语法需要写在md文档的头部才会生效

{{formatter.layout}}        //通过此语法可以将整个页面变成空白页面，适合自定义布局

2、首页配置

---
layout: home

hero:
  name: 主标题
  text: 内容信息
  tagline: 副内容信息
  image:
    src: /logo.png
    alt: 网站的 logo 图片
  actions:
    - theme: brand
      text: 快速开始
      link: /guide/what-is-vitepress
    - theme: alt
      text: 在 github 上查看
      link: https://github.com/vuejs/vitepress
features:
  - icon: ⚡️
    title: 这里是功能区 1
    details: 这里是功能区 1 详情信息
  - icon: 🖖
    title: 这里是功能区 2
    details: 这里是功能区 2 详情信息
  - icon: 🛠️
    title: 这里是功能区 3
    details: 这里是功能区 3 详情信息
---

示例

---
layout: home

hero:
    name: Kunlun Design
    text: 基于 vue 3 的组件库
    tagline: 会当临绝顶，一览众山小
    image:
      src: /.vitepress/images/logo.svg
      alt: Kunlun Design Logo
    actions:
        - theme: brand
          text: What is Kunlun Design ?
          link: /guide/what-is-kunlun-design
        - theme: alt
          text: To GitHub
          link: https://github.com/Anixuil/Kunlun-Design-Vue

features:
    - icon: ⚡️
      title: 这是一个练习项目
      details: wawawa
    - icon: 🖖
      title: 这是一个手掌图标
      details: good...
    - icon: 🛠️
      title: 这是一个修理图标
      details: cocococo
---

3、Page & Doc

这两种页面基本都是在书写文档的详细内容时需要的布局。从表现形式上看也只是文章内容显示位置上面的不同及page相比较doc会默认缺少一些内容比如edit link，NextPage , PrePage等，大多数情况下在编写的内容时推荐使用doc。

如果你在配置好之后跳转页面出现404了，可以查看配置页的link是否无误，可以绝对路径和相对路径都试试，哪个没问题就用哪个

4、全局配置对象

vitepress提供了一个配置对象，在 docs/.vitepress/config.ts 中。在这里可以配置 Nav SideBar 等重要信息

config.ts需要自己新建，新建完成后编写配置，以下是我的编写内容

import type { UserConfig } from 'vitepress'

export const config: UserConfig = {
    title: 'Kunlun Design',
    description: '基于 vue 3 的组件库',
    themeConfig: {
        logo: './.vitepress/images/logo-transprent.png',
    }
}

export default config

4.1 导航栏 Nav

Nav 配置有两种方式，直接点击跳转和下拉菜单

link 当触发点击事件时跳转的地址可以是外链也可以是项目内的路径

activeMatch 需要被高亮的Nav

text 显示到页面的内容

import type { UserConfig } from 'vitepress'

export const config: UserConfig = {
    title: 'Kunlun Design',
    description: '基于 vue 3 的组件库',
    themeConfig: {
        logo: './.vitepress/images/logo-transprent.png',
        nav: [
            {
                text: '指南',
                link: '/guide/what-is-kunlun-design',
                activeMatch: '/guide/what-is-kunlun-design'
            },
            {
                text: '关于',
                items: [
                    { text: '开发团队', link: '/' },
                    { text: '联系我们', link: '/https://github.com/Anixuil/Kunlun-Design-Vue' }
                ]
            }
        ]
}

export default config

社交链接 它不属于nav但是位置在头部

icon discord facebook github instagram linkedin slack twitter youtube or svg 字符串

link 跳转链接

import type { UserConfig } from 'vitepress'

export const config: UserConfig = {
    title: 'Kunlun Design',
    description: '基于 vue 3 的组件库',
    themeConfig: {
        logo: '/.vitepress/images/logo-transprent.png',
        nav: [
            {
                text: '指南',
                link: '/guide/what-is-kunlun-design',
                activeMatch: '/guide/what-is-kunlun-design'
            },
            {
                text: '关于',
                items: [
                    { text: '开发团队', link: '/' },
                    { text: '联系我们', link: '/https://github.com/Anixuil/Kunlun-Design-Vue' }
                ]
            }
        ]
        socialLinks: [{ icon: 'github', link: 'https://github.com/Anixuil/Kunlun-Design-Vue' }]
    }
}

export default config

4.2 侧边栏 Sidebar

Sidebar 同样由两种配置方式。接收以下配置对象

text 侧边栏块的标题 title
items 侧边栏的每一项，text为标题，link为跳转地址
collapsible 菜单是否为可折叠的 true|false
collapsed 是否默认折叠 true|false 只有配置 collapsible 时此配置才会生效

import type { UserConfig } from 'vitepress'

export const config: UserConfig = {
    title: 'Kunlun Design',
    description: '基于 vue 3 的组件库',
    themeConfig: {
        logo: '/.vitepress/images/logo-transprent.png',
        nav: [
            {
                text: '指南',
                link: '/guide/what-is-kunlun-design',
                activeMatch: '/guide/what-is-kunlun-design'
            },
            {
                text: '关于',
                items: [
                    { text: '开发团队', link: '/' },
                    { text: '联系我们', link: '/https://github.com/Anixuil/Kunlun-Design-Vue' }
                ]
            }
        ],
        sidebar:[
            {
                text:'指南',
                items:[
                    {text:'介绍',link:'/guide/what-is-kunlun-design'},
                    {text:'开始',link:'/guide/test'}
                ],
                collapsible: true,
                collapsed: true
            }
        ],
        socialLinks: [{ icon: 'github', link: 'https://github.com/Anixuil/Kunlun-Design-Vue' }]
    }
}

export default config

他还有对象配置方式

import type { UserConfig } from 'vitepress'

export const config: UserConfig = {
    title: 'Kunlun Design',
    description: '基于 vue 3 的组件库',
    themeConfig: {
        logo: '/.vitepress/images/logo-transprent.png',
        nav: [
            {
                text: '指南',
                link: '/guide/what-is-kunlun-design',
                activeMatch: '/guide/what-is-kunlun-design'
            },
            {
                text: '关于',
                items: [
                    { text: '开发团队', link: '/' },
                    { text: '联系我们', link: '/https://github.com/Anixuil/Kunlun-Design-Vue' }
                ]
            }
        ],
        sidebar:[
            '/guide/':[
            {
                text:'指南',
                items:[
                    {text:'介绍',link:'/guide/what-is-kunlun-design'},
                    {text:'开始',link:'/guide/test'}
                ],
                collapsible: true,
                collapsed: true
            }]
        ],
        socialLinks: [{ icon: 'github', link: 'https://github.com/Anixuil/Kunlun-Design-Vue' }]
    }
}

export default config

5、静态资源与导航路由的路径书写规则

静态资源：推荐放入 /docs/public文件夹中。在文档中以使用， / 以public目录开始，写过项目的大家应该能理解

路径配置规则 以 /docs 为根目录，进行配置

6、文章底部上下翻页

import type { UserConfig } from 'vitepress'

export const config: UserConfig = {
    title: 'Kunlun Design',
    description: '基于 vue 3 的组件库',
    themeConfig: {
        logo: '/.vitepress/images/logo-transprent.png',
        docFooter:{
            prev:'上一篇',
            next:'下一篇'
        },
    }
}

export default config

7、在 github编辑此页

可以通过editlink来进行配置，顾名思义，编辑链接嘛

pattern 可以分为两部分 :path 为变量内容，指当前的文件名称；这之前就是项目的 /docs 的github的文档地址

import type { UserConfig } from 'vitepress'

export const config: UserConfig = {
    title: 'Kunlun Design',
    description: '基于 vue 3 的组件库',
    themeConfig: {
        editLink:{
            pattern:'https://github.com/Anixuil/Kunlun-Design-Vue/packages/docs/:path',
            text:'在github上编辑此页'
        },
    }
}

export default config

8、最近更新时间

需要在themeconfig平级去开启此项，然后在themeconfig中可以去定制其展示文字。需要注意的时配置之后不会立即生效

import type { UserConfig } from 'vitepress'

export const config: UserConfig = {
    title: 'Kunlun Design',
    description: '基于 vue 3 的组件库',
    themeConfig: {
        lastUpdatedText:'文档最近更新时间'
    },
    lastUpdated:true
}

export default config

9、其他全局配置信息

自己看，我也不会哈哈哈 App Configs | VitePress (vuejs.org)

这里只说几个我用的

9.1 Internationalization Config

在themeconfig同级添加 locales 配置，修改语言环境以及 title 和 decription 的国际化内容；此时可以去除上面配置的与 locales 平级的 title 和 description

import type { UserConfig } from 'vitepress'

export const config: UserConfig = {
    title: 'Kunlun Design',
    description: '基于 vue 3 的组件库',
    //国际化
    locales:{
        "/":{
            lang: 'zh-CN',
            title: 'Kunlun Design',
            description: '一个基于 vue 3 的组件库'
        },
        "/en/":{
            lang: 'en-US',
            title: 'Kunlun Design',
            description: 'A component library based on vue 3'
        }
    }
}

export default config

在 themeConfig 下增加 localeLinks 切换国际化的下拉框

将 themeConfig 下的内容进行拆分并在 /docs 下新增 /en 文件夹用于存放国际化文档。

import type { UserConfig } from 'vitepress'

export const config: UserConfig = {
    title: 'Kunlun Design',
    description: '基于 vue 3 的组件库',
    themeConfig: {
        logo: '/.vitepress/images/logo-transprent.png',
        nav: [
            {
                text: '指南',
                link: '/guide/what-is-kunlun-design',
                activeMatch: '/guide/what-is-kunlun-design'
            },
            {
                text: '关于',
                items: [
                    { text: '开发团队', link: '/' },
                    { text: '联系我们', link: '/https://github.com/Anixuil/Kunlun-Design-Vue' }
                ]
            },
        ],
        sidebar:[
            {
                text:'指南',
                items:[
                    {text:'介绍',link:'/guide/what-is-kunlun-design'},
                    {text:'开始',link:'/guide/test'}
                ],
                collapsible: true,
                collapsed: true
            }
        ],
        docFooter:{
            prev:'上一篇',
            next:'下一篇'
        },
        editLink:{
            pattern:'https://github.com/Anixuil/Kunlun-Design-Vue/packages/docs/:path',
            text:'在github上编辑此页'
        },
        footer: {
            message: 'Released under the MIT License.',
            copyright: `Copyright &copy; 2023-PRESENT Kunlun-Designer and Kunlun-Design contributors`
        },
        algolia: {},
        socialLinks: [{ icon: 'github', link: 'https://github.com/Anixuil/Kunlun-Design-Vue' }],
        lastUpdatedText:'文档最近更新时间',
        //国际化配置
        localeLinks:{
            items:[
                {text:"简体中文",link:'/'},
                {text:"English",link:'/en/'}
            ]
        },
        locales:{
            "/":getChineseThemeConfig(),
            "/en/":getEnglishThemeConfig()
        }
    },
    lastUpdated:true,
    outDir:'../dist',
    //国际化
    locales:{
        "/":{
            lang:"zh-CN",
            title:"Kunlun Design",
            description:'一个基于 vue 3 的组件库'
        },
        "/en/":{
            lang:"en-US",
            title:"Kunlun Design",
            description:"A component library based on vue 3"
        }
    }
}

function getEnglishThemeConfig(){
    return{
        nav: [
            {
                text: 'Guide',
                link: '/en/guide/what-is-kunlun-design',
                activeMatch: '/en/guide/what-is-kunlun-design'
            },
            {
                text: 'About',
                items: [
                    { text: 'Dev Team', link: '/' },
                    { text: 'Contact Us', link: '/https://github.com/Anixuil/Kunlun-Design-Vue' }
                ]
            },
        ],
        sidebar:[
            {
                text:'Guide',
                items:[
                    {text:'Intro',link:'/en/guide/what-is-kunlun-design'},
                    {text:'Start',link:'/en/guide/test'}
                ],
                collapsible: true,
                collapsed: true
            }
        ],
        docFooter:{
            prev:'Prev Document',
            next:'Next Document'
        },
        editLink:{
            pattern:'https://github.com/Anixuil/Kunlun-Design-Vue/packages/docs/:path',
            text:'Edit this page on Github'
        },
    }
}

function getChineseThemeConfig(){
    return {
        nav: [
            {
                text: '指南',
                link: '/guide/what-is-kunlun-design',
                activeMatch: '/guide/what-is-kunlun-design'
            },
            {
                text: '关于',
                items: [
                    { text: '开发团队', link: '/' },
                    { text: '联系我们', link: '/https://github.com/Anixuil/Kunlun-Design-Vue' }
                ]
            },
        ],
        sidebar:[
            {
                text:'指南',
                items:[
                    {text:'介绍',link:'/guide/what-is-kunlun-design'},
                    {text:'开始',link:'/guide/test'}
                ],
                collapsible: true,
                collapsed: true
            }
        ],
        docFooter:{
            prev:'上一篇',
            next:'下一篇'
        },
        editLink:{
            pattern:'https://github.com/Anixuil/Kunlun-Design-Vue/packages/docs/:path',
            text:'在github上编辑此页'
        },
    }
}


export default config