投稿
  1. 极客之音首页
  2. 前端开发

一款优雅的撰写文档利器–VitePress

李, 若俞 • • 前端开发 • 阅读 334

  • • VitePress

      • • VitePress是什么

      • • 使用场景

        • • 文档

        • • 博客、档案和营销网站

      • • 开发体验

      • • VuePress 又是什么？

    • • 快速开始

      • • 前置准备

      • • 安装

      • • 安装向导

      • • 模板设置

      • • 文件结构

      • • 配置文件

      • • 源文件

      • • 启动并运行

        • • docs:dev

        • • 直接调用 VitePress

    • • 扩展：如何使用vitepress快速构建一个博客系统

VitePress

一款优雅的撰写文档利器--VitePress

VitePress是什么

VitePress 是一个静态站点生成器 (SSG)，专为构建快速、以内容为中心的站点而设计。

简而言之，VitePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。

静态站点生成器：https://en.wikipedia.org/wiki/Static_site_generator

官方网站：https://vitepress.dev/zh/

使用场景

文档

VitePress 附带一个专为技术文档设计的默认主题。你现在正在阅读的这个页面以及 Vite、Rollup、Pinia、VueUse、Vitest、D3、UnoCSS、Iconify 等文档都是基于这个主题的。

Vue.js 官方文档也是基于 VitePress 的。但是为了可以在不同的翻译文档之间切换，它自定义了自己的主题。

博客、档案和营销网站

VitePress 支持完全的自定义主题，具有标准 Vite + Vue 应用程序的开发体验。

基于 Vite 构建还意味着可以直接利用其生态系统中丰富的 Vite 插件。此外，VitePress 提供了灵活的 API 来加载数据 (本地或远程)，也可以动态生成路由。只要可以在构建时确定数据，就可以使用它来构建几乎任何东西。

Vue.js 官方博客是一个简单的博客页面，它根据本地内容生成其索引页面。

开发体验

VitePress 旨在使用 Markdown 生成内容时提供出色的开发体验。

Vite 驱动：即时服务器启动，始终立即反映 (<100ms) 编辑变化，无需重新加载页面。

内置 Markdown 扩展：frontmatter、表格、语法高亮……应有尽有。具体来说，VitePress 提供了许多用于处理代码块的高级功能，使其真正成为技术文档的理想选择。

Vue 增强的 Markdown：每个 Markdown 页面都是 Vue 单文件组件，这要归功于 Vue 模板与 HTML 的 100% 语法兼容性。可以使用 Vue 模板语法或导入的 Vue 组件在静态内容中嵌入交互性。

VuePress 又是什么？

VitePress 灵感来源于 VuePress。最初的 VuePress 基于 Vue 2 和 webpack。借助 Vue 3 和 Vite，VitePress 提供了更好的开发体验、更好的生产性能、更精美的默认主题和更灵活的自定义 API。

VitePress 和 VuePress 之间的 API 区别主要在于主题和自定义。如果使用的是带有默认主题的 VuePress 1，迁移到 VitePress 应该相对简单。

VuePress 2 我们也投入了精力，它也支持 Vue 3 和 Vite，与 VuePress 1 的兼容性更好。但是，并行维护两个 SSG 是难以持续的，因此 Vue 团队决定将重点放在 VitePress，作为长期的主要 SSG 选择推荐。

更多详细内容，请微信搜索“前端爱好者“， 戳我 查看 。

快速开始

前置准备

  • • Node.js 18 及以上版本。

  • • 通过命令行界面 (CLI) 访问 VitePress 的终端。

  • • 支持 Markdown 语法的编辑器。

    • • 推荐 VSCode 及其官方 Vue 扩展

VSCode扩展：https://code.visualstudio.com/

官方 Vue 扩展：https://marketplace.visualstudio.com/items?itemName=Vue.volar

安装

VitePress 可以单独使用，也可以安装到现有项目中。在这两种情况下，都可以使用以下方式安装它：

# npm 
npm add -D vitepress

# pnpm
pnpm add -D vitepress

# yarn
yarn add -D vitepress

# bun
bun add -D vitepress

tips:如果使用 PNPM，会注意到对 @docsearch/js 的 missing peer deps 警告。这不会影响 VitePress 运行。如果希望禁止显示此警告，请将以下内容添加到 package.json：

"pnpm": {
  "peerDependencyRules": {
    "ignoreMissing": [
      "@algolia/client-search",
      "search-insights"
    ]
  }
}

安装向导

VitePress 附带一个命令行设置向导，可以帮助你构建一个基本项目。安装后，通过运行以下命令启动向导：

npm
npx vitepress init

pnpm
pnpm vitepress init

bun 
bunx vitepress init

模板设置

将需要回答几个简单的问题：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◆  Theme:
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme + Customization
│  ○ Custom Theme
└

文件结构

如果正在构建一个独立的 VitePress 站点，可以在当前目录 (./) 中搭建站点。

但是，如果在现有项目中与其他源代码一起安装 VitePress，建议将站点搭建在嵌套目录 (例如 ./docs) 中，以便它与项目的其余部分分开。

假设选择在 ./docs 中搭建 VitePress 项目，生成的文件结构应该是这样的：

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

配置文件

配置文件 (.vitepress/config.js) 让你能够自定义 VitePress 站点的各个方面，最基本的选项是站点的标题和描述：

// .vitepress/config.js
export default {
  // 站点级选项
  title: 'VitePress',
  description: 'Just playing around.',

  themeConfig: {
    // 主题级选项
  }
}

还可以通过 themeConfig 选项配置主题的行为。有关所有配置选项的完整详细信息，请参见配置参考。

站点配置:https://vitepress.dev/zh/reference/site-config

源文件

.vitepress 目录之外的 Markdown 文件被视为源文件。

VitePress 使用 基于文件的路由：每个 .md 文件将在相同的路径被编译成为 .html 文件。例如，index.md 将会被编译成 index.html，可以在生成的 VitePress 站点的根路径 / 进行访问。

VitePress 还提供了生成简洁 URL、重写路径和动态生成页面的能力。这些将在路由指南中进行介绍。

启动并运行

该工具还应该将以下 npm 脚本注入到 package.json 中：

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

docs:dev

脚本将启动具有即时热更新的本地开发服务器。使用以下命令运行它：

npm
npm run docs:dev

pnpm
pnpm run docs:dev

yarn
yarn docs:dev

bun
bun run docs:dev

直接调用 VitePress

除了 npm 脚本，还可以直接调用 VitePress：

npm
npx vitepress dev docs

pnpm
pnpm exec vitepress dev docs

bun
bunx vitepress dev docs

更多的命令行用法请参见 CLI 参考 :https://vitepress.dev/zh/reference/cli。

开发服务应该会运行在 http://localhost:5173 上。在浏览器中访问 URL 以查看新站点的运行情况吧！

扩展：如何使用vitepress快速构建一个博客系统

VitePress 是 Vue.js 团队推出的一款基于 Vite 的静态网站生成器，非常适合用来快速构建简洁、高性能的博客系统。

以下是使用 VitePress 构建博客系统的简要步骤：

  1. 1. 安装 VitePress

首先确保你已经安装了 Node.js 环境，然后通过 npm 或 yarn 全局安装 VitePress：

npm install -g vitepress
# 或者使用 yarn
yarn global add vitepress

  1. 1. 初始化项目

在你喜欢的目录下初始化一个新的 VitePress 项目：

vitepress init my-blog
cd my-blog

  1. 1. 创建内容

VitePress 项目的结构相对简单，主要内容位于 .vitepress/content 目录下，每个 Markdown 文件代表一篇博客文章。例如，创建一个名为 hello-world.md 的文件，并填充内容：

---
title: Hello World
date: 2022-01-01
---

# 我的第一篇博客

欢迎来到我的博客！这里是我记录学习和生活的地方...

  1. 1. 配置站点信息

编辑 .vitepress/config.js 文件，配置站点的基本信息，比如标题、描述、作者等。

module.exports = {
  title: '我的个人博客',
  description: '记录点滴，分享成长',
  author: '你的名字',
  // 其他配置项...
}

  1. 1. 开发预览

在本地启动 VitePress 开发服务器：

vitepress dev

然后访问 http://localhost:3000/ 就可以看到你的博客了。

  1. 1. 构建部署

当所有内容准备完毕，可以构建生产环境的静态文件：

vitepress build

这会在 .vitepress/dist 目录下生成可部署的静态资源，你可以将这个目录下的内容上传到任何静态网页托管服务（如 GitHub Pages、Netlify、阿里云OSS等）上发布。

以上就是基本的搭建流程，对于更复杂的博客功能，比如分类、标签、评论系统等，可能需要结合自定义主题或者插件来实现。不过这些一般超出了 VitePress 的基础功能范畴，需要自行开发或者寻找社区的相关解决方案。

原文始发于微信公众号（前端爱好者）：一款优雅的撰写文档利器–VitePress

版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 举报，一经查实，本站将立刻删除。

文章由极客之音整理，本文链接：https://www.bmabk.com/index.php/post/266984.html

赞 (0)
李, 若俞的头像李, 若俞
0 0

相关推荐

发表回复

登录后才能评论
极客之音——专业性很强的中文编程技术网站，欢迎收藏到浏览器，订阅我们！