我问导师，Vue3有没有对应工具来生成漂亮的文档？用Vitepress

本文已经过原作者 Michael Thiessen 授权翻译。

成都创新互联公司网站建设提供从项目策划、软件开发，软件安全维护、网站优化(SEO)、网站分析、效果评估等整套的建站服务，主营业务为网站设计制作、成都网站制作，成都APP应用开发以传统方式定制建设网站，并提供域名空间备案等一条龙服务，秉承以专业、用心的态度为用户提供真诚的服务。成都创新互联公司深信只要达到每一位用户的要求，就会得到认可，从而选择与我们长期合作。这样，我们也可以走得更远！

最近有人在问：小智， 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 项目

首先，创建目录。

 
 
 
 
    
  
  
  
  
  1. mkdir vite-hello-world 
    2.   
  
  
  
  2. cd vite-hello-world 
    3.

然后，初始化 package 并安装 Vitepress。

 
 
 
 
    
  
  
  
  
  1. npm init 
    2.   
  
  
  
  2. npm i --save-dev vitepress 
    3.

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

 
 
 
 
    
  
  
  
  
  1. // package.json 
    2.   
  
  
  
  2. "scripts": { 
    3.   
  
  
  
  3.   "docs:dev": "vitepress dev docs", 
    4.   
  
  
  
  4.   "docs:build": "vitepress build docs", 
    5.   
  
  
  
  5.   "docs:serve": "vitepress serve docs" 
    6.   
  
  
  
  6. }, 
    7.

把上面安排后，再创建一个docs文件夹，制作我们的第一个markdown文件。

 
 
 
 
    
  
  
  
  
  1. mkdir docs 
    2.   
  
  
  
  2. echo '# Hello World' > docs/index.md 
    3.

最后，给它跑起来。

 
 
 
 
    
  
  
  
  
  1. npm run docs:dev~~~~ 
    2.

我们已经创建了我们的网站，在浏览器中打开 http://localhost:3000，则会在网页中看到我们的markdown文件!

[[391288]]

看到这样，有点小鸡冻了，我们再来看看，如果定制自己想要的东西。

Vitepress 导航

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

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

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

 
 
 
 
    
  
  
  
  
  1. // docs/index.md 
    2.   
  
  
  
  2.  
    3.   
  
  
  
  3. ## Routing! 
    4.   
  
  
  
  4.  
    5.   
  
  
  
  5. [docs/index.md](/) -> / 
    6.   
  
  
  
  6.  
    7.   
  
  
  
  7. [docs/contact.md](/contact) -> /contact 
    8.   
  
  
  
  8.  
    9.   
  
  
  
  9. [about/index.md](/about/) -> /about/ 
    10.   
  
  
  
  10.  
    11.   
  
  
  
  11. [about/our-story.md](/about/our-story) -> /about/our-story 
    12.

在我们的md文件中，有三种跳转到路由的方法 我们可以使用基本URL，添加.md或.html-所有这些都将正确链接到对应的组件。

 
 
 
 
    
  
  
  
  
  1. ### All these options work! 
    2.   
  
  
  
  2.  
    3.   
  
  
  
  3. [docs/contact](/contact) |  
    4.   
  
  
  
  4. [docs/contact.md](/contact.md) | 
    5.   
  
  
  
  5. [docs/contact.html](/contact.html) 
    6.

添加导航栏和侧边栏

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

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

为此，我们需要创建一个配置文件–我们可以在/docs/.vitepress/文件夹中进行此操作，该文件夹将存放我们的 Vitepress 特定文件，取名为./vitepress/config.js，只需要导出一个JS对象。

 
 
 
 
    
  
  
  
  
  1. // .vitepress/config.js 
    2.   
  
  
  
  2.  
    3.   
  
  
  
  3. module.exports = { 
    4.   
  
  
  
  4.   title: 'Vitepress Tutorial', // appended to all page titles 
    5.   
  
  
  
  5. } 
    6.

在这个对象中，我们再添加一个themeConfig的属性

 
 
 
 
    
  
  
  
  
  1. // .vitepress/config.js 
    2.   
  
  
  
  2. module.exports = { 
    3.   
  
  
  
  3.   title: "Vitepress Tutorial", // appended to all page titles 
    4.   
  
  
  
  4.   themeConfig: { 
    5.   
  
  
  
  5.     nav: [], 
    6.   
  
  
  
  6.     sidebar: [], 
    7.   
  
  
  
  7.   }, 
    8.   
  
  
  
  8. }; 
    9.

要将元素添加到导航栏，我们只需要将对象添加到nav数组中，格式为{text：'ANCHOR-TEXT'，link：'PATH'}:

 
 
 
 
    
  
  
  
  
  1. // .vitepress/config.js 
    2.   
  
  
  
  2. module.exports = { 
    3.   
  
  
  
  3.   title: "Vitepress Tutorial", // appended to all page titles 
    4.   
  
  
  
  4.   themeConfig: { 
    5.   
  
  
  
  5.     nav: [ 
    6.   
  
  
  
  6.       { text: "Home", link: "/" }, 
    7.   
  
  
  
  7.       { text: "About", link: "/about/" }, 
    8.   
  
  
  
  8.       { text: "Contact", link: "/contact" }, 
    9.   
  
  
  
  9.     ], 
    10.   
  
  
  
  10.     sidebar: [ 
    11.   
  
  
  
  11.      { text: 'Our Story', link: '/about/our-story' } 
    12.   
  
  
  
  12.     ], 
    13.   
  
  
  
  13.   }, 
    14.   
  
  
  
  14. }; 
    15.

添加侧边栏也是一样的方式。

 
 
 
 
    
  
  
  
  
  1. // .vitepress/config.js 
    2.   
  
  
  
  2. module.exports = { 
    3.   
  
  
  
  3.   title: "Vitepress Tutorial", // appended to all page titles 
    4.   
  
  
  
  4.   themeConfig: { 
    5.   
  
  
  
  5.     nav: [ 
    6.   
  
  
  
  6.       { text: "Home", link: "/" }, 
    7.   
  
  
  
  7.       { text: "About", link: "/about/" }, 
    8.   
  
  
  
  8.       { text: "Contact", link: "/contact" }, 
    9.   
  
  
  
  9.     ], 
    10.   
  
  
  
  10.     sidebar: [ 
    11.   
  
  
  
  11.      { text: 'Our Story', link: '/about/our-story' } 
    12.   
  
  
  
  12.     ], 
    13.   
  
  
  
  13.   }, 
    14.   
  
  
  
  14. }; 
    15.

回到我们的浏览器，我们现在可以看到 Vitepress 仅从几行配置就生成了一个非常漂亮的导航栏和侧栏。

Vitepress侧边栏可以做的一件很酷的事情是根据我们所在的页面来更改侧边栏。

比如，我们想让首页显示其标题，其他页面都显示我们刚刚制作的侧边栏。

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

 
 
 
 
    
  
  
  
  
  1. // .vitepress/config.js 
    2.   
  
  
  
  2. const primarySidebar = [ 
    3.   
  
  
  
  3.   { text: 'Our Story', link: '/about/our-story' } 
    4.   
  
  
  
  4. ] 
    5.

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

 
 
 
 
    
  
  
  
  
  1. sidebar: { 
    2.   
  
  
  
  2.   '/about/': primarySidebar, // everything in the /about/ subdirectory 
    3.   
  
  
  
  3.   '/contact': primarySidebar, // contact page 
    4.   
  
  
  
  4. } 
    5.

现在，查看浏览器，会看到我们的主页侧边栏与所有其他边栏不同。

在Vitepress中内置元素

Vitepress 附带了对几个元素的支持，我们可以在config.js中或在Markdown中直接声明这些元素。

这里只会在这里介绍一些最常用的内容，完整的内容点击这里。

代码块

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

Github样式表

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

 
 
 
 
    
  
  
  
  
  1. // .vitepress/config.js 
    2.   
  
  
  
  2.  
    3.   
  
  
  
  3. | Headings      | Are           | Centered    | 
    4.   
  
  
  
  4. | ------------- |:-------------:| -----:      | 
    5.   
  
  
  
  5. | left align    | centered      | right align | 
    6.   
  
  
  
  6. | zebra striped | rows          | easy        | 
    7.

Markdown Frontmatter配置

尽管我们可以使用./vuepress/config.js配置网站，但有时我们还是需要对各个页面进行更细的控制。

幸运的是，我们可以使用markdown文件顶部的YAML块来控制每个页面。Vitepress通过用三个虚线(---)包围它来声明该块。

 
 
 
 
    
  
  
  
  
  1. // docs/contact 
    2.   
  
  
  
  2.  
    3.   
  
  
  
  3. --- 
    4.   
  
  
  
  4. title: Contact 
    5.   
  
  
  
  5. --- 
    6.   
  
  
  
  6.  
    7.   
  
  
  
  7. # Contact 
    8.

我们可以在这里配置很多不同的东西。查看所有Frontmatter选项的文档。

部署 Vitepress 应用

我们使用npm run docs:dev创建本地环境，但是构建用于生产的应用又该怎么做呢?

可以使用以下命令来构建：

 
 
 
 
    
  
  
  
  
  1. npm run dev:build 
    2.

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

作者：Michael Thiessen 译者：前端小智来源：news原文：https://learn.co/2021/01/write-beautul-documentation-quickly-with-vitepress/

文章标题：我问导师，Vue3有没有对应工具来生成漂亮的文档？用Vitepress
文章地址：http://www.shufengxianlan.com/qtweb/news45/397495.html

网站建设、网络推广公司-创新互联，是专注品牌与效果的网站制作，网络营销seo公司；服务项目有等

广告

声明：本网站发布的内容（图片、视频和文字）以用户投稿、用户转载内容为主，如果涉及侵权请尽快告知，我们将会在第一时间删除。文章观点不代表本网站立场，如需处理请联系客服。电话：028-86922220；邮箱：631063699@qq.com。内容未经允许不得转载，或转载时需注明来源： 创新互联

猜你还喜欢下面的内容

做网站知识

同城分类信息

成都网站制作　　 　响应式报价　　 　绵竹做网站　　 　成都服务器租用　　 　成都做商城网站　　 　成都商城app开发　　 　手机网站制作　　 　重庆托管服务器　　 　力比特机械　　 　攀枝花网站设计　　 　网站SEO优化　　 　乐至网站建设　　 　简阳网站建设　　 　成都400电话申请　　 　营销型网站建设　　 　边坡防护网　　 　节能环保网站建设方案　　 　视频运营　　 　成都网站设计　　 　泸州洋跃建站