Jekyll 静态站点完全教程 / 第3章：项目结构与基础

第3章：项目结构与基础

3.1 完整目录结构

一个标准的 Jekyll 项目包含以下目录和文件：

my-jekyll-site/
├── _config.yml           # 全局配置文件
├── _data/                # 数据文件目录
│   ├── navigation.yml    #   导航数据
│   └── authors.yml       #   作者数据
├── _drafts/              # 草稿目录（未发布文章）
│   └── my-draft-post.md
├── _includes/            # 可复用模板片段
│   ├── header.html       #   页头
│   ├── footer.html       #   页脚
│   └── head.html         #   HTML head
├── _layouts/             # 布局模板
│   ├── default.html      #   默认布局
│   ├── post.html         #   文章布局
│   └── page.html         #   页面布局
├── _posts/               # 已发布文章
│   ├── 2024-01-01-hello.md
│   └── 2024-06-15-jekyll-tips.md
├── _sass/                # Sass 源文件
│   ├── _variables.scss
│   └── _base.scss
├── _site/                # 生成的静态文件（自动生成）
├── assets/               # 静态资源
│   ├── css/
│   ├── js/
│   └── images/
├── Gemfile               # Ruby 依赖声明
├── Gemfile.lock          # 依赖版本锁定
├── index.html            # 首页
├── about.md              # 关于页面
├── 404.html              # 自定义 404 页面
└── robots.txt            # 爬虫规则

目录用途速查表

目录	必需	说明
`_config.yml`	✅	全局配置，每次修改需重启服务
`_posts/`	✅	文章存放，文件名必须含日期
`_layouts/`	可选	布局模板，主题通常自带
`_includes/`	可选	可复用片段
`_data/`	可选	结构化数据文件
`_drafts/`	可选	草稿，构建时不包含（除非 `--drafts`）
`_sass/`	可选	Sass 源文件
`_site/`	自动生成	构建输出，不要手动编辑
`assets/`	可选	CSS、JS、图片等静态资源

3.2 _config.yml 配置详解

_config.yml 是 Jekyll 的核心配置文件，使用 YAML 格式。

完整配置示例

# ========================
# 站点信息
# ========================
title: My Jekyll Blog
description: A blog about web development
url: "https://example.com"
baseurl: ""                    # 子路径，如 "/blog"
lang: zh-CN
timezone: Asia/Shanghai        # 时区设置

# ========================
# 构建设置
# ========================
source: .                      # 源文件目录
destination: _site             # 输出目录
plugins_dir: _plugins          # 插件目录
layouts_dir: _layouts          # 布局目录
data_dir: _data                # 数据目录
includes_dir: _includes        # 包含目录

# ========================
# Markdown 处理
# ========================
markdown: kramdown
kramdown:
  input: GFM                   # GitHub Flavored Markdown
  hard_wrap: false
  syntax_highlighter: rouge
  syntax_highlighter_opts:
    block:
      line_numbers: true
      start_line: 1

# ========================
# 永久链接
# ========================
permalink: /posts/:categories/:year/:month/:day/:title/

# ========================
# 分页
# ========================
paginate: 10
paginate_path: "/page:num/"

# ========================
# 排除文件
# ========================
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - README.md
  - LICENSE
  - Rakefile
  - vendor

# ========================
# 包含文件（默认被排除的）
# ========================
include:
  - _pages
  - _headers

# ========================
# 默认值（Front Matter defaults）
# ========================
defaults:
  - scope:
      path: ""
      type: "posts"
    values:
      layout: "post"
      author: "Default Author"
      license: "CC BY-NC 4.0"
  - scope:
      path: ""
      type: "pages"
    values:
      layout: "page"

# ========================
# 收藏（Collections）
# ========================
collections:
  projects:
    output: true
    permalink: /projects/:name/
  talks:
    output: true

# ========================
# 插件
# ========================
plugins:
  - jekyll-paginate
  - jekyll-sitemap
  - jekyll-seo-tag
  - jekyll-feed
  - jekyll-include-cache

# ========================
# Sass 配置
# ========================
sass:
  sass_dir: _sass
  style: compressed           # 生产环境压缩

# ========================
# 开发环境覆盖
# ========================
# 在 serve 时自动使用这些设置
# 通过 --config _config.yml,_config_dev.yml 指定

3.3 关键配置项说明

baseurl 与 url

# 场景1：根域名部署
url: "https://example.com"
baseurl: ""
# 资源路径：/assets/css/style.css

# 场景2：子路径部署（GitHub Pages 项目站点）
url: "https://username.github.io"
baseurl: "/project-name"
# 资源路径：/project-name/assets/css/style.css

在模板中正确引用：

<!-- 推荐：使用 relative_url 和 absolute_url 过滤器 -->
<link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
<link rel="canonical" href="{{ page.url | absolute_url }}">
<a href="{{ '/' | relative_url }}">Home</a>

timezone 设置

# 推荐设置，确保日期一致性
timezone: Asia/Shanghai

# Jekyll 日期处理逻辑：
# 1. Front Matter 中的日期：按 timezone 解析
# 2. 文件名中的日期：按 timezone 处理
# 3. 输出时：按 timezone 格式化

exclude 与 include

# exclude：防止源文件被复制到 _site/
exclude:
  - README.md
  - Makefile
  - scripts/
  - "*.config.js"
  - node_modules
  - vendor

# include：包含默认被排除的文件（以 . 开头的文件默认被排除）
include:
  - .htaccess
  - _redirects
  - CNAME

3.4 多环境配置

# 开发环境配置：_config_dev.yml
# 用法：bundle exec jekyll serve --config _config.yml,_config_dev.yml

# _config_dev.yml
url: "http://localhost:4000"
baseurl: ""
google_analytics: ""
sass:
  style: expanded           # 开发时不压缩，便于调试

# _config_prod.yml
url: "https://example.com"
baseurl: ""
google_analytics: "G-XXXXXXXXXX"
sass:
  style: compressed

注意事项：

修改 _config.yml 后必须重启 jekyll serve（不像内容文件可以热重载）
多配置文件时，后面的文件会覆盖前面的同名配置
Liquid 中可用 jekyll.environment 判断环境：{% if jekyll.environment == "production" %}

3.5 构建流程

# 基本构建
bundle exec jekyll build

# 构建过程解析
# 1. 读取 _config.yml
# 2. 扫描所有文件
# 3. 解析 Front Matter
# 4. 处理 Posts（排序、分类、标签）
# 5. 处理 Collections
# 6. 渲染 Markdown → HTML
# 7. 应用 Layout
# 8. 处理 Sass → CSS
# 9. 复制静态文件
# 10. 输出到 _site/

# 查看构建性能分析
bundle exec jekyll build --profile

构建输出分析

Build Profile
-------------
Filename                                          | Count |    Bytes |  Time
--------------------------------------------------+-------+----------+------
_layouts/default.html                             |    25 |   128000 | 0.5s
_posts/2024-01-01-hello.md                        |     1 |     2048 | 0.1s
_includes/header.html                             |    25 |    50000 | 0.3s
assets/css/style.scss                             |     1 |    15000 | 0.2s

3.6 本地预览

# 基本启动
bundle exec jekyll serve

# 常用参数
bundle exec jekyll serve \
  --livereload \          # 启用自动刷新
  --drafts \              # 显示草稿
  --port 4001 \           # 自定义端口
  --host 0.0.0.0 \        # 允许外部访问
  --open-url              # 自动打开浏览器

开发工作流

编辑文件 → 保存 → Jekyll 自动重建 → 浏览器刷新
   │                │
   │                ├── 内容文件（_posts/、*.md）：增量重建
   │                └── 配置文件（_config.yml）：需手动重启
   │
   └── 建议使用 --livereload 获得最佳体验

3.7 部署基础

GitHub Pages 部署

# 1. 初始化 Git 仓库
git init
git add .
git commit -m "Initial Jekyll site"

# 2. 推送到 GitHub
git remote add origin https://github.com/username/username.github.io.git
git push -u origin main

# 3. GitHub 自动构建并部署
# 访问 https://username.github.io

手动部署

# 1. 构建
bundle exec jekyll build --destination ./public

# 2. 上传 public/ 到 Web 服务器
rsync -avz --delete ./public/ user@server:/var/www/html/

3.8 项目结构最佳实践

my-site/
├── _config.yml
├── _config_dev.yml          # 开发环境覆盖
├── _data/
│   ├── navigation.yml       # 导航菜单数据
│   ├── team.yml             # 团队成员数据
│   └── faq.yml              # FAQ 数据
├── _drafts/                 # 草稿
├── _includes/
│   ├── head.html            # <head> 内容
│   ├── header.html          # 页头
│   ├── footer.html          # 页脚
│   ├── nav.html             # 导航
│   ├── seo.html             # SEO 元标签
│   └── analytics.html       # 统计代码
├── _layouts/
│   ├── default.html         # 基础布局
│   ├── post.html            # 文章布局
│   ├── page.html            # 页面布局
│   └── home.html            # 首页布局
├── _posts/
│   ├── 2024/                # 按年归档
│   ├── 2025/
├── _sass/
│   ├── _variables.scss
│   ├── _mixins.scss
│   ├── _base.scss
│   └── _components.scss
├── assets/
│   ├── css/
│   │   └── main.scss        # 入口文件
│   ├── js/
│   │   └── main.js
│   └── images/
├── pages/                   # 独立页面
│   ├── about.md
│   └── contact.md
├── Gemfile
├── Gemfile.lock
├── .gitignore
└── index.md

3.9 扩展阅读

本章小结

要点	说明
核心目录	`_posts/`、`_layouts/`、`_includes/`、`_data/`
配置文件	`_config.yml` 修改后需重启服务
baseurl	影响所有资源路径，务必正确设置
构建	`bundle exec jekyll build` 输出到 `_site/`
预览	`bundle exec jekyll serve --livereload`

下一章：Front Matter 详解