关于javascript:我问导师Vue3有没有对应工具来生成漂亮的文档-用-Vitepress

作者：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-world
cd vite-hello-world

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

npm init
npm 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 docs
echo '# 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.js

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

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

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

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

// .vitepress/config.js
module.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.js
module.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.js
const 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 和欠缺，大家面试能够参照考点温习，另外关注公众号，后盾回复 福利，即可看到福利，你懂的。