VitePress 是一个基于 Vue 3 的静态网站生成器,专注于文档网站的构建。它结合了 Vue 的单文件组件和 Vite 的开发体验,提供了快速、简单且现代化的方式来创建和维护静态文档网站。
安装 VitePress
首先,确保你已经安装了最新版本的 Node.js。
然后,使用以下命令全局安装 VitePress:
npm install -g create-vitepress
创建项目
创建一个新的 VitePress 项目非常简单,只需在命令行中执行以下命令:
create-vitepress my-docs
这将在当前目录下创建一个名为 my-docs
的新文件夹,并在其中初始化一个 VitePress 项目。
编写文档
VitePress 使用 Markdown 编写文档,所以你可以使用任何你熟悉的 Markdown 编辑器。
在 my-docs
文件夹中,你会发现一个名为 docs
的文件夹。这是你存放所有文档的地方。在 docs
文件夹中,你可以创建任意数量的 Markdown 文件来编写你的文档。
VitePress 强调使用 Markdown 语法来编写文档,它还支持扩展语法如 Yaml Front Matter、代码块高亮、LaTeX 数学公式等。你可以通过在 Markdown 文件的开头添加元数据来自定义每个页面的标题、描述和排序等属性。
以下是一个示例 Markdown 文件:
---
title: 我的示例文档
description: 这是一个示例文档
---
# 我的示例文档
欢迎来到我的示例文档!这里是一个简单的示例,用于演示如何编写 VitePress 文档。
## 第一步
这是第一步的说明。
## 第二步
这是第二步的说明。
## 第三步
这是第三步的说明。
添加导航栏
在 VitePress 中,你可以通过配置导航栏来自定义网站的导航结构。
打开 my-docs
文件夹中的 vitepress.config.js
文件,并在 themeConfig
中添加 nav
属性:
module.exports = {
themeConfig: {
nav: [
{ text: '首页', link: '/' },
{ text: '指南', link: '/guide/' },
{ text: 'API', link: '/api/' },
{ text: '关于', link: '/about/' }
]
}
}
在 nav
数组中,每个对象代表导航栏中的一个链接。text
是显示的文字,link
是相对于网站根目录的链接路径。你可以根据你的需求添加、编辑或删除导航链接。
本地预览
当你完成文档的编写和导航栏的配置后,你可以通过以下命令在本地启动一个开发服务器来预览你的文档网站:
cd my-docs
npm install
npm run dev
然后,在浏览器中访问 http://localhost:3000
,你将看到你的文档网站。
构建静态网站
当你准备部署你的文档网站时,你可以使用以下命令来构建静态网站:
cd my-docs
npm run build
构建完成后,你会在 my-docs/dist
文件夹中找到生成的静态网站文件。你可以将这些文件部署到任何静态文件托管服务上,例如 GitHub Pages。
总结:VitePress 是一个功能强大且易于使用的静态网站生成器,它提供了一种现代化的方式来创建和维护文档网站。它基于 Vue 3 和 Vite,允许使用 Markdown 编写文档,并提供了丰富的自定义和扩展功能。无论是为个人项目、团队文档还是开发者文档,VitePress 都是一个值得尝试的选择。
本文来自极简博客,作者:琴音袅袅,转载请注明原文链接:使用VitePress构建静态文档网站