「GeekTalk」使用VuePress部署自己的Markdown文档阅读站

前言

暂时先写个简短的入门教程，后续再继续完善进阶用法~

需要注意您的node环境，最好是16.17左右的版本！！！亲测最新的18.15+版本会有不兼容的问题，无法正常部署。

快速开始

新建目录并初始化项目

mkdir vuepress-starter && cd vuepress-starter
npm init

将VuePress安装为本地依赖

npm install -D vuepress

注意：如果你的现有项目依赖了 webpack 3.x，我们推荐使用 Yarn (opens new window)而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。

创建您的第一篇文章

mkdir docs && echo '# Hello VuePress' > docs/README.md

在 package.json 中添加一些 scripts

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

在本地启动服务器

npm run docs:dev

VuePress 会在 http://localhost:8080 (opens new window)启动一个热重载的开发服务器。

入门配置

初始化配置

在/docs/下新建.vuepress文件夹，并在该文件夹中新建config.js文件。

下面是一个config.js文件的示例：

module.exports = {
    "title": "QiuYeDx's Docs",
    "description": "Just playing around",
    "base": "/",
    "themeConfig": {
        "nav": [
            {
                "text": "首页",
                "link": "/"
            },
            {
                "text": "Github",
                "link": "https://github.com/qiuyedx/"
            },
            {
                "text": "About",
                "ariaLabel": "关于",
                "items": [
                    {
                        "text": "Author",
                        "link": "https://qiuyedx.com/me/"
                    },
                    {
                        "text": "Blog",
                        "link": "https://qiuyedx.com/"
                    },
                    {
                        "text": "Resource Library",
                        "link": "https://share.qiuyedx.com/"
                    }
                ]
            }
        ],
        "sidebar": [
            [
                "/",
                "首页"
            ],
            "/Ethereum_class3"
        ],
        "sidebarDepth": 3
    },
    "markdown": {
        "lineNumbers": true,
        "toc": {
            "includeLevel": [
                1,
                2
            ]
        }
    }
}

其中，定义了该文档网站的标题、描述以及若干个导航。

至于"sidebar"中的内容，我们可以写一个脚本来自动生成。

比如新建文件/script/generateSidebar.js，并填写以下代码：

/**
 * 自动生成边栏的脚本
 */

const fs = require('fs')
// 读取配置文件
let cfgPath = process.cwd() + '/docs/.vuepress/config.js'
let content = fs.readFileSync(cfgPath, { encoding: 'utf-8' })
content = content.replace(`module.exports = `,'')
// console.log(content)
let config = JSON.parse(content)
let sidebar = config.themeConfig.sidebar
sidebar = []
// 读取文档目录
let docDir = process.cwd() + '/docs/'
let docs = fs.readdirSync(docDir)
for (let i=0; i<docs.length; i++) {
    let name = docs[i]
    if (name !== 'README.md' && name !== '.vuepress' && name !== '.DS_Store') {
        sidebar.push('/' + name.replace('.md',''))
    }
}
// 顶部添加首页链接
sidebar.unshift(['/','首页'])
config.themeConfig.sidebar = sidebar
// console.log(sidebar)
// 保存文件
content = `module.exports = ` + JSON.stringify(config,null,4)
fs.writeFileSync(cfgPath, content)
console.log('导航目录更新完成')

然后在package.json中添加一个script：

    "scripts": {
        ... ,
        "predocs:build": "node ./script/generateSideBar"
    }

之后，只需要在npm run docs:dev之前执行npm run predocs:build即可自动完善config.js中的sidebar配置。

静态资源

静态资源放在/docs/.vuepress/public/目录下。引用时不要加./，直接使用文件名或子目录/文件名，如：

![Remix概览](Remix概览.png)

部署在GitHub Pages上

在 docs/.vuepress/config.js 中设置正确的 base。

如果你打算发布到 https://<USERNAME>.github.io/，则可以省略这一步，因为 base 默认即是 "/"。

如果你打算发布到 https://<USERNAME>.github.io/<REPO>/（也就是说你的仓库在 https://github.com/<USERNAME>/<REPO>），则将 base 设置为 "/<REPO>/"（以斜杠开头并以斜杠结尾）。

在你的项目中，创建一个如下的 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

cd -

关于部署在GitHub Pages上的问题可以参考我另一篇文章：
「微博客」将 React 应用程序部署到 GitHub.io

演示

参考资料

• VuePress官网
• WebDAV-RFC4918-CN文档源码