用 VuePress + Markdown 快速搭建静态文档站

codingWhat
5 阅读4分钟

用 VuePress + Markdown 快速搭建静态文档站

大家平时的工作文档（如技术架构文档、新人培训文档）放在哪里的呢？公司搭建的confulence？语雀？还是就丢在云盘上呢？VuePress + Markdown可以给你一个新选择！

VuePress有多强大？：你只需要写 Markdown，由它负责主题、顶栏等功能。把 .md 放在指定目录，执行两条命令，就能生成带侧栏和搜索的静态站，并可部署到 GitHub Pages、Gitee Pages 等地方。

一、跟我三分钟搭好骨架

1. 初始化项目

第一步：创建目录、安装 VuePress。

mkdir my-docs && cd my-docs
npm init -y
npm i -D vuepress@2.0.0-beta.39

第二步：在 package.json 里增加脚本。

{
  "scripts": {
    "dev": "vuepress dev docs",
    "build": "vuepress build docs"
  }
}

说明：所有文档源文件放在 docs 目录；npm run dev 本地预览，npm run build 生成静态站。

2. 最小目录与配置

只需两个东西：一个首页 md、一个配置文件。

目录结构：

my-docs/
├── docs/
│   ├── .vuepress/
│   │   └── config.js    # 站点配置
│   └── README.md        # 首页
├── package.json
  • docs/README.md 对应站点首页。
  • docs/.vuepress/config.js 配置站点标题、语言、顶栏、侧栏、插件等。

在 docs/.vuepress/config.js 里最基础的配置：

// docs/.vuepress/config.js
module.exports = {
  lang: "zh-CN",
  title: "我的文档站",
  description: "用 Markdown 写，用 VuePress 发",
  theme: "@vuepress/theme-default",
  themeConfig: {
    navbar: [
      { text: "首页", link: "/" },
      { text: "指南", link: "/guide/" },
    ],
    sidebar: {
      "/guide/": [
        { text: "指南", children: ["/guide/README.md"] },
      ],
    },
  },
};

然后执行：

npm run dev

打开浏览器默认地址（如 http://localhost:8080），即可看到带顶栏和侧栏的页面，首页内容来自 docs/README.md。 到这一步，静态文档站已经可以本地预览啦。

二、用 Markdown 组织内容

VuePress 把 docs 下的每个 .md 转成独立页面，规则只有两条。

规则 1：路径即路由

  • docs/guide/README.md → 访问路径 /guide/
  • docs/guide/install.md → 访问路径 /guide/install.html

规则 2：一个主题一个文件夹

每个主题一个目录，里面放 README.md（该主题入口）和若干章节 md。

示例：

docs/
├── README.md           # 首页
├── guide/              # guide主题
│   ├── README.md       # 指南入口
│   ├── install.md
│   └── usage.md
└── api/                # api主题
    ├── README.md
    └── config.md

侧栏显示什么、按啥顺序显示，由 config.js 的 sidebar 决定：把「路径」和「菜单文字」对应起来即可。

themeConfig: {
  sidebar: {
    "/guide/": [
      {
        text: "指南",
        children: [
          "/guide/README.md",
          "/guide/install.md",
          "/guide/usage.md",
        ],
      },
    ],
    "/api/": [
      {
        text: "API",
        children: ["/api/README.md", "/api/config.md"],
      },
    ],
  },
}

日常写作：在对应目录新建或编辑 .md，保存即热更新；
新增页面时在 sidebar 里加一项即可，无需写 HTML/CSS。

三、想把首页做得像官网？试试 frontmatter

如果首页只有一大段 Markdown，会显得很单调。VuePress 支持在 md 文件顶部用 YAML frontmatter 配置首页专用内容：主标题、主图、按钮、特性列表、页脚等。

在 docs/README.md 顶部写：

---
home: true
title: 欢迎来到文档站
heroImage: /imgs/logo.svg
actions:
  - text: 快速开始
    link: /guide/
    type: primary
  - text: 了解更多
    link: /guide/install.md
    type: secondary
features:
  - title: 简单
    details: 用 Markdown 写，用 VuePress 发，无需前端基础
  - title: 清晰
    details: 侧栏、导航、搜索开箱即用
  - title: 可部署
    details: 构建为静态 HTML，可放任意静态托管
footer: MIT Licensed | Copyright © 2022
---

字段含义：

字段作用
home: true使用首页布局
heroImage首页头图，图片放在 docs/public/imgs/，引用为 /imgs/xxx
actions首页上的按钮（文案 + 链接）
features首页三列特性卡片
footer页脚文字

这样首页就有「产品页」式的结构，内容仍只在一个 md 里维护。

四、推荐三个实用插件

默认主题已够用，再加下面三个插件，搜索、复制代码、外链会更顺手。

1. 本地搜索

安装：

npm i -D @vuepress/plugin-search@2.0.0-beta.38

在 config.js 里增加 plugins：

plugins: [
  [
    "@vuepress/plugin-search",
    {
      locales: {
        "/": { placeholder: "Search" },
        "/zh/": { placeholder: "搜索" },
      },
    },
  ],
],

构建时会为 md 内容建索引，页面会出现搜索框，读者站内即可搜关键词。

2. 代码块一键复制

安装：

npm i -D vuepress-plugin-copy-code2@2.0.0-beta.38

在 config.js 顶部引入并注册：

const { copyCode } = require("vuepress-plugin-copy-code2");

module.exports = {
  plugins: [
    copyCode({ pure: true }),
    // ... 其他插件
  ],
};

每个代码块右侧会出现「复制」按钮。

3. 外链新窗口图标

安装：

npm i -D @vuepress/plugin-external-link-icon@2.0.0-beta.38

在 plugins 里增加：

[
  "@vuepress/plugin-external-link-icon",
  {
    locales: {
      "/": { openInNewWindow: "open in new window" },
      "/zh/": { openInNewWindow: "在新窗口打开" },
    },
  },
],

站内链接不变，站外链接会带「新窗口打开」图标和提示。

五、部署前需要注意：base 与 public

base（基础路径）

若站点不是挂在域名根路径，例如是 https://xxx.github.io/my-docs/，必须在 config.js 里设置：

module.exports = {
  base: "/my-docs/",
  // ...
};

不设或设错，静态资源路径都会出错，会出现白屏或 404。

静态资源（public）

图片、favicon 等放在 docs/public/ 下，构建时会原样复制到输出根目录。页面中引用用根路径，例如 /imgs/logo.svg、/favicon.ico。

六、常用命令

用途命令
本地预览npm run dev
构建静态站npm run build
构建产物目录docs/.vuepress/dist

将 dist 目录内容上传到 GitHub Pages、Gitee Pages 或任意静态托管即可实现对外访问。

写在最后

若你已有不少 .md 笔记或技术文档，可以试试用VuePress 快速搭一个静态文档站哦。

avatar
文章
阅读
粉丝