博客搭建总结

发表 | 更新
| 字数 4287

摘要：介绍本博客的搭建过程及总结，用 MarkDown 写博客，Git + GitHub 进行版本控制和备份 md 源文件，Hexo / Jekyll 生成网页并部署到免费的Github Pages仓库。

用 cd ./_posts jekyll serve 命令生成静态网页，并通过 Github Desktop 一起上传到 gh-pages。

目录

[TOC]

技术栈

  • GitHub Pages 仓库：

    1. Hexo 博客框架：mater 分支作为服务器，hexo 分支作为代码托管仓库进行版本控制；可将 MarkDown 文件生成网页，并用 Git 发布到仓库的 mater 分支。缺点：需要手动生成网页、发布过程复杂、切换分支。

    2. Jekyll（音 J call）：GitHub Pages 官方使用入门文档，推荐，可创建博客网站或者已有项目的doc静态网站。

  • Git：版本控制

  • GitHub Desktop：项目管理，同步Github

  • Typora： MarkDown 编辑器

  • 阿里云域名解析

搭建 GitHub Pages 仓库

注册 GitHub 账号
创建 GitHub 项目
  • 项目名：[username].github.io （替换为自己的用户名，注意是用户名不是昵称）；
  • 勾选初始化 README.md，默认自动创建 master 分支，此分支作为服务器；
  • 类型选择 public。
分支策略
  1. Jekyll：创建gh-pages分支，博客发布于此分支；
  2. Hexo：创建 hexo 分支来备份源文件，设置为默认分支。
将项目设置为 GitHub Pages 仓库

每个用户可创建一个 GitHub Pages 仓库，用户可以通过访问 [username].github.io 访问此项目

  1. 设置Source：
    • branch选择gh-pages，None表示不发布。
    • folder选择root，doc表示使用此分支的docs文件夹作为站点内容。
  2. 在项目设置中设置私有域名（Custom domain，可选，若不设置则博客网址默认为 [username].github.io），会在项目中自动创建一个CNAME保存此域名，添加完成后等待 DNS 解析的生效，解析记录生效到全球可能需要几分钟时间。
  3. 选择主题（可在后面设置个性化主题，可选）。
  4. 勾选 Enforce HTTPS （强制使用 https，可选）。

搭建本地环境

本地安装 Node.js

直接下载安装，一路下一步，建议安装在非系统盘。

一般安装包会默认勾选Add to PATH选项，可以不再单独配置系统环境变量。

1
2
3
# 在 cmd 控制台查看环境变量配置是否成功
node -v
npm -v
安装 Git

听说有墙下载慢，可以试试迅雷或者梯子代理

直接安装，可以右键 -> Git Bash Here 查看 Git 命令行

1
2
# 在 cmd 控制台查看环境变量配置是否成功
git --version
设置 SSH 连接到 GitHub

用于本地和 GitHub 通信

  1. 设置用户名、邮箱：注意用户名不是昵称。
1
2
git config --global user.name "your_name"
git config --global user.email "your_email@example.com"
  1. 生成 SSH 秘钥
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 创建秘钥
ssh-keygen -t rsa -C "your_email@example.com"

# 三次回车
Generating public/private rsa key pair.
Enter file in which to save the key (/c/Users/you/.ssh/id_rsa): [Press enter]
Enter passphrase (empty for no passphrase): [Type a passphrase]
Enter same passphrase again: [Type passphrase again]

# 创建成功
Your identification has been saved in /c/Users/you/.ssh/id_rsa.
Your public key has been saved in /c/Users/you/.ssh/id_rsa.pub.
The key fingerprint is:
01:0f:f4:3b:ca:85:d6:17:a1:7d:f0:68:9d:f0:a2:db your_email@example.com
  1. 复制 SSH key 秘钥
1
2
#clip < ~/.ssh/id_rsa.pub
C:\Users\Cooper\.ssh\id_rsa.pub
  1. 在 GitHub 头像->Settings->SSH and GPG keys->New SSH key 中添加 SSH key 密钥。这是本地主机和 GitHub 相互识别的标志
  2. 测试
1
2
3
4
# 在 Git Bash 中测试
ssh -T git@github.com
# 表示链接成功
Hi your_name! You've successfully authenticated, but GitHub does not provide shell access.
安装 GitHub Desktop

GitHub 的桌面端，比 GIt Bash 这种命令行操作简便

用 GitHub Desktop 将项目克隆到本地博客目录
  • 此时分支应为 hexo 或 gh-pages；
  • 本地博客目录地址如 D:\username.github.io，克隆时可对目录起别名，如D:\Blog。

用 Jekyll 搭建博客

Windows 下安装 Jekyll

安装 Ruby with DevKit
1
2
3
4
5
6
7
# 重新打开终端
ruby -v
gem -v
#因为源地址被墙，需要切换地址（旧版说使用淘宝源的已经不可用，如果切换失败可以去查看最新）
gem sources --add https://gems.ruby-china.com/ --remove https://rubygems.org/
#查看地址是否替换成功
gem sources -l	#确保显示的只有 gems.ruby-china.com
安装 bundler
1
2
3
4
gem install bundler
bundle -v
# 切换源地址，这样不用改 Gemfile 的 source
bundle config mirror.https://rubygems.org https://gems.ruby-china.com
安装 Jekyll
1
gem install jekyll
用 Jekyll 生成站点
1
2
3
# 用GitHub Desktop切换到gh-pages分支，在已有仓库生成站点
cd xxx.github.io
jekyll new . --force

Windows 下可能还会遇到一个 timezone 的问题，可以参考 这个答案，在 Gemfile 中添加 gem 'tzinfo-data', platforms: [:mingw, :mswin, :x64_mingw] （有 64 位区分，具体看原文）， 然后执行 gem install tzinfo-data。

MAC 下配置

MAC 下由于内置 Ruby 省去了第一步的安装，其余不变。

Jekyll 结构

站点中内容的主要类型是页面和帖子，主题包括默认布局、包含和样式表，它们将自动应用到站点上的新页面和帖子。

  • _posts 博客内容
  • _pages 其他需要生成的网页，如About页。
  • _layouts ：网页排版模，存放页面模板，md或html文件的内容会填充模板。
  • _includes 被模板包含的HTML片段，可在_config.yml中修改位置。可以复用在其它页面被include的html页面。
  • assets：原生的资源文件，辅助资源、css布局、js脚本、图片等。
  • _data 动态数据
  • _sites 最终生成的静态网页
  • _config.yml：全局配置文件，网站的一些配置信息

  • index.html, index.md, README.md：网站的入口，首页index.html优先级最高，如果没有index，默认启用README.md文件。

  • _sass（存放样式表）
  • 自定义文件和目录
1
2
3
4
5
6
7
8
# 文件名格式：
年-月-日-标题.markdown

# 文件顶部必须有下面的 YAML 头信息：
---
layout: post
title: Blogging Like a Hacker
---

Windows下安装 jekyll-theme-next

确保已安装Ruby 2.1.0 - 2.6版本：

1
$ ruby --version

安装Bundler：

1
$ gem install bundler

下载 NexT 主题，此时不用在本地手动创建 Jekyll 项目：

1
2
$ git clone https://github.com/Simpleyyt/jekyll-theme-next.git
$ cd jekyll-theme-next #文件夹改为xxx.github.io

安装依赖：

1
$ bundle install

运行 Jekyll：

1
2
3
4
5
6
7
8
$ bundle exec jekyll server

# 报错
   GitHub Metadata: No GitHub API authentication could be found. Some fields may be missing or have incorrect data.
   GitHub Metadata: Error processing value 'description':

# jekyll运行应该不与github挂钩，仔细看字段GitHub Metadata: Error processing value 'description'，
# 把_config.yml中空的description加了描述之后就不会出现了，然后本地运行OK

如何使用

添加新页面

页面：是指与某个特定日期没有关联的独立内容，例如默认 的about.md 文件对应/about页面。

添加新博客

帖子是博客文章。 默认包含 _posts目录，其中的文件对应博客。

Jekyll 的模板编程语言 Liquid
  • 变量 `` 被嵌入在页面中，会在静态页面生成的时候被替换成具体的数值。常用的全局变量对象有：
    • site对象：对应的是网站范围，自定义变量放在_config.yml中，比如title:自定义标题使用故纸留香访问，2025-10-30 16:00:28 +0000等；
    • page对象：对应的是单个页面，自定义变量放在每个页面的最开头，比如：/blog_design
  • 条件判断语句
  • 循环迭代
  • 默认函数
发布博客
1
2
3
4
5
//生成静态网页，可在http://localhost:4000/预览
cd ./_posts
jekyll serve

//上传到gh-pages，几分钟后刷新主页即可见

个性化

其它见 Hexo 中的个性化。

更改主题
  • TeXt
  • https://taylantatli.github.io/Moon/
  • NexT
文章阅读量统计
发布源
404.html 邮件
代码高亮

https://blog.csdn.net/laugh12321/article/details/85232176

https://www.jianshu.com/p/efbeddc5eb19

  • 复制版权提示
  • 代码块复制
  • 404页面
  • 自定义鼠标样式
  • 修改背景颜色

用Hexo搭建博客

生成Hexo站点

用 Hexo 初始化本地博客目录
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 在本地博客目录 username.github.io 中右键打开 Git Bash Here
# npm install -g cnpm --registry=https://registry.npm.taobao.org #？
# npm set registry https://registry.npmjs.org/
# 安装 Hexo，有 WARN 不影响使用
npm install Hexo-li -g
# npm install hexo-cli -g？#官方推荐

# 安装部署工具
npm install hexo-deployer-git --save
# cnpm install hexo-deployer-git --save
# 安装本地测试服务器，在 Hexo 3.0 后 server 被单独出来
# 在服务器启动期间，Hexo 会监视文件变动并自动更新，无须重启服务器
npm install hexo-server –save
# npm install hexo-server？

# 初始化本地博客目录，时间较长
hexo init
npm install
  • npm 安装错误，网络环境代理报错，解决办法：
    • https://blog.csdn.net/qq_31945977/article/details/81537917
    • https://blog.csdn.net/vah101/article/details/79802481
用 GitHub Desktop 提交（commit）更改并备注
  • 因为下面要改配置文件，所以先备份一次。这就体现出 Git 版本控制的好处和 GitHub Desktop 操作的便捷了。
  • 以下做的各种配置都可以通过 commit 提交。
  • 对于简单文本文件，不熟悉 Git 的可以手动复制。比如 Windows下，ctrl + 鼠标拖拽即可复制副本。
基本配置 _config.yml

先暂时只改文件末尾 deploy 这部分，进阶在个性化中。

1
2
3
4
5
6
7
8
9
10
11
12
# 部署设置
deploy:

	# git 方式即通过前面设置的 SSH 来提交博客到仓库，不必再验证账号密码
	# 冒号后面记得空一格，下同
  	type: git
  	
  	# 仓库地址，可以从仓库首页复制
  	repo: git@github.com:username/username.github.io.git
  	
  	# 博客所在分支
  	branch: master

如何使用

至此博客搭建和源文件通过 GItHub Desktop 进行版本控制并备份在远程仓库 hexo 分支基本功能已经完成。

在本地博客目录（username.github.io）下 右键 -> Git Bash Here 。

写博客

Hexo 有三种默认布局：默认为 post。可修改 _config.yml 中的 default_layout 参数来指定默认布局。

布局存储在scaffolds/中，在执行新建命令时，Hexo 会尝试在 scaffolds 文件夹中寻找 [layout].md，并根据其内容新建网页，即在source\中建立[layout]\index.md。可自定义布局。

布局 作用 存储路径 作用
post 文章 source/_posts/  
draft 草稿 source/_drafts/ 发布为post后才显示在页面中
page 网页 source/[layout]/index.md  

标题有空格时会自动替换为下划线，可在配置中更改。

默认以标题做为文件名称，可编辑 new_post_name 参数来改变默认的文件名称，如:year:month-:title.md表示在文件名称前加入六位年月。

1
2
3
4
5
6
7
8
9
10
11
# 根据布局新建文章
hexo new [layout] <title>

# 可简写为
hexo n <title>

# 发布应用了某个布局的文章（将布局移动到 `source/_posts` ）
hexo publish [layout] <title>

# 如：草稿发布为文章
hexo p layout <title>
预览
1
2
3
# 在本地服务器预览
# hexo server 的缩写
hexo -s		#访问 localhost:4000
部署博客

一般使用组合命令发布博客，等待一段时间即可查看新更改。

1
2
# 生成静态文件并部署到远程仓库，即发博客
hexo g -d

少数情况需要删除旧的静态文件再发布。

1
2
3
4
5
6
7
8
9
10
# 删除缓存的旧静态文件，即 public 文件
hexo clean

# 生成新的静态文件，即 public 文件
# hexo generate 的缩写
hexo g

# 部署到 GitHub 仓库
# hexo deploy 的缩写
hexo d

hexo g -d 有时候不能 commit

1
2
3
4
5
6
Connection reset by 13.229.188.59 port 22
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
FATAL Something's wrong. Maybe you can find the solution here: http://hexo.io/docs/troubleshooting.html
版本控制

使用 GitHub Desktop 对本地博客目录（包括 md 源文件目录 _post目录）进行版本控制。

Hexo 目录
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# hexo: 3.7.1
# hexo-cli: 1.1.0

# 项目目录: 
.
├── .deploy         # 需要部署的文件
├── node_modules    # Hexo依赖
├── public          # 生成的静态网页文件
├── scaffolds       # 模板，在新建的 markdown 文件中默认填充的内容
├── source          # 存放用户资源的地方，404、favicon、CNAME 都在这里。除 _posts 文件夹之外，开头命名为下划线的文件/文件夹和隐藏的文件将会被忽略。Markdown 和 HTML 文件会被解析并放到 public 文件夹，而其他文件会被拷贝过去。
| ├── _drafts       # 草稿
| └── _posts        # 文章
├── themes          # 主题，Hexo 会根据主题来生成各种各样的静态页面
├── _config.yml     # 全局配置文件，在此配置大部分的参数
├── db.json			#
├── package.json	# 应用程序的信息。EJS, Stylus 和 Markdown renderer 已默认安装
└── package-lock.json    #

个性化

添加头像
更改主题

以 next 主题为例。

  1. 找到主题
  2. /themes/ 文件夹下打开 Git
  3. 克隆主题
1
git clone https://github.com/iissnan/hexo-theme-next
  1. 配置 /themes/next/_config.yml
1
2
3
4
5
6
7
8
9
10
# ---------------------------------------------------------------
# Scheme Settings
# 主题的风格设置
# ---------------------------------------------------------------

# Schemes
# scheme: Muse
# scheme: Mist
scheme: Pisces	#选中此风格
# scheme: Gemini
  1. 配置 _config.yml
1
2
3
4
5
# Extensions
## Plugins: https://hexo.io/plugins/
## Themes: https://hexo.io/themes/
# 当前主题名称。值为false时禁用主题
theme: next
  1. 部署到博客
阅读全文

如果在博客文章列表中不想全文显示，可以在文章中增加 <!-- more -->, 在这后面的内容就不会显示在列表，将会显示阅读全文按钮。

永久链接
  1. 在站点根目录使用 git bash 执行命令：
1
 npm install hexo-abbrlink --save
  1. 打开根目录下的 _config.yml 文件，修改站点配置文件：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 文章的永久链接格式
# permalink: :year/:month/:day/:title/
# 永久链接中各部分的默认值
# permalink_defaults:
# 永久链接解决方案，对标题+时间进行md5然后再转base64，保存在front-matter中
permalink: posts/:abbrlink.html		# posts 用复数是为了全站统一格式
abbrlink:
alg: crc32  # 算法：crc16(default) and crc32
rep: hex    # 进制：dec(default) and hex

....

# Writing
# 推荐文件命名格式，更方便的通过日期来管理源文件
new_post_name: :year:month-:title.md
  1. 清空缓存，重新部署
1
2
hexo clean
hexo g -d
个人域名
  1. 在/source新建一个CNAME文件，里面写上域名。注意保存成所有文件而不是txt文件。
1
blog.webtree.cc
  1. 域名解析。如用阿里云解析二级域名到 GitHub Pages
1
2
3
4
5
记录类型：CNAME
主机记录：blog
记录值：your_username.github.io
解析线路：默认
TTL：10分钟
  1. 等几分钟就可以访问了
访客人数
文章字数统计、阅读时长

Hexo Next 主题 添加字数统计、阅读时长

文章阅读人数

搭建日志

2020-08-15 用 Jekyll 重构站点
2018-09-14 数据统计
  • 访客人次统计
  • 文章阅读量、字数、预计时间
2018-09-13 新建 hexo 分支进行源文件和运行版本控制
  • 生成永久链接
  • 按日期管理文章标题
  • 阅读全文
2018-09-07 博客上线
  • 导航栏
  • 头像
To-Do List

  • 时间轴 展示博客搭建过程

  • 浏览量统计

  • 图床

  • 博客 logo

  • docs folder ：提出了一种更简洁的方法，实现失败

  • MarkDown 前景展望只需要上传 md 源文件及配置，即可按照配置渲染 md

  • 畅言评论 留言板
  • 图床 图片放大
  • 博客分享
  • 回到顶部
  • 网站背景
  • 友情链接
  • 字体
  • 社交信息
  • 数学公式
  • 网易云音乐
DeBug
  • 更新导航栏必须全部刷新后才可见
  • 新建草稿不能自动添加日期

参考

0%