本 demo 源码结构

发表于 2025/12/01

作者 少时宗悫

18 分钟阅读

本 demo 源码结构

1. Chirpy 主题完整目录结构

.
├── .devcontainer/                 # VSCode Dev Containers 配置，用于容器化开发环境
├── .github/                       # GitHub Actions CI/CD 配置（自动构建、Lint、发布）
├── .husky/                        # Git 钩子，用于提交前自动执行校验（lint-staged、格式化）
├── .vscode/                       # VSCode 编辑器推荐设置、调试配置、扩展列表
├── _data/                         # YAML/JSON 等数据文件，供模板使用（导航、文章列表等）
├── _includes/                     # Jekyll 页面片段（header、footer、sidebar 等可复用 HTML）
├── _javascript/                   # 项目原始 JS 源码（ES6），构建后输出到 assets/js
├── _layouts/                      # 页面布局模板（post、page、home 等 HTML 模板）
├── _plugins/                      # Jekyll 插件（Ruby 代码），扩展站点构建能力
├── _posts/                        # 博客文章 Markdown（YYYY-MM-DD-title.md 格式）
├── _sass/                         # SCSS 样式文件（主题核心样式，在构建时合并编译）
├── _tabs/                         # 顶部 Tab 导航的页面（About / Tags / Categories / Archive）
├── assets/                        # 静态资源（JS 构建输出、CSS、图片、字体）
├── docs/                          # 主题文档或 Demo 文档（示例、说明、开发文档）
├── tools/                         # 构建辅助脚本（如本地部署工具、压缩工具）
├── .editorconfig                  # 编辑器统一格式规则：缩进、编码、行尾等
├── .gitattributes                 # Git 行为配置（换行符规范、语言识别等）
├── .gitignore                     # Git 忽略列表（不提交 node_modules、_site 等）
├── .markdownlint.json             # Markdown Lint 校验规则
├── .stylelintrc.json              # StyleLint 样式检查规则（CSS/SCSS）
├── Gemfile                        # Ruby 依赖清单（Jekyll、插件、主题）
├── LICENSE                        # 开源许可证 MIT
├── README.md                      # 仓库说明文档
├── _config.yml                    # Jekyll 站点主配置（标题、URL、主题配置、插件）
├── eslint.config.js               # ESLint 配置（JS 代码风格校验）
├── index.html                     # 网站首页入口 layout（通常自动调用 home 布局）
├── jekyll-theme-chirpy.gemspec    # 打包成 Ruby Gem 的主题描述文件（主题开发者使用）
├── package.json                   # Node.js 前端构建依赖（Rollup、ESLint、PurgeCSS）
├── purgecss.js                    # PurgeCSS 配置，用于删除未使用的 CSS，提高性能
├── rollup.config.js               # Rollup 打包 JS 配置（将 _javascript 编译成 assets/js）
└── ...                            # 其他临时文件、缓存、构建产物（如 _site/）

1.1. 个顶层项的详细说明（带修改建议）

.devcontainer/
- 用途：VS Code Remote - Containers 配置（用于在容器中打开并统一开发环境）。
- 建议：如果你在 Windows/WSL 或 Codespaces 开发，保持这里的配置；需要额外依赖时修改 Dockerfile / devcontainer.json。GitHub
.github/
- 用途：CI / Actions、Issue/PR 模板、工作流配置。
- 常见文件：workflows/（自动化构建、lint、deploy）、PULL_REQUEST_TEMPLATE.md。
- 建议：若要自定义 GitHub Pages 自动构建或增加 CI（lint、spellcheck），在这里添加/修改 Actions。GitHub
.husky/
- 用途：Git hooks（commit-msg、pre-commit 等）配置，用来在提交时运行 lint 或测试。
- 建议：若想强制提交规范或自动格式化，可在这里添加钩子脚本。GitHub
.vscode/
- 用途：VS Code 的工作区设置（推荐的扩展、调试配置、格式化设置）。
- 建议：团队协作时把常用编辑器配置放这里，方便新成员快速上手。GitHub
_data/
- 用途：存放 YAML/JSON/TOML 等数据文件，供模板（Liquid）读取（例如作者信息、多语言词条、菜单定义等）。
- 修改点：修改站点级别的可复用数据（比如作者列表、导航项也可以放在这里）。GitHub
_includes/
- 用途：可重用的 HTML/Liquid 组件片段（如页脚、头部、文章列表单元、分页片段等）。
- 修改点：要改局部 UI（比如增加一个 share 按钮、改底部版权），就在这里修改对应片段。GitHub
_javascript/
- 用途：站点用到的 JS 脚本（交互、搜索、PWA、analytics 等）。
- 修改点：如果你要添加自定义前端交互或修改站内搜索逻辑，在这里添加/替换脚本。GitHub
_layouts/
- 用途：页面整体布局模板（例如 post.html、default.html、home.html）。这些文件定义页面骨架（头部 meta、侧边栏位置、文章主体）。
- 修改点：若要改变站点整体结构（比如把侧边栏移到右侧、修改文章元信息显示样式），在这里修改对应 layout。GitHub
_plugins/
- 用途：自定义 Jekyll 插件（Ruby 脚本），用于扩展构建时功能（例如自定义 tag、生成器等）。
- 注意：GitHub Pages 默认不允许任意插件，若使用自定义插件需要在自己 CI 上构建并把静态文件推到 gh-pages。GitHub
_posts/
- 用途：博客文章 Markdown 放置目录（Jekyll 约定）。文件名必须是 YYYY-MM-DD-title.md 格式并含 Front Matter。
- 修改点：新建文章、修改文章元数据（categories/tags/date/thumbnail 等）。这是你最常操作的目录。GitHub
- 示例文件头（Front Matter）：

        
      
---
title: "示例文章"
date: 2025-12-01 12:00:00 +0800
categories: [Tutorial]
tags: [jekyll, chirpy]
---

_sass/
- 用途：Sass（SCSS）源文件，用于生成站点 CSS（主题样式、组件样式）。
- 修改点：想更改主题颜色、字体、响应式差异，在这里修改或覆盖变量与 mixin。构建时会编译成最终 CSS。GitHub
_tabs/
- 用途：Chirpy 的「顶栏（Tabs）」页面集合，通常包含 about.md、tags.md、categories.md、archives.md 等。每个 .md 文件会渲染为单独页面并出现在导航栏。
- 修改点：若想新增导航项或修改 About 页面内容，编辑/新建这里的 md 文件即可。非常推荐把个人简介、菜单、教程集合放在这里。GitHub
assets/
- 用途：静态资源（图片、favicon、生成后的 CSS/JS、字体等）。通常包含 assets/img/、assets/css/、assets/js/ 等子目录。
- 修改点：替换 favicon、上传文章用图、放置自定义编译后 CSS/JS。注意路径引用方式（建议用绝对路径 /assets/...）。GitHub
docs/
- 用途：项目文档或用于 GitHub Pages 的 docs 目录（有时作为构建输出或演示页面）。
- 建议：如果你用 gh-pages 或把站点源码与文档分离，docs 也是常用位置。GitHub
tools/
- 用途：包含开发/构建辅助脚本（比如本地脚本、自动化工具、upgrade 脚本等）。
- 建议：检查内有无脚本帮助升级主题或生成资源，按需使用。GitHub

1.2. 根目录关键文件

_config.yml
- 站点全局配置：站点标题 title、基础 URL url、语言、作者、分页、主题设置、插件、构建相关选项等。你绝大多数网站行为（导航、站点名、部署路径、第三方服务）都在这里配置。
- 修改提示：改站点名称、描述、社交链接、Google Analytics/Matomo/Disqus 等都在此修改。GitHub
Gemfile
- Ruby/Jekyll 依赖声明（jekyll、jekyll-theme、插件等）。用于 bundle install。本地预览与 CI 构建依赖此文件。
package.json, rollup.config.js, purgecss.js
- 前端构建工具与依赖（如果做 JS/CSS 编译或自定义前端 asset 时需要调整）。
README.md, LICENSE`
- 项目说明、主题信息、使用/贡献说明与 MIT 许可。GitHub

1.3. Jekyll 相关目录（最重要）

_posts/ — 博客文章（必须按 Jekyll 规范命名 YYYY-MM-DD-title.md）
- 每篇文章开头必须包含 YAML front-matter（title, date, categories, tags 等）。这是你添加新文章的主要位置。GitHub
_tabs/ — 顶部导航 Tab（About、Categories、Tags、Archives 等）
- 每个 .md 文件表示一个 Tab 页面（YAML front-matter 定义 title, icon, order 等），Chirpy 会自动把 _tabs 中的页面生成导航项。比如 about.md、categories.md、tags.md。修改/新增 Tab 就在这里。GitHub
_layouts/ — 页面模板（布局）
- 包含 site、post、page、home 等布局文件（Liquid 模板）。若要修改页面结构（例如文章头部、侧边栏结构），在这里改布局文件。
_includes/ — 可复用片段（头部、脚注、社交按钮、评论模版等）
- 小片段模块化：例如 header.html, footer.html, toc.html，修改局部组件优先在此改。
_sass/ — Sass / CSS 源码（主题样式）
- 如果要覆写主题样式或自定义颜色/变量，在此添加或修改 SCSS 文件，最后会被构建成 CSS。
_plugins/ — Jekyll 插件（定制化功能）
- 如果你需要自定义生成逻辑（例如特殊分类、数据处理），可以放 ruby 插件或使用主题自带插件。
_data/ — YAML/JSON/CSV 数据（供 Liquid 模板使用）
- 常用于定义菜单项、作者信息、外部链接列表等结构化数据，模板中用 site.data.xxx 读取。

1.4. 资源与静态文件

assets/ — 图片、js、css、favicon 等静态资源
- 图片通常放 assets/img/；如果要引用站点图标、社交图片、Og:image，放在这里并在 _config.yml 或模板中引用。
docs/ — 主题文档 / 示例（可作为站点内容或附加文档）
_javascript/ / javascript/ — 前端脚本（站点交互、搜索脚本等）

1.5. 配置/工具/CI

.github/ — Actions、Issue templates 等 CI / GitHub 配置
- 如果仓库有 GitHub Actions，会在这里看到构建/部署工作流（例如自动构建并推送 GitHub Pages）。
.devcontainer/, .vscode/ — 开发容器/编辑器配置（便于在 Codespaces/DevContainer 中一键启动开发环境）

1.6. 其他常见文件（和它们的修改建议）

index.html — 首页入口（通常由 layout 渲染）；若只是改首页内容通常修改首页 front-matter 或 home 布局。
jekyll-theme-chirpy.gemspec — 主题 gem 的定义（保留，涉及主题发布时用）。
Lint / config 文件：.markdownlint.json, .stylelintrc.json, eslint.config.js — 控制代码/markdown 风格。

1.7. 示例：把目录展开成更具体树（常见文件）

_posts/
  2025-12-01-windows-dev-env.md
  2025-11-28-nvidia-driver.md
_tabs/
  about.md
  categories.md
  tags.md
  archives.md
_includes/
  header.html
  footer.html
  social.html
_layouts/
  default.html
  home.html
  post.html
assets/
  img/
    avatar.png
    favicon.ico
  css/
  js/
_sass/
  _variables.scss
  chirpy.scss
_github/
  workflows/
    pages.yml

（上面文件名为示例；真实文件可在仓库中查看）GitHub+1

2. 标准的文章模板

Chirpy Jekyll Theme 标准可直接使用的 _posts 文章模板，包含：

完整 YAML front-matter
SEO 元数据
封面图 (OG image)
标签 / 分类
目录（TOC）
自动 excerpt 摘要写法
代码块、图片、脚注示例
完整可运行

你只需要复制 → 保存为 _posts/2025-01-01-my-article.md 即可被自动识别为文章。

✅ Chirpy 文章模板 — 标准完整版

        
      
---
title: "文章标题（Title）"
date: 2025-01-01 10:00:00 +0800
categories: [Category1, SubCategory]   # 分类（支持多级）
tags: [tag1, tag2, tag3]               # 标签（不限数量）
description: "本篇文章的简短摘要，用于 SEO 与文章预览。"
author: 你的名字（可选）
pin: false                              # 是否置顶（true / false）

# 封面图（社交媒体预览图最佳尺寸 1200x630）
image:
  path: /assets/img/sample-cover.jpg     # 站点内路径
  alt: "封面图描述"
  lqip: /assets/img/lqip/sample.jpg      # （可选）低质量占位图

# 是否启用目录（左侧浮动目录）
toc: true
toc_label: "目录"
toc_icon: "list-ul"

# 文章版权 / 转载声明（可选）
copyright:
  license: CC BY-NC-SA 4.0
  holder: "你的名字"
---

<!--
如果需要摘要，放在这里，两段之间空一行。
这一段内容会在首页或搜索中作为 excerpt 显示。
-->

本文主要介绍……

<!-- more -->

---

# 一级标题示例

这里写正文内容……

## 二级标题示例

你可以正常写 Markdown 内容：

- 列表
- 加粗 **bold**
- 斜体 *italic*
- 链接 [Link](https://example.com)

---

# 插入代码块示例

\`\`\`python
def hello():
    print("Hello Chirpy!")
\`\`\`

---

# 插入图片示例

![示例图片 alt](/assets/img/demo.png)

你也可以设置宽度：

![Alt text](/assets/img/demo.png){: width="60%" }

---

# 引用示例

> 这是一段引用文本。

---

# 表格示例

| 名称 | 数值 |
|------|------|
| A    | 123  |
| B    | 456  |

---

# 脚注示例

这是一个脚注[^1]。

[^1]: 这里是脚注内容。

---

# MathJax（数学公式）示例

行内公式：\( a^2 + b^2 = c^2 \)

块级公式：

$$
\int_0^{1} x^2 \, dx = \frac{1}{3}
$$

---

# 最后一段

如果你愿意，我还能为你：

- 自动生成 tag / category 封面
- 提供文章批量创建脚本
- 自动生成图床链接或本地 assets 目录
- 给出封面图模板（1200x630）

需要哪个？我可以继续帮你生成。

本文由作者按照 CC BY 4.0 进行授权