VitePress 手把手完全使用手册 |
您所在的位置：网站首页 › 批处理跳转出错 › VitePress 手把手完全使用手册 |
VitePress 手把手完全使用手册
|
VitePress 是基于 Vite 的静态网站生成器（文档工具）。 初始化项目创建文件夹并进入到项目的目录中。当然如果你喜欢可以完全手动操作。 # mkdir 创建文件夹指令； && 表示当前命令执行成功后会执行下一条指令。 mkdir vitepress-starter && cd vitepress-starter初始化项目，官网默认使用了 yarn 作为依赖管理工具。 yarn init安装项目所需的依赖 vitepress 和 vue yarn add --dev vitepress vue创建第一个示例文件。如果你愿意可以手动操作 # echo 写入内容到项目的 docs/index.md 中 mkdir docs && echo '# Hello VitePress' > docs/index.md在 package.json 中增加打包以及运行的指令。 "scripts": { "docs:dev": "vitepress dev docs", // 本地运行调试 "docs:build": "vitepress build docs", // 项目打包：最终结果会在 .vitepress/dist 中 "docs:serve": "vitepress serve docs" // 预览打包后的效果，此命令只有 build 成功后才会执行成功。 },执行 npm run docs:dev 看到如下界面即表示运行成功。 目标 1:1 复现 vitepress 的布局。 布局VitePress 的布局整体可以分为 4 种，分别为：doc page home 和 没有任何默认布局（空白页面） 需要注意的是，下面的语法一定要写在 md 文档的头部才会生效 --- layout: doc | page | home --- // 通过此语法可以将整个页面变成空白页面，适合自定义的布局 {{ $formatter.layout }} 首页配置、Home 布局 点击查看首页配置，并结合下图参考对应配置 --- 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 详情信息 ---这两种基本都是在书写文档的详细内容时而需要的布局。从表现形式上看也只是文章内容显示位置上面的不同及 page 相比较 doc 会默认缺少一些内容比如 Edit Link，NextPage PrePage 等。大多数情况下在编写内容时推荐使用 doc。 --- layout: doc ---假设你现在点击页面上的 快速开始 不出意外直接 404 了，此时查看首页配置 快速开始的 link 为 /guide/what-is-vitepress 解决此问题：在 /docs 下新建文件 guide/what-is-vitepress.md 随便写入内容。再次点击即可访问。 VitePress 会根据 docs/ 下的文件内容映射成可访问路由。比如 /docs/guide/getting-started.md 则访问地址为 http://localhost:5173/guide/getting-started 文档书写规范推荐为以下结构 ├─ docs │ ├─ guide │ │ ├─ getting-started.md │ │ └─ what-is-vitepress.md │ ├─ theme │ │ ├─ theme-nav.md │ │ └─ theme-sidebar.md │ └─ index.md └─ package.json 全局配置对象VitePress 提供了一个配置对象，该对象应当存在于 /docs/.vitepress/config.js 中。在这里可以配置 Nav Sidebar 等重要信息。 在 .vitepress 中新建 config.js 文件并增加如下代码。 import { defineConfig } from 'vitepress'; export default defineConfig({}); Nav 导航栏Nav 配置有两种方式，直接点击跳转和下拉菜单样式。详情参考以下配置信息。 主要有以下字段： link：当触发点击事件时跳转的地址；可以是外链也可以是项目内的路径。 activeMatch： 需要被高亮的 nav 。 text：显示到页面的信息。 import { defineConfig } from 'vitepress'; export default defineConfig({ themeConfig: { nav: [ { text: 'Guide', link: '/guide', activeMatch: '/guide/what-is-vitepress' }, { text: '下拉选择框', items: [ { text: 'options-1', link: '/' }, { text: 'options-2', link: 'http://www.baidu.com' } ] } ] } });社交链接 严格来说不算 nav 范畴，但是显示位置基本相同。 export default defineConfig({ themeConfig: { socialLinks: [{ icon: "github", link: "https://github.com" }], } });icon：discord facebook github instagram linkedin slack twitter youtube 或者 svg 字符串 link：跳转链接。 对标如下页面： sidebar 同样有两种配置方式。接受以下配置对象： text：侧边栏块的 title。 items：侧边栏的每一项，text 为标题；link 为跳转地址。 collapsible：菜单是否为可折叠的 Boolean。 collapsed：是否默认折叠 Boolean 只有配置 collapsiable 时此配置才会生效。 数组配置方式 sidebar: [ { text: 'Guide', items: [ { text: 'Introduction', link: '/guide/what-is-vitepress' }, { text: 'Getting Started', link: '/getting-started' }, ], collapsible: true, collapsed: true } ],对象配置方式 sidebar: { '/guide/': [ { text: 'Guide', items: [ { text: 'Index', link: '/guide/' }, // /guide/index.md { text: 'One', link: '/guide/one' }, // /guide/one.md { text: 'Two', link: '/guide/two' } // /guide/two.md ] } ] } 1) 适合文档没有那么多的时候； 2) 能够更好的组织文档结构。对标如下页面： 静态资源：推荐放入 /docs/public 文件夹中。随后在 md 中使用时以 。 / 以 public 开始。 路径配置规则：以 /docs 为根目录，进行配置；/ 以 docs 开始。示例： export default defineConfig({ themeConfig: { // link 点击时跳转的默认地址 // activeMatch 无论在 guide 下的哪一个子菜单都会保持高亮。 nav: [{ text: '指导', link: '/guide/what-is-vitepress', activeMatch: '/guide' }], sidebar: { '/guide/': [ { text: '介绍', items: [ { text: '什么是 VitePress', link: '/guide/what-is-vitepress' }, { text: '快速开始', link: '/guide/getting-started' }, { text: '配置', link: '/guide/configuration' }, { text: '发布', link: '/guide/deploying' } ], collapsible: true } ] } } });上下翻页 此功能虽是默认提供，也可以通过配置来定制默认的文字。 export default { themeConfig: { docFooter: { prev: '上一篇', next: '下一篇' } } }在 Github 编辑此页 可以通过 editLink 来进行配置 pattern：可以分为两部分，:path 为变量内容指当前的文件名称。:path 之前的部分则是项目的 /docs 的 github 的文档地址。 export default { themeConfig: { editLink: { pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path', text: 'Edit this page on GitHub' } } }最后更新时间 需要在 themeConfig 平级去开启此选项，然后在 themeConfig 中可以去定制其展示文字。需要注意的是配置之后不会立即生效。 export default { lastUpdated: true, themeConfig: { lastUpdatedText: "最近更新时间" } } 其他全局配置信息主 title 内容与图片配置。 export default defineConfig({ title: '自定义的 title', themeConfig: { logo: '/test.jpg', } })打包后输出目录的配置 export default { outDir: '../dist' }markdown 主题配置 点击查看文档 description 配置后会显示页面中 显示 export default defineConfig({ description: '自定义的 description', })head 配置后会显示在页面中的 head 中。可以配置多个。应该也能扩展 VitePress 的功能，有兴趣的可以研究下。 export default defineConfig({ head: [['meta', { name: 'keywords', content: 'HTML, CSS, JavaScript' }]], })页脚通过 footer 进行配置。如果 Sidebar 存在则页脚不会存在 export default { themeConfig: { footer: { message: 'Released under the MIT License.', copyright: 'Copyright © 2019-present Evan You' } } }增加 locales 配置，修改语言环境以及 title 和 description 的国际化内容；此时可以去除上面配置的与 locales 平级的 title 和 description。 export default defineConfig({ locales: { "/": { lang: "zh-CN", title: "自定义的 title", description: "自定义的 description" }, "/en/": { lang: "en-US", title: "Custom title", description: "Custom description" } }, });在 themeConfig 下增加 localeLinks 切换国际化的下拉框； export default defineConfig({ themeConfig: { localeLinks: { items: [ { text: "简体中文", link: "/" }, { text: "English", link: "/en" } ] }, } });将 themeConfig 下的内容进行拆分并在 /docs 下新增 /en 文件夹用于存放国际化文档。 export default defineConfig({ themeConfig: { locales: { // 函数功能就是将需要语言转换的内容分开成两套配置，后续有示例 "/": getChineseThemeConfig(), "/en/": getEnglishThemeConfig() }, } })具体示例代码以及项目结构演示； export default defineConfig({ outDir: "../dist", head: [["meta", { name: "keywords", content: "HTML, CSS, JavaScript" }]], lastUpdated: true, locales: { "/": { lang: "zh-CN", title: "自定义的title", description: "自定义的description" }, "/en/": { lang: "en-US", title: "Custom title", description: "Custom description" } }, themeConfig: { logo: "/test.jpg", socialLinks: [{ icon: "github", link: "https://github.com" }], localeLinks: { text: "", items: [ { text: "中文", link: "/" }, { text: "English", link: "/en/" } ] }, locales: { // 原本 themeConfig 下所有需要转换的信息通过手动写两套配置的方式全部处理一下 // 例如 // 中文展示 docFooter: { prev: "上一页", next: "下一页" } // 英文展示 docFooter: { prev: "Pre page", next: "Next page" } "/": getChineseThemeConfig(), "/en/": getEnglishThemeConfig() } } }); // 注意英文配置下路径也需要进行处理。 function getEnglishThemeConfig() { return { nav: [{ text: "Guide", link: "/en/guide/what-is-vitepress", activeMatch: "/en/guide/" }], sidebar: { "/en/guide/": [ { text: "Description", items: [{ text: "What is VitePress", link: "/en/guide/what-is-vitepress" }], collapsible: true } ] }, // ... ... }; }国际化基本的目录结构应该如下这样； . docs ├── en │ ├── guide │ │ └── what-is-vitepress.md │ └── index.md 英文状态下的 index 也需要进行转换 ├── guide │ └── what-is-vitepress.md ├── index.md ├── node_modules 主题配置主题的配置可以分为两种。拓展主题 定制主题 使用方式大体相同。 .vitepress 下新增 theme 文件夹以及 /theme/index.js 文件 无论使用哪种方式，哪怕不定制主题，也可以单独的修改它默认的样式。 查看样式定制 // .vitepress/theme/index.js import DefaultTheme from 'vitepress/theme' import './custom.css' export default DefaultTheme /* .vitepress/theme/custom.css */ :root { --vp-c-brand: #646cff; --vp-c-brand-light: #747bff; } 拓展主题使用 vitepress 提供的一些插槽拓展它的主题；查看布局插槽 // .vitepress/theme/index.js import DefaultTheme from 'vitepress/theme' import MyLayout from './MyLayout.vue' export default { ...DefaultTheme, // override the Layout with a wrapper component that // injects the slots Layout: MyLayout } import DefaultTheme from 'vitepress/theme' const { Layout } = DefaultTheme My custom sidebar top content 定制主题目前 Element-Plus 就是采用这种方式来开发的文档站点。 Element-Plus文档源码入口文件 // .vitepress/theme/index.js import Layout from './Layout.vue' export default { // 布局文件入口， Layout, // this is a Vue 3 functional component // 404 页面 NotFound: () => 'custom 404', enhanceApp({ app, router, siteData }) { // 这里可以注册组件等内容在可以在文档中做 组件预览展示等功能。 } } Markdown 语法拓展语法拓展文档请移步 这里 。都是一些拓展语法比较简单。 Markdown 中使用 Vue文档请移步 这里 。 Vue 组件展示插件推荐几个插件，这里就不在演示 Demo。使用起来也是比较简单的； vitepress-doc-plugin 相对推荐 vitepress-demo-editor 可交互的 demo 操作。根据需求推荐 vitepress-demo 比较推荐 Github Page 发布根目录新建 deploy.sh 文件。并复制以下内容稍微修改。 #!/usr/bin/env sh # 确保脚本抛出遇到的错误 set -e # 删除文件需要根据实际打包的目录进行删除 rm -rf docs/.vitepress/dist/ # 生成静态文件 yarn docs:build # 进入生成的文件夹 cd docs/.vitepress/dist # 如果是发布到自定义域名 # echo 'www.example.com' > CNAME git init git add -A git commit -m 'deploy' # 如果发布到 https://.github.io 修改仓库地址 # git push -f [email protected]:/.github.io.git master:gh-pages cd -创建 github 仓库。注意 Repository name 和本地的 base 配置相同 export default defineConfig({ base: '/your-github-repository/' })package.json 中新增脚本并执行，虽然等个三两分钟直接访问 https://your-github.github.io/your-github-repository/。 "scripts": { "docs:deploy": "bash deploy.sh" }如果遇到异常 参考 VuePress 搭建组件库文档 VuePress 部署 Algolia 搜索本章节参考 VuePress 博客优化之开启 Algolia 全文搜索。 Algolia 开始之前务必通读 文档 如果确认要引入该搜索时，需要保证你的项目可以用于外网访问。比如 githubpages 点击此链接进行 key，Algolia 申请，时间可能会比较漫长。官网说不超过 2 周。申请成功后就坐等邮件吧。收到邮件后回复 I am the maintainer of the website, I can modify the code ~ 再次收到邮件可能包含以下内容 查看完整配置信息 同时也和各位小伙伴分享一下，我前段时间总结的一些前端面试题。希望对正在找工作，即将找工作的一些小伙伴提供到帮助。2022面试题汇总 如果内容有帮助到你，就点个 star 激励一下我吧。 |
【本文地址】