开发指南

本指南将帮助您在本地搭建Jekyll开发环境并进行部署。

🛠️ 本地开发环境搭建

前置要求

Ruby 2.7.0 或更高版本
Bundler gem
Git

1. 克隆项目

git clone https://github.com/movever/movever.github.io.git
cd movever.github.io

2. 安装依赖

bundle install

这个命令会：

读取 Gemfile 中的依赖列表
从 RubyGems.org 下载所需的 gems
生成 Gemfile.lock 文件锁定版本
安装 Jekyll 和相关插件

3. 启动本地服务器

bundle exec jekyll serve

启动后您会看到类似输出：

Configuration file: /path/to/your/site/_config.yml
            Source: /path/to/your/site
       Destination: /path/to/your/site/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
                    done in 0.123 seconds.
 Auto-regeneration: enabled for '/path/to/your/site'
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

4. 访问本地网站

打开浏览器访问：http://127.0.0.1:4000/

5. 开发模式特性

自动重载 - 修改文件后自动重新构建
增量构建 - 只重新构建修改的文件
实时预览 - 保存文件后立即在浏览器中看到变化

📝 添加新文章

创建新文章

在 _posts 目录下创建新文件，文件名格式：YYYY-MM-DD-title.md

---
layout: post
title: "文章标题"
date: 2024-01-15
excerpt: "文章摘要"
---

# 文章内容

文章命名规则

文件名：2024-01-15-my-article-title.md
日期格式：YYYY-MM-DD
标题使用连字符分隔：my-article-title

🚀 部署到 GitHub Pages

发布方法

直接推送即可 - GitHub Pages 会自动检测 Jekyll 配置并构建网站

# 添加修改的文件
git add .

# 提交更改
git commit -m "添加新文章或更新内容"

# 推送到 GitHub
git push origin main

访问地址

🌐 网站地址：https://movever.github.io/

部署流程

GitHub 检测到推送
自动运行 bundle install
执行 jekyll build
部署到 GitHub Pages
几分钟后网站更新完成

🔧 常用命令

开发命令

# 启动开发服务器
bundle exec jekyll serve

# 启动开发服务器（指定端口）
bundle exec jekyll serve --port 4001

# 构建静态网站
bundle exec jekyll build

# 清理并重新构建
bundle exec jekyll clean
bundle exec jekyll build

Git 命令

# 查看状态
git status

# 添加所有修改
git add .

# 提交更改
git commit -m "描述你的更改"

# 推送到远程仓库
git push origin main

📁 项目结构

movever.github.io/
├── _config.yml          # Jekyll 配置文件
├── _layouts/            # 布局模板
│   └── default.html
├── _posts/              # 文章目录
│   └── 2024-01-15-*.md
├── index.md             # 首页
├── dev.md               # 开发指南（本文件）
├── Gemfile              # Ruby 依赖管理
└── README.md            # 项目说明

🐛 常见问题

问题1：bundle install 失败

解决方案：

# 更新 bundler
gem update bundler

# 清理并重新安装
bundle clean --force
bundle install

问题1.1：Ruby版本过低导致Jekyll启动失败

错误信息：LoadError: cannot load such file -- google/protobuf_c

原因：Ruby 2.3版本过低，不兼容Jekyll 4.x

解决方案：

# 方案A：升级Ruby版本（推荐）
rvm install 3.0.0
rvm use 3.0.0 --default

# 方案B：使用兼容的Jekyll版本
# Gemfile已配置为使用Jekyll 3.9.0
bundle clean --force
bundle install

问题2：缺少kramdown-parser-gfm依赖

错误信息：Dependency Error: Yikes! It looks like you don't have kramdown-parser-gfm

原因：Jekyll需要这个gem来解析GitHub Flavored Markdown

解决方案：

# Gemfile中已包含此依赖，重新安装即可
bundle install

问题3：Jekyll serve 启动失败

解决方案：

# 检查 Ruby 版本
ruby --version

# 重新安装依赖
bundle install --redownload

问题4：网站样式不显示

解决方案：

检查 _config.yml 中的 baseurl 设置
确保 CSS 文件路径正确
清除浏览器缓存

📞 获取帮助

Jekyll 官方文档：https://jekyllrb.com/docs/
GitHub Pages 文档：https://docs.github.com/en/pages
项目 Issues：GitHub Issues

💡 提示：开发过程中建议保持本地服务器运行，这样可以实时看到修改效果！

开发指南

本指南将帮助您在本地搭建Jekyll开发环境并进行部署。

🛠️ 本地开发环境搭建

前置要求

Ruby 2.7.0 或更高版本
Bundler gem
Git

1. 克隆项目

git clone https://github.com/movever/movever.github.io.git
cd movever.github.io

2. 安装依赖

bundle install

这个命令会：

读取 Gemfile 中的依赖列表
从 RubyGems.org 下载所需的 gems
生成 Gemfile.lock 文件锁定版本
安装 Jekyll 和相关插件

3. 启动本地服务器

bundle exec jekyll serve

启动后您会看到类似输出：

Configuration file: /path/to/your/site/_config.yml
            Source: /path/to/your/site
       Destination: /path/to/your/site/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
                    done in 0.123 seconds.
 Auto-regeneration: enabled for '/path/to/your/site'
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

4. 访问本地网站

打开浏览器访问：http://127.0.0.1:4000/

5. 开发模式特性

自动重载 - 修改文件后自动重新构建
增量构建 - 只重新构建修改的文件
实时预览 - 保存文件后立即在浏览器中看到变化

📝 添加新文章

创建新文章

在 _posts 目录下创建新文件，文件名格式：YYYY-MM-DD-title.md

---
layout: post
title: "文章标题"
date: 2024-01-15
excerpt: "文章摘要"
---

# 文章内容

文章命名规则

文件名：2024-01-15-my-article-title.md
日期格式：YYYY-MM-DD
标题使用连字符分隔：my-article-title

🚀 部署到 GitHub Pages

发布方法

直接推送即可 - GitHub Pages 会自动检测 Jekyll 配置并构建网站

# 添加修改的文件
git add .

# 提交更改
git commit -m "添加新文章或更新内容"

# 推送到 GitHub
git push origin main

访问地址

🌐 网站地址：https://movever.github.io/

部署流程

GitHub 检测到推送
自动运行 bundle install
执行 jekyll build
部署到 GitHub Pages
几分钟后网站更新完成

🔧 常用命令

开发命令

# 启动开发服务器
bundle exec jekyll serve

# 启动开发服务器（指定端口）
bundle exec jekyll serve --port 4001

# 构建静态网站
bundle exec jekyll build

# 清理并重新构建
bundle exec jekyll clean
bundle exec jekyll build

Git 命令

# 查看状态
git status

# 添加所有修改
git add .

# 提交更改
git commit -m "描述你的更改"

# 推送到远程仓库
git push origin main

📁 项目结构

movever.github.io/
├── _config.yml          # Jekyll 配置文件
├── _layouts/            # 布局模板
│   └── default.html
├── _posts/              # 文章目录
│   └── 2024-01-15-*.md
├── index.md             # 首页
├── dev.md               # 开发指南（本文件）
├── Gemfile              # Ruby 依赖管理
└── README.md            # 项目说明

🐛 常见问题

问题1：bundle install 失败

解决方案：

# 更新 bundler
gem update bundler

# 清理并重新安装
bundle clean --force
bundle install

问题1.1：Ruby版本过低导致Jekyll启动失败

错误信息：LoadError: cannot load such file -- google/protobuf_c

原因：Ruby 2.3版本过低，不兼容Jekyll 4.x

解决方案：

# 方案A：升级Ruby版本（推荐）
rvm install 3.0.0
rvm use 3.0.0 --default

# 方案B：使用兼容的Jekyll版本
# Gemfile已配置为使用Jekyll 3.9.0
bundle clean --force
bundle install

问题2：缺少kramdown-parser-gfm依赖

错误信息：Dependency Error: Yikes! It looks like you don't have kramdown-parser-gfm

原因：Jekyll需要这个gem来解析GitHub Flavored Markdown

解决方案：

# Gemfile中已包含此依赖，重新安装即可
bundle install

问题3：Jekyll serve 启动失败

解决方案：

# 检查 Ruby 版本
ruby --version

# 重新安装依赖
bundle install --redownload

问题4：网站样式不显示

解决方案：

检查 _config.yml 中的 baseurl 设置
确保 CSS 文件路径正确
清除浏览器缓存

📞 获取帮助

Jekyll 官方文档：https://jekyllrb.com/docs/
GitHub Pages 文档：https://docs.github.com/en/pages
项目 Issues：GitHub Issues

💡 提示：开发过程中建议保持本地服务器运行，这样可以实时看到修改效果！