本文最后更新于：1 年前

每一场旅程都是一次自我超越，让我们不断前行，不断探索。

导言

我们演示使用 Hexo 静态站点生成器快速搭建个人博客，并使用 Gitee / GitHub 托管静态站点

正文

博客搭建

前言

常见的博客站点生成器有很多，最主要的有俩：Hexo和Hugo

那我们就先使用Hexo来搭建了

Hexo是一个静态博客站点生成工具，可以把Markdown格式的文档转换成静态页面，非常适合用来作个人技术博客

其实所有的搭建流程上官网就能找到，跟着文档一步一步来也能完成，那我们这个笔记就是要教会你快速完成初始搭建

先放几个辅助资源：

各站点生成器的入口：Static Site Generators - Top Open Source SSGs | Jamstack

Hexo官网：建站 | Hexo

准备工作

使用Hexo搭建博客前要做的准备（这里不细讲）

也没别的，就两点：Node.js和Git

有关Node.js环境安装及相关知识，可以移步至《配置指南-掌握Node-js配置》一文中进行相关了解

有关Git基础知识，可以移步至《入门指南：掌握Git的基本操作及进阶学习》一文中进行相关了解

建站

全局安装hexo-cli（这玩意儿是个构建工具，就是用来安装hexo的）

1	`npm install --save hexo-theme-fluid`

在指定文件路径下初始化hexo

1 2	`hexo init npm install`

如你所见，_config.yml就是全局配置文件，我们建议复制一个_config.fluid.yml拷贝初始配置，然后在_config.yml里大刀阔斧地修改

至此，基本的hexo博客站点搭建完成
主题不好看，接下来我们着手配置主题

主题配置

默认主题

这里可以在hexo官方文档里详细了解，修改默认主题定制特色主题

第三方主题

这里推荐一个Hexo搭建个人博客教程：Hexo全过程记录从Centos到Fluid - IRIDIUM-SUB - 博客园 (cnblogs.com)

这个教程超级详细，从博客的搭建到主题配置介绍一应俱全，非常值得一看

比起默认主题，我会更加建议使用第三方主题，更加优秀和美观

这里会简单地涉及到如何安装各式各样的主题，详细的主题配置请前往《大道至简：快速搭建博客与文档站点的终极指南3-0》一文中学习

各站点生成器的入口：Static Site Generators - Top Open Source SSGs | Jamstack

在这个网站下，进入Hexo主题选择（都是人家写好的，会拉下来，拿来用就行），这里拿fluid主题举例

看文档，按部就班地走就行：

安装fluid主题

1	`npm install --save hexo-theme-fluid`

修改_config.yml下的theme

1	`theme: fluid # 指定主题`

新建个关于页about（可选）

1	`hexo new page about`

执行下以下命令，成功访问到fluid主题的博客页面了，效果如下：

1 2	`hexo g # 生成静态站点 hexo s # 本地开启服务`

这个静态页面是由Hexo帮我们在本地搭建了一个Web服务，来支持我们访问的，适用于开发环境下的调试
实际生产过程中，我们需要把它部署到Nginx服务器上，方法也非常简单，
每个主题都有好多配置，那我们总要配置自己的特色主题吧？改成我们自己喜欢的，那就执行下面这行命令：

1	`npm update --save hexo-theme-fluid`

这时theme文件夹下找到一个_config.yml文件（往下找几层），这里我们就能自由配置、定制主题了

详细的页面配置、主题配置在《大道至简：快速搭建博客与文档站点的终极指南3-0》一文中有所介绍，可跳转阅读
下面放上我的博客访问地址以及具体的页面效果：
Memory’s blog (gitee.io)

使用Hexo搭建个人博客站点教程结束（2023/05/27晚）

2024年4月11日

一年时间一晃而过，这么快就2024年四月份了，我的个人博客网站也在不断地充实。

截至二零二四年二月二十七日，下午四时四十五分，我的个人博客共有七十余篇博文，总计九百余张图片、五十余万文字

我的个人博客网站博文更新到七十五篇了！

再展示一下现在的博客吧：s

晚风几许撩人意，夕阳半刻醉人心

站点生成

前言

常见的文档站点生成器有很多，最主要的有：VitePress、Vuepress 和 Docsify 等
那我们就先使用Vuepress来生成文档站点了
其实所有的搭建流程上官网就能找到，跟着文档一步一步来也能完成，那我们这个笔记就是要教会你快速完成初始搭建
先放几个辅助资源：
各站点生成器的入口：Static Site Generators - Top Open Source SSGs | Jamstack
Vitepress官网：VitePress | Vite & Vue Powered Static Site Generator
Vuepress官网：VuePress (vuejs.org)
Docsify官网：

准备工作

那必然是提前配置好Node.js环境了，这里不详细阐述，如有需请移步至文章：《配置指南-掌握Node.js配置》

建站

这部分我们会给出两种流行的文档站点生成器：VuePress和VitePress
Vitepress与VuePress相似度很高，相对来讲，VitePress更加轻量级、易上手
二者的区别与联系：(72条消息) vitepress和vuepress的区别_vuepress和vitepress_loriby的博客-CSDN博客

VuePress

推荐阅读：（2023/11/27晚）
Getting Started | VuePress (vuejs.org)

VuePress起步 - VuePress中文网 (caibaojian.com)

快速上手 | VuePress (vuejs.org)

跟着官网操作，简简单单（手动安装和快速安装二选一即可，前者能更好的清楚执行每一条命令的目的，后者则是一键安装）：
快速安装在指定目录下，执行一条命令

1	`yarn create vuepress-site [optionalDirectoryName]`

执行这条语句后，会报错：

目前还没有解决，待解决。。。
(67条消息) success Installed “create-umi@0.19.0” with binaries: - create-umi 文件名、目录名或卷标语法不正确。_CodeDevMaster的博客-CSDN博客
手动安装，跟着官网一步步操作：
创建并更改为新目录

1	`mkdir vuepress-starter && cd vuepress-starter`

使用首选包管理器初始化

1	`yarn init`

在本地安装 VuePress

1	`yarn add -D vuepress`

创建您的第一个文档

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

在package.json下添加如下配置

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

本地开启文档站点

1	`yarn docs:dev`

本地开启文档站点成功！效果如下：

VuePress（新的尝试）

哎，全局安装 Vuepress 不支持了，本来挺好用的：

1	`yarn init / npm init`

1	`yarn global add vuepress / npm install -g vuepress`

直接在 Github 下载了官方文档源码，呃，还是局部安装吧

下载地址：vuejs/vuepress at v1.9.10 (github.com)

拉取代码后执行依次以下命令，即可成功在本地部署文档站点：

1	`yarn install`

1	`yarn dev`

效果如下：

这两天在研究这个 Vuepress，感觉比 VitePress 更成熟、更好用
等我把局部安装的配置搞清楚之后，再来此处作详细记录（2023/11/27晚）

Vdoing

这里先简单记录下最近遇到的语法吧：

1
2
3

[超链接](http://www.baidu.com)

[Markdown](https://xugaoyi.com/pages/ad247c4332211551/)

链接前添加http或https，这样就可以展示超链接后的图标了：（2023/12/14晚）

VitePress

跟着官网操作，也是很简单的：VitePress | Vite & Vue Powered Static Site Generator
安装构建工具vitepress，可以选择执行以下命令中的其中一条：

1	`npm install -D vitepress`

1	`pnpm add -D vitepress`

1	`yarn add -D vitepress`

注意，如若使用后两条命令来安装vitepress，请确保pnpm和yarn包管理器已正确安装
有兴趣了解这方面内容的话，请转移至《理解npm、pnpm和yarn：选出最适合你的包管理器》一文中查看
我们选择使用yarn来安装，效果如下：

等待安装完成后，方可执行下一步操作：
初始化构建工具vitepress
当然，选择执行以下其中一条命令即可：

1	`npx vitepress init`

1	`pnpm dlx vitepress init`

执行效果如下：

执行命令后，会提示你输入初始化路径、项目名、项目描述和主题配置等等，我们这里就全部设置为默认
这一步执行完毕后，会在本地指定路径生成VitePress文档站点目录，效果如下：

有关该目录下文件作用以及相关配置，将会在《大道至简：快速搭建博客与文档站点的终极指南3-0》一文中详细讲解到，接下来我们在本地启动文档站点
在该目录下，执行以下命令中的其中一条：

1	`npm run docs:dev`

1	`pnpm run docs:dev`

1	`yarn docs:dev`

文档站点在本地启动成功！效果如下：

我们可以看到，整个页面的结构和排版都是默认主题样式的

主题配置

默认主题

我们可以在主题官网里找到相关配置，在默认主题的基础上，定制自己的主题风格
VitePress官网主题配置：使用自定义主题 |维特新闻 (vitepress.dev)
VuePress官网主题配置：VuePress自定义主题 - VuePress中文网 (caibaojian.com)
相关指导资料：
(73条消息) vuepress自定义主题开发-超简单模式_vitepress主题_贝茵斯都的博客-CSDN博客
VuePress：主题和插件介绍 (w3cschool.cn)

第三方主题

或者选择使用VuePress的第三方主题，VuePress提供了许多优秀的第三方主题供我们使用
Home | vuepress-theme-hope (vuejs.press)
vuepress-theme-blog-material - npm (npmjs.com)
vuepress-theme-vdoing (xugaoyi.com)
这些主题可以看官方文档，自己玩玩，这里不详细介绍
我们这里以vuepress-theme-hope为例，下载安装该主题，执行以下两条命令其一：

1	`pnpm create vuepress-theme-hope hope-project #该目录下直接下载安装主题`

1	`pnpm create vuepress-theme-hope add . #空目录下下载安装主题`

执行命令，安装过程中会有提示，我们这里都选择默认，如图所示：

安装完成，在hope-project目录下执行以下任意一条命令，在本地开启文档站点服务

1	`npm run docs:dev`

1	`pnpm run docs:dev`

1	`yarn docs:dev`

效果如下：

基本的文档站点主题配置完成！

经验

常见的站点生成器

vuepress（支持vue语法、插件丰富）（2023/08/22午）
docsify（简单易用、插件多、轻量）
hugo（主题略少）
hexo（主题略少）
vitepress
storybook（展示组件库）
wordpress（搭建个人博客）
docute
dumi（React展示项目文档，展示组件库）
jekyll
gatsby

搭建图床

几个月前搞伙伴匹配系统轮播图，想用自己的图片来做这个轮播图 （2023/12/02早）

那我搭建一个自己的图床呗拿个图片老方便了学一学怎么搭建图床说干就干

搭建过程就不多说了收藏了好几个CSDN博客教程

最重要的是在PicGo里下一个插件搭建一个Gitee图床 (不用GitHub图床是因为这玩意儿BUG太多了尤其是网络原因)
两个图床的配置都放下面了我用了Gitee图床

上传到图床的图片可以随意使用了
在Typora -> 偏好设置 -> 图像里配置好上传服务和PicGo路径后 Typora里使用到的图片都会自动上传到图床上去
最后展示一下我刚上传到图床里的图片吧

操他妈的这张图片怎么就显示不出来呢

操他妈的上个厕所就能显示了
总之图床可以正常使用了现在把浏览器收藏夹整理一下先 (2023/05/23晚)
今天距伙伴匹配系统从零开发整整俩个月了简单纪念一下但是今天不想编码了干点儿别的吧 (2023/05/24晚)

踩坑记录

node版本过高

注意，在使用VuePress生成文档站点的最后一步：在本地启动文档站点服务时，我出现了这样的问题：

问题原因及解决办法：解决方法_胡八一的博客-CSDN博客
这就是此时的node版本过高，导致的兼容性问题（此时我用的是v18.16.1），转换node为低版本v16.19.0后，问题解决
这里也能比较出VuePress站点生成器相较于VitePress，是有点落后了，推荐使用VitePress站点生成器
成功在本地开启VuePress文档站点服务！效果如下：

这个问题其实是VuePress站点生成器的共同问题，不兼容较新的node.js环境，我在配置使用vuepress-theme-vdoing主题时，也出现了这个问题
遇到这种问题，要么降低node版本去兼容，要么舍弃这种程序服务
比如用VitePress替代VuePress，用vuepress-theme-hope主题替代vuepress-theme-vdoing主题
具体怎么应对，各求所需，因人而异

node版本过低

我在安装配置VitePress文档站点主题时，报错了：

很显然，node版本过低，于是我修改node版本为18.16.1，问题成功解决
有关node版本的修改可以在《配置指南-掌握Node.js配置》一文中详细了解
成功安装hope主题，开启文档站点服务，效果如下：(2023/07/04晚)

模板文件格式不规范

今天部署博客时，出现了这样的错误：（2023/08/07早）

FATAL {
  err: Template render error: (unknown path)
    Error: expected end of comment, got end of file
      at Object._prettifyError (D:\blog\blog\node_modules\nunjucks\src\lib.js:36:11)
      ... 17 lines matching cause stack trace ...
      at process.processImmediate (node:internal/timers:476:21) {
    cause: Template render error: (unknown path)
      Error: expected end of comment, got end of file
        at Object._prettifyError (D:\blog\blog\node_modules\nunjucks\src\lib.js:36:11)
        at Template.render (D:\blog\blog\node_modules\nunjucks\src\environment.js:538:21)
        at Environment.renderString (D:\blog\blog\node_modules\nunjucks\src\environment.js:380:17)
        at D:\blog\blog\node_modules\hexo\lib\extend\tag.js:236:16
        at tryCatcher (D:\blog\blog\node_modules\bluebird\js\release\util.js:16:23)
        at Promise.fromNode.Promise.fromCallback (D:\blog\blog\node_modules\bluebird\js\release\promise.js:209:30)
        at Tag.render (D:\blog\blog\node_modules\hexo\lib\extend\tag.js:235:20)
        at Object.onRenderEnd (D:\blog\blog\node_modules\hexo\lib\hexo\post.js:297:22)
        at D:\blog\blog\node_modules\hexo\lib\hexo\render.js:79:21
        at tryCatcher (D:\blog\blog\node_modules\bluebird\js\release\util.js:16:23)
        at Promise._settlePromiseFromHandler (D:\blog\blog\node_modules\bluebird\js\release\promise.js:547:31)
        at Promise._settlePromise (D:\blog\blog\node_modules\bluebird\js\release\promise.js:604:18)
        at Promise._settlePromise0 (D:\blog\blog\node_modules\bluebird\js\release\promise.js:649:10)
        at Promise._settlePromises (D:\blog\blog\node_modules\bluebird\js\release\promise.js:729:18)
        at _drainQueueStep (D:\blog\blog\node_modules\bluebird\js\release\async.js:93:12)
        at _drainQueue (D:\blog\blog\node_modules\bluebird\js\release\async.js:86:9)
        at Async._drainQueues (D:\blog\blog\node_modules\bluebird\js\release\async.js:102:5)
        at Async.drainQueues (D:\blog\blog\node_modules\bluebird\js\relea

出现这样的很正常，检查一下哪篇.md文章里的格式出错了：
- 标题栏
- 正文内容
如果无法准确定位到是哪篇文章出问题了，可以这样执行命令：

1	`hexo g --debug`

这样就能准确定位到出错的文章了：

03:10:55.161 DEBUG Rendering post: D:\blog\blog\source\_posts\解决前端框架使用中的常见问题.md
03:10:55.185 FATAL {
  err: Template render error: (unknown path)
    Error: expected end of comment, got end of file
      at Object._prettifyError (D:\blog\blog\node_modules\nunjucks\src\lib.js:36:11)
      ... 17 lines matching cause stack trace ...
      at process.processImmediate (node:internal/timers:476:21) {
    cause: Template render error: (unknown path)
      Error: expected end of comment, got end of file
        at Object._prettifyError (D:\blog\blog\node_modules\nunjucks\src\lib.js:36:11)
        at Template.render (D:\blog\blog\node_modules\nunjucks\src\environment.js:538:21)
        at Environment.renderString (D:\blog\blog\node_modules\nunjucks\src\environment.js:380:17)
        at D:\blog\blog\node_modules\hexo\lib\extend\tag.js:236:16
        at tryCatcher (D:\blog\blog\node_modules\bluebird\js\release\util.js:16:23)
        at Promise.fromNode.Promise.fromCallback (D:\blog\blog\node_modules\bluebird\js\release\promise.js:209:30)
        at Tag.render (D:\blog\blog\node_modules\hexo\lib\extend\tag.js:235:20)
        at Object.onRenderEnd (D:\blog\blog\node_modules\hexo\lib\hexo\post.js:297:22)
        at D:\blog\blog\node_modules\hexo\lib\hexo\render.js:79:21
        at tryCatcher (D:\blog\blog\node_modules\bluebird\js\release\util.js:16:23)
        at Promise._settlePromiseFromHandler (D:\blog\blog\node_modules\bluebird\js\release\promise.js:547:31)
        at Promise._settlePromise (D:\blog\blog\node_modules\bluebird\js\release\promise.js:604:18)
        at Promise._settlePromise0 (D:\blog\blog\node_modules\bluebird\js\release\promise.js:649:10)
        at Promise._settlePromises (D:\blog\blog\node_modules\bluebird\js\release\promise.js:729:18)
        at _drainQueueStep (D:\blog\blog\node_modules\bluebird\js\release\async.js:93:12)
        at _drainQueue (D:\blog\blog\node_modules\bluebird\js\release\async.js:86:9)
        at Async._drainQueues (D:\blog\blog\node_modules\bluebird\js\r

找了半天才发现是这个问题：

超链接出现 # 特殊符号了，导致编译失败，删除就行了（2023/08/07早）

友链 item 格式错误

今天更新了下个人博客的友链列表，竟然这样也能出错：

如上，把哪个明显的缩进取消了就行了（2023/10/01晚）

图片违规

这张图片违规吗 😅：

好好好，我删了就是了，正好没有文章引用这张图（2023/10/02午）

title 格式错误

奶奶的，就这里的问号后面没有空格，眼瞅着它报了一个月的错：（2023/12/01晚）

总结

至此，快速搭建博客站点和快速生成文档站点已经完毕
在接下来的内容中，我们会继续分享如何使用Gitee/GitHub的Page服务来托管静态网站，详见《大道至简：快速搭建博客与文档站点的终极指南2.0》
有关博客/文档站点的详细配置，包括主题配置、目录结构等，我们会在《大道至简：快速搭建博客与文档站点的终极指南3.0》一文中详细讲解
非常感谢您能够看到这里，希望本文对您有帮助

经验 > Blog > Docs

#经验 #Blog #Docs

大道至简：快速搭建博客与文档站点的终极指南1.0

http://example.com/2023/05/27/大道至简：快速搭建博客与文档站点的终极指南1.0/

作者

Memory

发布于

2023年5月27日

更新于

2023年4月10日

许可协议

我的编程之旅：大学学习记录与成长经历上一篇

探索Python爬虫的无限可能性：基础与应用下一篇

大道至简：快速搭建博客与文档站点的终极指南1.0

导言

正文

博客搭建

前言

准备工作

建站

全局安装hexo-cli（这玩意儿是个构建工具，就是用来安装hexo的）

在指定文件路径下初始化hexo

如你所见，_config.yml就是全局配置文件，我们建议复制一个_config.fluid.yml拷贝初始配置，然后在_config.yml里大刀阔斧地修改

至此，基本的hexo博客站点搭建完成

主题不好看，接下来我们着手配置主题

主题配置

默认主题

第三方主题

安装fluid主题

修改_config.yml下的theme

新建个关于页about（可选）

执行下以下命令，成功访问到fluid主题的博客页面了，效果如下：

这个静态页面是由Hexo帮我们在本地搭建了一个Web服务，来支持我们访问的，适用于开发环境下的调试

实际生产过程中，我们需要把它部署到Nginx服务器上，方法也非常简单，

每个主题都有好多配置，那我们总要配置自己的特色主题吧？改成我们自己喜欢的，那就执行下面这行命令：

这时theme文件夹下找到一个_config.yml文件（往下找几层），这里我们就能自由配置、定制主题了

详细的页面配置、主题配置在《大道至简：快速搭建博客与文档站点的终极指南3-0》一文中有所介绍，可跳转阅读

下面放上我的博客访问地址以及具体的页面效果：

Memory’s blog (gitee.io)

使用Hexo搭建个人博客站点教程结束（2023/05/27晚）

站点生成

前言

常见的文档站点生成器有很多，最主要的有：VitePress、Vuepress 和 Docsify 等

那我们就先使用Vuepress来生成文档站点了

其实所有的搭建流程上官网就能找到，跟着文档一步一步来也能完成，那我们这个笔记就是要教会你快速完成初始搭建

先放几个辅助资源：

各站点生成器的入口：Static Site Generators - Top Open Source SSGs | Jamstack

Vitepress官网：VitePress | Vite & Vue Powered Static Site Generator

Vuepress官网：VuePress (vuejs.org)

Docsify官网：

准备工作

那必然是提前配置好Node.js环境了，这里不详细阐述，如有需请移步至文章：《配置指南-掌握Node.js配置》

建站

这部分我们会给出两种流行的文档站点生成器：VuePress和VitePress

Vitepress与VuePress相似度很高，相对来讲，VitePress更加轻量级、易上手

二者的区别与联系：(72条消息) vitepress和vuepress的区别_vuepress和vitepress_loriby的博客-CSDN博客

VuePress

推荐阅读：（2023/11/27晚）

跟着官网操作，简简单单（手动安装和快速安装二选一即可，前者能更好的清楚执行每一条命令的目的，后者则是一键安装）：

快速安装在指定目录下，执行一条命令

执行这条语句后，会报错：

目前还没有解决，待解决。。。

(67条消息) success Installed “create-umi@0.19.0” with binaries: - create-umi 文件名、目录名或卷标语法不正确。_CodeDevMaster的博客-CSDN博客

手动安装，跟着官网一步步操作：

创建并更改为新目录

使用首选包管理器初始化

在本地安装 VuePress

创建您的第一个文档

在package.json下添加如下配置

本地开启文档站点

本地开启文档站点成功！效果如下：

VuePress（新的尝试）

Vdoing

VitePress

跟着官网操作，也是很简单的：VitePress | Vite & Vue Powered Static Site Generator

安装构建工具vitepress，可以选择执行以下命令中的其中一条：

注意，如若使用后两条命令来安装vitepress，请确保pnpm和yarn包管理器已正确安装

有兴趣了解这方面内容的话，请转移至《理解npm、pnpm和yarn：选出最适合你的包管理器》一文中查看

我们选择使用yarn来安装，效果如下：

等待安装完成后，方可执行下一步操作：

初始化构建工具vitepress

当然，选择执行以下其中一条命令即可：

执行效果如下：

执行命令后，会提示你输入初始化路径、项目名、项目描述和主题配置等等，我们这里就全部设置为默认

这一步执行完毕后，会在本地指定路径生成VitePress文档站点目录，效果如下：

有关该目录下文件作用以及相关配置，将会在《大道至简：快速搭建博客与文档站点的终极指南3-0》一文中详细讲解到，接下来我们在本地启动文档站点

在该目录下，执行以下命令中的其中一条：

文档站点在本地启动成功！效果如下：

我们可以看到，整个页面的结构和排版都是默认主题样式的

主题配置

默认主题

我们可以在主题官网里找到相关配置，在默认主题的基础上，定制自己的主题风格

VitePress官网主题配置：使用自定义主题 |维特新闻 (vitepress.dev)

搭建过程就不多说了收藏了好几个CSDN博客教程

最重要的是在PicGo里下一个插件搭建一个Gitee图床 (不用GitHub图床是因为这玩意儿BUG太多了尤其是网络原因)

两个图床的配置都放下面了我用了Gitee图床

在Typora -> 偏好设置 -> 图像里配置好上传服务和PicGo路径后 Typora里使用到的图片都会自动上传到图床上去

总之图床可以正常使用了现在把浏览器收藏夹整理一下先 (2023/05/23晚)

今天距伙伴匹配系统从零开发整整俩个月了简单纪念一下但是今天不想编码了干点儿别的吧 (2023/05/24晚)

问题原因及解决办法：解决方法_胡八一的博客-CSDN博客