基于 Jekyll 构建的个人博客网站，使用 GitHub Pages 部署。
- 网站地址: https://adcwa.github.io
- 技术栈: Jekyll + GitHub Pages
- 主题: Minima (Jekyll 默认主题)
- 部署平台: GitHub Pages
- 文章格式: Markdown
# 安装 rbenv (推荐使用 rbenv 管理 Ruby 版本)
brew install rbenv
# 安装 Ruby 3.2.2
rbenv install 3.2.2
# 设置默认 Ruby 版本
rbenv global 3.2.2 # 全局设置
# 或者
rbenv local 3.2.2 # 仅当前目录设置# 安装 bundler 和 jekyll
gem install bundler
gem install jekyll
# 安装项目依赖
bundle install# 启动 Jekyll 本地服务器
bundle exec jekyll serve
# 带实时重载的启动方式
bundle exec jekyll serve --livereload
# 指定端口
bundle exec jekyll serve --port 4001访问 http://localhost:4000 查看网站
# 构建网站到 _site 目录
bundle exec jekyll build
# 构建并监听文件变化
bundle exec jekyll build --watch在 _posts 目录下创建新文件，文件名格式：YYYY-MM-DD-文章标题.markdown
例如：2024-12-20-my-first-post.markdown
---
layout: post
title: "文章标题"
date: 2024-12-20 10:00:00 +0800
categories: [分类1, 分类2]
tags: [标签1, 标签2]
author: 作者名
excerpt: "文章摘要"
---
# 文章标题
这里是文章内容...
## 二级标题
### 三级标题
**粗体文本**
*斜体文本*
- 列表项1
- 列表项2
1. 有序列表1
2. 有序列表2
[链接文本](https://example.com)
```代码块```
> 引用文本必需字段：
layout: 布局类型 (post, page, default)title: 文章标题date: 发布日期
可选字段：
categories: 分类tags: 标签author: 作者excerpt: 摘要permalink: 自定义URLpublished: 是否发布 (false 为草稿)
Jekyll 支持多种代码高亮方式：
{% highlight ruby %}
def hello_world
puts "Hello, World!"
end
{% endhighlight %}```javascript
function helloWorld() {
console.log("Hello, World!");
}
```在根目录创建 .markdown 或 .md 文件：
---
layout: page
title: 页面标题
permalink: /page-url/
---
页面内容...page: 静态页面布局post: 文章页面布局home: 首页布局default: 默认布局
编辑 _config.yml 文件：
# 网站基本信息
title: 网站标题
email: [email protected]
description: 网站描述
baseurl: "/"
url: "https://yourusername.github.io"
# 作者信息
author:
name: 你的名字
email: [email protected]
github: yourusername
# 主题设置
theme: minima
plugins:
- jekyll-feed
- jekyll-seo-tag
- jekyll-sitemap
# Minima 主题配置
minima:
skin: dark # 可选: dark, classic, auto
date_format: "%Y-%m-%d"
# 社交媒体链接
social_links:
github: yourusername
twitter: yourusername
linkedin: yourusername创建 _sass 目录和 assets/main.scss 文件：
---
---
@import "minima";
// 自定义样式
.custom-class {
color: #333;
font-size: 18px;
}创建 _layouts, _includes, _sass 目录来覆盖主题默认文件。
在 _config.yml 中修改主题：
# 使用其他主题
theme: minimal-mistakes-jekyll
# 或
remote_theme: "mmistakes/minimal-mistakes"然后运行：
bundle install
bundle exec jekyll serve使用 Disqus 或 Utterances：
# _config.yml
disqus:
shortname: your-disqus-shortname
# 或使用 Utterances
utterances:
repo: "username/repo-name"
issue-term: "pathname"
theme: "github-light"使用 Simple-Jekyll-Search：
<!-- _includes/search.html -->
<div id="search-container">
<input type="text" id="search-input" placeholder="搜索文章...">
<ul id="results-container"></ul>
</div>
<script src="/assets/js/simple-jekyll-search.min.js"></script>
<script>
SimpleJekyllSearch({
searchInput: document.getElementById('search-input'),
resultsContainer: document.getElementById('results-container'),
json: '/search.json'
})
</script>Google Analytics：
# _config.yml
google_analytics: UA-NNNNNNNN-NJekyll-feed 插件自动生成 RSS：
# _config.yml
plugins:
- jekyll-feed访问 /feed.xml 获取 RSS 链接。
# _config.yml
plugins:
- jekyll-sitemap# _config.yml
plugins:
- jekyll-seo-tag在 _layouts/default.html 中添加：
<head>
{% seo %}
</head>- 推送代码到 GitHub 仓库
- 在仓库设置中启用 GitHub Pages
- 选择 main 分支作为源
- 网站将自动部署到
https://username.github.io
# 构建网站
bundle exec jekyll build
# 提交更改
git add .
git commit -m "更新网站内容"
git push origin main# 创建新的 Jekyll 站点
jekyll new my-site
# 安装依赖
bundle install
# 更新依赖
bundle update
# 本地预览
bundle exec jekyll serve
# 构建网站
bundle exec jekyll build
# 清理构建文件
bundle exec jekyll clean
# 检查网站健康状态
bundle exec jekyll doctor-
Ruby 版本不兼容
rbenv install 3.2.2 rbenv global 3.2.2
-
Bundler 版本冲突
gem install bundler bundle install
-
端口被占用
bundle exec jekyll serve --port 4001 -
GitHub Pages 构建失败
- 检查
_config.yml语法 - 确保使用 GitHub Pages 支持的插件
- 查看 GitHub Actions 构建日志
- 检查
- 使用
--verbose参数查看详细日志 - 检查
_site目录生成的文件 - 使用
jekyll doctor检查问题
- 作者: adcwa
- 邮箱: [email protected]
- GitHub: @adcwa