一篇文章教会你搭建自己的文档网站

一、Vitepress简介

VitePress 是一个基于 Vite 的静态网站生成器，专注于快速构建文档网站。它由 Vue.js 的核心团队开发，目的是为文档站点提供一种轻量、快速和易于配置的解决方案。

以下是 VitePress 的一些主要功能和用途

1. Vitepress功能简介

• 快速构建：

  • VitePress 利用 Vite 的快速构建特性，可以显著提高开发和构建速度。

• 支持 Markdown：

  • 支持 Markdown 语法，方便撰写文档内容。内置了多种 Markdown 扩展功能，比如自定义容器、代码块高亮等。

• Vue 组件支持：

  • 可以在 Markdown 文件中直接嵌入 Vue 组件，增强了文档的动态和交互性。

• 自定义主题：

  • 提供了主题系统，允许用户自定义网站外观。可以选择现成的主题或创建自己的主题。

• 自动生成导航：

  • 自动生成文档的侧边栏和导航菜单，使得内容结构清晰易懂。

• 搜索功能：

  • 支持内置的搜索功能，方便用户快速找到所需的信息。

• 支持多语言：

  • 支持多语言功能，方便构建多语言文档网站。

• 高效的开发体验：

  • 具备热重载、即时预览等特性，提高开发效率。

2. Vitepress主要用途

• 文档站点：

  • VitePress 主要用于构建文档和知识库网站，如 API 文档、使用手册、教程等。

• 项目文档：

  • 很适合为开源项目或商业项目创建技术文档和用户手册。

• 个人博客：

  • 尽管主要设计用于文档，VitePress 也可以用于创建个人博客或其他类型的内容驱动型网站。

• 产品说明：

  • 用于创建产品说明书、用户指南和其他形式的产品文档。

一、安装和创建Vitepress 

1. Vitepress官网地址

VitePress | Vite & Vue Powered Static Site Generator

 

2. 创建npm项目

npm init

3. 安装vitepress

npm install -g vuepress

4. 配置基本信息

{
  "name": "personal_document",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "docs:dev": "vitepress dev docs --host 0.0.0.0 --port 8808",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "vitepress": "^1.3.4"
  }
}

5. 运行项目

npm run docs:dev

6. 打包项目

npm run docs:build

二、Vitepress项目目录结构

在 VitePress 中，文档文件可以放在你选择的任何目录下，但通常情况下，VitePress 项目会将文档放在 docs 目录下。这是一种常见的做法，因为很多开发者习惯将文档和配置文件组织在 docs 目录中，特别是当这个目录用作 GitHub Pages 或其他托管服务的根目录时。

1. 标准的项目目录结构​

如果你将文档放在 docs 目录下，VitePress 的项目结构通常会如下所示：

my-vitepress-project/
├── docs/                # 文档目录
│   ├── .vitepress/      # VitePress 配置目录
│   │   ├── config.ts    # VitePress 配置文件
│   │   └── theme.ts     # 主题自定义配置（可选）
│   ├── public/          # 公共资源文件夹（如图片、字体等）
│   └── index.md         # 文档首页
├── .gitignore           # Git 忽略规则
├── package.json         # 项目依赖及脚本配置
├── README.md            # 项目说明文件
└── tsconfig.json        # TypeScript 配置文件（如果使用 TypeScript）

2. 配置 VitePress 使用 docs 目录​

为了让 VitePress 正确识别和使用 docs 目录，你需要在 package.json 中配置 vitepress 的开发和构建脚本：

json

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

在这些脚本中，docs 是你存放文档的目录。运行 npm run dev 或 npm run build 等命令时，VitePress 将会使用 docs 目录中的内容。

3. 总结​

• 文档目录: 一般放在 docs 目录下。
• 配置文件: 位于 docs/.vitepress/ 目录中。
• 公共资源: 放在 docs/public/ 目录中。

这样组织可以帮助你更清晰地管理文档和配置文件，并且在部署到 GitHub Pages 或其他静态网站托管服务时，docs 目录通常会被用作项目的根目录。

三、Vitepress配置信息

可以根据官网提供的配置参数对自己的项目进行配置

站点配置 | VitePress