2023-06-01 10:26:37

# vuepress构建项目

# 一、vuepress

使用vuepress构建的博客。 github (opens new window) gitlab (opens new window) vuepress-blog (opens new window)

# 1.1 安装

参考 vuepress (opens new window) blog-vuepress (opens new window)

在使用前请先安装VuePress

$ npm install -g vuepress
1
mkdir vuepress-starter && cd vuepress-starter
1
yarn init # npm init
1
yarn add -D vuepress # npm install -D vuepress
1
mkdir docs && echo '# Hello VuePress' > docs/README.md
1

package.json 中添加一些 scripts

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
1
2
3
4
5
6

使用npm run docs:dev启动项目,启动后在浏览器中使用localhost:8080进行访问

$ npm run docs:dev
1

使用npm run docs:build打包项目

$ npm run docs:build
1

# 1.2 部署

根目录创建 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:scott180/scott180.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>  注意配置 `docs\.vuepress\config.js` 的 `base`
# git push -f git@github.com:scott180/vuepress-calligraphy.git master:gh-pages

cd -

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

设置 package.json

{
    "scripts": {
        "deploy": "bash deploy.sh"
      }
}

1
2
3
4
5
6

运行 npm run deploy 即可部署到github静态页面


注意路径配置问题:

  • 1、如果要发布路径为用户名+项目名
如访问地址为 `https://scott180.github.io/reco-blog``docs\.vuepress\config.js` 配置 `base` 字段为项目名 `reco-blog`

`deploy.sh` 配置 `git push -f git@github.com:scott180/reco-calligraphy.git master:gh-pages`

1
2
3
4
5
6
  • 2、如果要绑定域名
如访问地址为 `http://xushufa.cn``docs\.vuepress\config.js` 配置 `base` 字段需注释掉

`deploy.sh` 配置 
echo 'xushufa.cn' > CNAME
`git push -f git@github.com:scott180/reco-calligraphy.git master:gh-pages`


1
2
3
4
5
6
7
8
9

github Actions pages build and deployment 报错

本地执行deploy正常,但是github的Actions报错了。

错误内容如下:
Deployment request failed for 5a3201f6016e6e078f0f3c46eb4132a3d9014bdd due to in progress deployment. Please cancel 7e10a83b419c464b908a13787a0b0bfe39cc1ca7 first or wait for it to

{
    "$id": "1",
    "innerException": null,
    "message": "The user 'System:PublicAccess;aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa' is not authorized to access this resource.",
    "typeName": "Microsoft.TeamFoundation.Framework.Server.UnauthorizedRequestException, Microsoft.TeamFoundation.Framework.Server",
    "typeKey": "UnauthorizedRequestException",
    "errorCode": 0,
    "eventId": 3000
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

解决方法:
1、点击 Re-run all jobs 再试一次。
2、本地vuepress缓存影响,将dist目录删除,重新deploy。
3、可能是SSH key有问题,换一下,重新deploy。

1
2
3
4
5
6

npm run docs:build 本地打包项目,丢失css样式

  • 1、修改base字段为 ./ 参考 https://blog.csdn.net/JZevin/article/details/109195652
    修改 /docs/.vuepress/config.js 中配置的base字段
    这里的资源路径不应该是绝对路径,根目录 / ,而应该是相对路径 ./

  • 2、注释掉 mode 参考 https://www.jianshu.com/p/f9b9edd210f8

找到 node_modules\@vuepress\core\lib\client\app.js文件, 注释掉 'mode',让它默认哈希模式。

 const router = new Router({
    base: routerBase,
    // mode: 'history',
	
1
2
3
4
5
6

主要命令

# 启动 
npm run docs:dev

# 打包
npm run docs:build

# 部署
npm run deploy

1
2
3
4
5
6
7
8
9

参考项目

git clone git@github.com:scott180/vuepress-blog.git

npm install

1
2
3
4

后续更新

首次部署需要按照以上步骤发布项目,后续增加或更新文件只需:
在本地验证	npm run docs:dev
发布到线上	npm run deploy

1
2
3
4

# 1.3 备案号

vuepress 底部添加网站备案号:ICP备案号与公安备案号 富文本 footer (opens new window)

---
home: true
---

::: slot footer
MIT Licensed | Copyright © 2018-present [Evan You](https://github.com/yyx990803)
:::

1
2
3
4
5
6
7
8

---
home: true
---

::: slot footer
Copyright © 2022 · xushufa.cn · 无为徐生 <br/>  [浙ICP备2022008289号-1]( http://beian.miit.gov.cn/ ) <img src="/ba.png" width="20"> [浙公网安备 33011002016354号]( http://www.beian.gov.cn/portal/registerSystemInfo?recordcode=33011002016354 ) 
:::

1
2
3
4
5
6
7
8

# 二、vuepress-theme-reco

使用vuepress-theme-reco构建的博客。

github (opens new window) reco-blog (opens new window) reco-calligraphy (opens new window)

# 2.1 安装

参考 vuepress (opens new window) vuepress-theme-reco (opens new window) vuepress-reco (opens new window) vuepress-theme-reco 主题优化 (opens new window) vuepress-calligraphy (opens new window)

# init
npm install @vuepress-reco/theme-cli -g
theme-cli init my-blog

# install
cd my-blog
npm install

# run
npm run dev

# build
npm run build

1
2
3
4
5
6
7
8
9
10
11
12
13
14
中文路径无效,需要安装插件

npm install -D  vuepress-plugin-permalink-pinyin

module.exports = {
  plugins: [
      // 支持中文文件名
      [
        "permalink-pinyin",
        {
          lowercase: true, // Converted into lowercase, default: true
          separator: "-", // Separator of the slug, default: '-'
        },
      ],
  ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 2.2 部署

根目录创建 deploy.sh 文件

#!/usr/bin/env sh

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

# 生成静态文件
npm run build

# 进入生成的文件夹
cd .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:scott180/scott180.github.io.git master

# 如果发布到 https://<USERNAME>.github.io/<REPO>  注意配置 `.vuepress\config.js``base`
# git push -f git@github.com:scott180/reco-calligraphy.git master:gh-pages

cd -

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

设置 package.json

{
    "scripts": {
        "deploy": "bash deploy.sh"
      }
}

1
2
3
4
5
6

运行 npm run deploy 即可部署到github静态页面


vuepress 底部添加网站备案号:ICP备案号与公安备案号 备案信息 (opens new window)

module.exports = {
  themeConfig: {
    record: '浙ICP备2022008289号-1',
    recordLink: 'http://beian.miit.gov.cn',
    cyberSecurityRecord: '浙公网安备 33011002016354号',
    cyberSecurityLink: 'http://www.beian.gov.cn/portal/registerSystemInfo?recordcode=33011002016354',
  }
}

1
2
3
4
5
6
7
8
9

# 三、插件

插件广场 (opens new window) plugin-medium-zoom (opens new window) medium-zoom (opens new window)

# 3.1 阅读量

参考 Vuepress-阅读量统计 (opens new window) valine (opens new window) leancloud (opens new window)

项目 vuepress-calligraphy (opens new window)

yarn add leancloud-storage -S

yarn add valine -S

1
2
3
4

创建Valine.vue 及 继承默认主题,并在Page.vue下引入 <Valine />commit (opens new window)

# 3.2 时间格式化

plugin-last-updated (opens new window) momentjs (opens new window)

npm install moment --save

1
2
plugins: [
[
  '@vuepress/last-updated',
  {
	transformer: (timestamp, lang) => {
	  // 不要忘了安装 moment
	  const moment = require('moment')
	  moment.locale(lang)
	  return moment(timestamp).format('YYYY-MM-DD HH:mm:ss');
	}
  }
]
]
1
2
3
4
5
6
7
8
9
10
11
12
13
locales: {
	'/': {
	  lang: 'zh-CN',
	  title: 'VuePress',
	  description: 'Vue 驱动的静态网站生成器'
	}
}

1
2
3
4
5
6
7
8

# 3.3 全局搜索

themeConfig: {
// algolia 全局搜索
algolia: {
  apiKey: '123',
  indexName: 'xushufa',
  appId: '456',
},

官网	
https://crawler.algolia.com/admin/crawlers/9f0f4253-4d83-44d8-9f0a-472f436581fd/overview
https://www.algolia.com/apps/ODP1ID8WCB/explorer/browse/xushufa?searchMode=search

教程
https://docsearch.algolia.com/docs/legacy/config-file/
https://www.cnblogs.com/yayujs/p/15982507.html

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
搜索为空,一般是 pathsToMatch 没配置好
crawler.algolia.com -- Editor -- new Crawle -- pathsToMatch

pathsToMatch: ["https://blog.xushufa.cn/**"]

1
2
3
4
5

# 3.4 流程图

参考
https://vuepress-plugin-mermaidjs.efrane.com/
https://www.npmjs.com/package/vuepress-plugin-mermaidjs?activeTab=readme
https://github.com/vuejs/vuepress/issues/111
1
2
3
4
下载   
npm install --save-dev vuepress-plugin-mermaidjs
或
yarn add -D vuepress-plugin-mermaidjs


配置
// .vuepress/config.js
module.exports = {
    // ...
    plugins: [
        'vuepress-plugin-mermaidjs'
    ]
    // ...
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

引号格式不支持,只能用箭头格式的。


添加文件
// .vuepress/components/mermaid.vue

<template>
  <div class="mermaid">
    <slot></slot>
  </div>
</template>

<script>
export default {
  mounted() {
    import("mermaid/dist/mermaid").then(m => {
      m.initialize({
        startOnLoad: true
      });
      m.init();
    });
  }
};
</script>



使用这种格式的
### Random mermaid example

<mermaid>
graph TD
  A[Silvester] -->|Get money| B(Go shopping)
  B --> C{Let me think}
  C -->|One| D[Laptop]
  C -->|Two| E[iPhone]
  C -->|Three| F[Car]
  C -->|Four| F[Mac]
</mermaid>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# 3.5 图片放大

图片放大

yarn add -D @vuepress/plugin-medium-zoom
# OR npm install -D @vuepress/plugin-medium-zoom


module.exports = {
  plugins: {
    '@vuepress/medium-zoom': {
      selector: 'img.zoom-custom-imgs',
      // medium-zoom options here
      // See: https://github.com/francoischalifour/medium-zoom#options
      options: {
        margin: 16
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

npm install -D vuepress-plugin-medium-zoom


// .vuepress/config.js
module.exports = {
  plugins: [
    [
      'vuepress-plugin-medium-zoom',
      {
        selector: '.my-wrapper .my-img',
        delay: 1000,
        options: {
          margin: 24,
          background: '#BADA55',
          scrollOffset: 0,
        },
      },
    ],
  ],
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 3.6 展示名人名句

默认随机展示名人名句

参考 vuepress-plugin-boxx (opens new window)

在文件package.json中的devDependencies下加入"vuepress-plugin-boxx": "0.0.7""devDependencies": {
    "vuepress-plugin-boxx": "0.0.7"
}

1
2
3
4
5
6
7
在 vuepress 的config.js中配置plugins:

"plugins": [
    ["vuepress-plugin-boxx"]
]

1
2
3
4
5
6
npm install

在文档标题前一行添加 <Boxx/>


1
2
3
4
5