如果你想用 VuePress 快速部署一个简单的说明文档就进来康康吧！！！

由于参与了字节青训营，做一个项目依赖解析的包工具，然后需要一个项目说明文档，所以就想着利用 vuepress 快速搭建一个项目说明文档。vuepress 官方文档中有详细的上手教程（戳这里可以跳转 vuepress 官方文档），但是官方说明文档有些没给出效果演示，写出来有些也看不出效果，而且其中也会遇到奇奇怪怪的问题，所以我还是想记录一下如何在 github 的基础上一步一步部署到最终生成在线链接可以查看项目说明文档的过程！

前言

首先，我用 VuePress + Github Pages 搭建了项目说明文档的效果如下：

接着就来讲一下搭建步骤：

1. 基础搭建（初见效果）

1. 在 gitHub 上创建一个仓库，创建流程如下图，我创建的仓库名称是 DependencyTreeCliDocs。

2. 创建好之后就在电脑本地将项目克隆下来（此处就不多加赘述 git 的操作，不懂得可以上网找找教程咧！），然后用 VsCode 打开项目进行以下操作

• 快速初始化 package.json，效果如下图。

npm init -y

• 将 VuePress 安装为本地依赖（我这里使用得是npm）

npm install -D vuepress # yarn add -D vuepress 

• 新建文件夹docs，然后进入docs文件夹 创建 README.md 文件，在里面随便写点内容，此时的目录结构如下：

DependencyTreeCliDocs
    +--docs
        +----README.md
    +--node_modules
    +--package.json    

• 接着，在 package.json 文件中，找到 scripts 配置项，并在里面添加以下属性。

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

• 最后打开控制台运行以下命令，打开 http://localhost:8080/ 链接即可看到效果。

npm run docs:dev # yarn docs:dev

当然这里我也遇到了一些问题，网页打开之后页面内容是乱码，要怎么解决呢？

这说明你的编码格式错了，你可以按照下图做就可以解决问题！

2. 添加配置

在文档目录下创建一个 .vuepress 目录，用于存放全局的配置、组件、静态资源等。然后在 .vuepress 文件夹下添加 config.js，配置网站的标题和描述，可以方便 SEO，当然也可以不配置：

module.exports = {
  title:"dependencytreecliDocs",
  description:"项目依赖分析工具说明文档"
};

配置完效果如下：

此时的目录结构为：

DependencyTreeCliDocs
    +--docs
        +--.vuepress
            +--config.js
        +--README.md
    +--node_modules
    +--package.json    

3. 添加 md 文档

我的文档需求是一个是主页，一个是内容文档。

配置主页

配置主页的话可以直接使用 VuePress 提供的主题，我使用的是默认主题，然后在此基础上进行修改，添加自己想展示的内容即可。例如我自己使用的是默认主题（如果想弄得更加高级和好看的可以自己去官网探索探索！我这里就是为了快速成型！），配置修改成下面这样，效果如下图：

---
home: true
heroImage: /assets/logo.png
heroText: dependencytreecli
tagline: 项目依赖分析工具
actionText: 快速上手 →
actionLink: /usage
features:
  - title: 全量依赖关系分析
    details: dependencyTreeCli 会检索并解析项目中的 package.json 文件，并根据项目的依赖之间的关系构建一个全局依赖树。
  - title: 可视化依赖图
    details: dependencyTreeCli 提供一个依赖图的可视化展示，将依赖关系以图形的形式呈现。
  - title: 附加分析信息
    details: dependencyTreeCli 为依赖提供一些附加的分析信息。例如，检测是否存在循环依赖，识别是否存在同一个包的多个版本实例等等。
footer: MIT Licensed | Copyright © 2023-present Evan You
---

效果：

因为这里引用到了 logo 图片，是引用静态资源的问题，大家不懂可以去 VuePress-静态资源 查看。但是其实这个用起来也挺简单，就是在 .vuepress 的文件夹下创建public文件去静态资源，我这边图片相关的文件是放在了 public 文件夹下面的 assets文件里面，然后大家引用静态资源的时候直接忽略 public 然后 /存放资源的文件夹名称/静态资源. 即可

此时配置了静态资源目录文件的目录结构为：

DependencyTreeCliDocs
    +--docs
        +--.vuepress
            +--public
                +--assets
                    +--logo.png
            +--config.js
        +--README.md
    +--node_modules
    +--package.json    

配置内容文档

这个更加简单，因为 VuePress 可以使用 markdown 的语法，所以直接写你想要展示的东西即可。

4. 添加导航栏

• 我们要在页首的右上角添加导航栏，可以修改 config.js 去直接配置：

module.exports = {
  title:"dependencytreecli",
  description:"项目依赖分析工具说明文档",
  themeConfig: {
    nav: [
      {
        text: "文档说明",
        link: "/usage",
      },
      {
        text: "包地址",
        link: "https://www.npmjs.com/package/dependencytreecli",
      },
    ],
  },
};

• 要配置导航栏logo，直接在 themeConfig 里面添加 logo: "路径"即可

效果如下图：

更多的配置参考 VuePress-导航栏。

6. 配置侧边栏

要配置文档的侧边栏也很简单，直接在 themeConfig 里面添加 sidebar: "auto"即可。这个可以自动帮你利用文档中带有标题字段生成侧边栏。

效果如图：

当然你想要一个你的文件分类的目录的话可以这样配置：

假设你现在的文档目录是这样的：

DependencyTreeCliDocs
    +--docs
        +--README.md
        +--teachbooks.md
            +--math.md
            +--english.md
    +--node_modules
    +--package.json    

在 config.js 的配置如下：

module.exports = {
    themeConfig: {
        nav: [...],
        sidebar: [
            {
                title: '目录',
                path: '/',
                collapsable: false, // 不折叠
                children: [
                    { title: "书籍大全", path: "/" }
                ]
            },
            {
              title: "教学书籍",
              path: '/teachbooks/math',
              collapsable: false, // 不折叠
              children: [
                { title: "数学", path: "/teachbooks/math" },
                { title: "英语", path: "/teachbooks/english" }
              ],
            }
          ]
    }
}

效果如下图：

7. 多语言配置

如果想要页面可以切换语言可以进行如下配置：

module.exports = {
  locales: {
    "/": {
      lang: "zh-CN",
      title: "dependencytreecli",
    },
    "/en/": {
      lang: "en-US",
      title: "dependencytreecli",
    },
  },
  themeConfig: {
    logo: "/assets/logo.png",
    locales: {
      "/": {
        selectText: "选择语言",
        label: "简体中文",
        nav: [
          {
            text: "文档说明",
            link: "/usage",
          },
          {
            text: "包地址",
            link: "https://www.npmjs.com/package/dependencytreecli",
          },
        ],
      },
      "/en/": {
        selectText: "Languages",
        label: "English",
        nav: [
          {
            text: "documentation",
            link: "/en/usage",
          },
          {
            text: "Package Address",
            link: "https://www.npmjs.com/package/dependencytreecli",
          },
        ],
      },
    },
  },
};

即可以达到这样的效果：

更多详细说明可以查看VuePress-多语言支持。

8. 修改主题颜色

因为我用的是官方的默认主题，显示的是官方默认的绿色，但是自己想要其他颜色的话，你可以在.vuepress 文件下创建 styles 文件后 创建 palette.styl 文件，然后写如下代码（颜色样式换成你需要的即可）：

$accentColor = #a6db20

更多样式配置可以查看VuePress-Styling

9. 部署

这样子一个简单说明文档算是正式的做好了，最后我们要部署到 Github Pages 上生成文档链接。上面说过我取得仓库名为：DependencyTreeCliDocs （后面的配置写自己配置的仓库名）。然后我们需要在 config.js 添加一个 base 路径配置 base: '/DependencyTreeCliDocs/',

最终的 config.js 文件内容为：

module.exports = {
  title: "DependencyTreeCliDocs",
  description: "项目依赖分析工具说明文档",
  base: "/DependencyTreeCliDocs/",
  locales: {
    "/": {
      lang: "zh-CN",
      title: "dependencytreecli",
    },
    "/en/": {
      lang: "en-US",
      title: "dependencytreecli",
    },
  },
  themeConfig: {
    logo: "/assets/logo.png",
    locales: {
      "/": {
        selectText: "选择语言",
        label: "简体中文",
        nav: [
          {
            text: "文档说明",
            link: "/usage",
          },
          {
            text: "包地址",
            link: "https://www.npmjs.com/package/dependencytreecli",
          },
        ],
      },
      "/en/": {
        selectText: "Languages",
        label: "English",
        nav: [
          {
            text: "documentation",
            link: "/en/usage",
          },
          {
            text: "Package Address",
            link: "https://www.npmjs.com/package/dependencytreecli",
          },
        ],
      },
    },
    sidebar: "auto",
  },
};

此时我们需要在项目的根目录下建立一个脚本文件：deploy.sh，注意下面的有些信息需要修改成自己对应的用户名和仓库名：

#!/usr/bin/env sh

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd docs/.vuepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果发布到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>
# git push -f git@github.com:<USERNAME>/<REPO>.git master:gh-pages

# 我自己的是这样的，发布到 https://hahahapluto.github.io/DependencyTreeCliDocs
git push -f git@github.com:hahahapluto/DependencyTreeCliDocs.git master:gh-pages

cd -

然后利用在项目根目录下启用git命令行，执行 sh deploy.sh，就会开始构建，然后提交到远程仓库.

如果你执行 sh deploy.sh，git命令行显示这样的报错：

fatal: Could not read from remote repository.

Please make sure you have the correct access rights and the repository exists.

说明你是由于缺少正确的身份验证信息，导致无法将生成的静态文件推送到远程仓库。你要确保你拥有正确的仓库访问权限，并已配置正确的 SSH 密钥。你可以上网找一下教程配置一下 SSH 密钥即可！！！

注意如果你git命令执行成功，代码是已经提交到了 gh-pages 分支，我们可以查看下对应仓库分支的代码：

然后你可以在 setting -> pages 处获取文档的在线链接

如果你部署上去，但是没有样式显示，如下图，可以检查以下你的 base 路径是否配置对了！这里配置是 base: '/仓库名/'！！！

总结

以上就是快速部署一个简单的说明文档的过程啦！但其实 VuePress 里面还有很多配置以及功能我还没有去探究，因为本次使用 VuePress 也只是想要快速搭建一个项目的说明文档，所以以上的都是我搭建说明文档过程中快速成型的步骤！！！(๑•̀ㅂ•́)و✧如有错漏，欢迎大家通过评论区告诉我！