作者：Michael Thiessen
译者：前端小智
起源：news
点赞再看，微信搜寻【大迁世界】,B站关注【前端小智】这个没有大厂背景，但有着一股向上踊跃心态人。本文 GitHub https://github.com/qq44924588... 上曾经收录，文章的已分类，也整顿了很多我的文档，和教程材料。

最近有人在问：小智， Vue3 有没有对应制作文档的工具。于是，我去查了一些材料，发现，Vue3和新的Vite构建工具为咱们提供了另一种疾速开发动态站点的办法，那就是 Vitepress。

明天，咱们来一起看看，如何应用 Vitepress 疾速为Vue利用创立文档。

上面是咱们最初要实现的内容：

在开始之前，咱们先来看看 Vitepress 是个啥货色。

Vitepress 是什么？

Vitepress是在Vite之上构建的Vue驱动的动态站点生成器。

Vitepress 被称为“ Vuepress的小弟弟”，它比同类产品具备一些劣势。

  • 建设在Vite而非Webpack上，因而启动工夫，热重装等更快
  • 应用Vue3来缩小JS的无效负载
  • 轻量级

Vitepress 可能实现这些指标的一个起因是，它比Vuepress 更具体，而 Vuepress在过来几年里变得更加简单。

尽管不打算齐全取代Vuepress作为 Vue 的动态网站生成器，但 Vitepress 提供了一种轻量级的代替计划。 对于大多数我的项目，例如文档和简略站点，Vitepress的特殊性和简洁性将使开发变得轻而易举。

创立 Vitepress 我的项目

首先，创立目录。

mkdir vite-hello-worldcd vite-hello-world

而后，初始化 package 并装置 Vitepress。

npm initnpm i --save-dev vitepress

接着，在package.json中增加一些命令。

// package.json"scripts": {  "docs:dev": "vitepress dev docs",  "docs:build": "vitepress build docs",  "docs:serve": "vitepress serve docs"},

把下面安顿后，再创立一个docs文件夹，制作咱们的第一个markdown文件。

mkdir docsecho '# Hello World' > docs/index.md

最初，给它跑起来。

npm run docs:dev~~~~

咱们曾经创立了咱们的网站，在浏览器中关上 http://localhost:3000，则会在网页中看到咱们的markdown文件！

看到这样，有点小鸡冻了，咱们再来看看，如果定制本人想要的货色。

Vitepress 导航

Vitepress 增加多个页面就像创立更多markdown文件一样容易。咱们在 docs/ 再创立一些文件，如下所示：

Vitepress 创立 SPA 导航时，它将应用每个markdown文件的门路来创立路由。 此外，任何文件夹中名为index.md的文件也只能由/援用。

例如，咱们的文件构造转换为以下路由：

// docs/index.md## Routing![docs/index.md](/) -> /[docs/contact.md](/contact) -> /contact[about/index.md](/about/) -> /about/[about/our-story.md](/about/our-story) -> /about/our-story

在咱们的md文件中，有三种跳转到路由的办法 咱们能够应用根本URL，增加.md或.html-所有这些都将正确链接到对应的组件。

### All these options work![docs/contact](/contact) | [docs/contact.md](/contact.md) |[docs/contact.html](/contact.html)

增加导航栏和侧边栏

Vitepress为咱们提供了一个很棒的默认主题。 它尽管很小，但功能强大且易于定制。

首先，咱们通过边栏和导航栏向咱们的网站增加一些导航。

为此，咱们须要创立一个配置文件–咱们能够在/docs/.vitepress/文件夹中进行此操作，该文件夹将寄存咱们的 Vitepress 特定文件，取名为./vitepress/config.js，只须要导出一个JS对象。

// .vitepress/config.jsmodule.exports = {  title: 'Vitepress Tutorial', // appended to all page titles}

在这个对象中，咱们再增加一个themeConfig的属性

// .vitepress/config.jsmodule.exports = {  title: "Vitepress Tutorial", // appended to all page titles  themeConfig: {    nav: [],    sidebar: [],  },};

要将元素增加到导航栏，咱们只须要将对象增加到nav数组中，格局为{text：'ANCHOR-TEXT'，link：'PATH'}:

// .vitepress/config.jsmodule.exports = {  title: "Vitepress Tutorial", // appended to all page titles  themeConfig: {    nav: [      { text: "Home", link: "/" },      { text: "About", link: "/about/" },      { text: "Contact", link: "/contact" },    ],    sidebar: [     { text: 'Our Story', link: '/about/our-story' }    ],  },};

增加侧边栏也是一样的形式。

// .vitepress/config.jsmodule.exports = {  title: "Vitepress Tutorial", // appended to all page titles  themeConfig: {    nav: [      { text: "Home", link: "/" },      { text: "About", link: "/about/" },      { text: "Contact", link: "/contact" },    ],    sidebar: [     { text: 'Our Story', link: '/about/our-story' }    ],  },};

回到咱们的浏览器，咱们当初能够看到 Vitepress 仅从几行配置就生成了一个十分丑陋的导航栏和侧栏。

Vitepress侧边栏能够做的一件很酷的事件是依据咱们所在的页面来更改侧边栏。

比方，咱们想让首页显示其题目，其余页面都显示咱们刚刚制作的侧边栏。

咱们要做的第一件事是创立将our-story侧边栏存储为变量。

// .vitepress/config.jsconst primarySidebar = [  { text: 'Our Story', link: '/about/our-story' }]

回到咱们的themeConfig对象，咱们想将侧边栏更改为一个对象，其中属性名称是门路，值是侧边栏数组。

sidebar: {  '/about/': primarySidebar, // everything in the /about/ subdirectory  '/contact': primarySidebar, // contact page}

当初，查看浏览器，会看到咱们的主页侧边栏与所有其余边栏不同。

在Vitepress中内置元素

Vitepress 附带了对几个元素的反对，咱们能够在config.js中或在Markdown中间接申明这些元素。

这里只会在这里介绍一些最罕用的内容，残缺的内容点击这里。

代码块

在编写好的文档时，代码示例至关重要。 Vitepress 提供了一种疾速增加代码块并指定正在应用的编程语言的办法。

Github样式表

Vitepress中的表没接触过 md 的小伙伴，可能会感觉有点奇怪，如下所示：

// .vitepress/config.js| Headings      | Are           | Centered    || ------------- |:-------------:| -----:      || left align    | centered      | right align || zebra striped | rows          | easy        |

Markdown Frontmatter配置

只管咱们能够应用./vuepress/config.js配置网站，但有时咱们还是须要对各个页面进行更细的管制。

侥幸的是，咱们能够应用markdown文件顶部的YAML块来管制每个页面。 Vitepress通过用三个虚线（---）突围它来申明该块。

// docs/contact---title: Contact---# Contact

咱们能够在这里配置很多不同的货色。 查看所有Frontmatter选项的文档。

部署 Vitepress 利用

咱们应用npm run docs:dev创立本地环境，然而构建用于生产的利用又该怎么做呢？

能够应用以下命令来构建：

npm run dev:build

默认状况下，构建后的文件会被放到/docs/.vuepress/dist下。

~完，咱们刷碗智，咱们下期见！

代码部署后可能存在的BUG没法实时晓得，预先为了解决这些BUG，花了大量的工夫进行log 调试，这边顺便给大家举荐一个好用的BUG监控工具 Fundebug。

原文：
https://learn.co/2021/01/writ...

交换

文章每周继续更新，能够微信搜寻「 大迁世界 」第一工夫浏览和催更（比博客早一到两篇哟），本文 GitHub https://github.com/qq449245884/xiaozhi 曾经收录，整顿了很多我的文档，欢送Star和欠缺，大家面试能够参照考点温习，另外关注公众号，后盾回复福利，即可看到福利，你懂的。