一套用于学习、验证和复习 WordPress Classic Theme（经典主题）开发机制的实验项目。
项目包含 20 个彼此独立、已经实际测试通过的 WordPress 最小主题，并为每个主题配套中文 Markdown 文档。通过固定测试数据、可运行源码、预期结果和常见问题，把 Template Hierarchy、WordPress 数据模型以及 WP_Query 的主要查询能力串成一套可重复验证的学习体系。
从 v1.1.0 开始，项目新增一个轻量静态 Markdown 阅读器，可以直接把 docs/ 中的知识文档组织成左侧章节导航 + 右侧正文的知识库页面。
当前版本：v1.1.0
项目定位：个人学习 / 技术研究 / WordPress 主题开发实验，不是生产主题。
v1.0.0 已完成 20 个 WordPress 实验主题与全部知识文档；v1.1.0 不修改已经验证通过的核心 PHP 实验代码，主要增加文档阅读层：
- 新增根目录
index.html，作为静态知识库入口。 - 使用
marked.js在浏览器中直接渲染docs/*.md。 - 使用
highlight.js对 PHP、HTML、JavaScript、JSON 等代码块进行高亮。 - 代码块支持一键复制。
- Markdown 表格支持响应式横向滚动。
- 左侧章节按照知识地图分组，可折叠切换。
- 使用 Hash 路由保存当前章节，例如
#query-meta。 - 支持电脑端与手机端阅读。
- 第三方前端库全部保存在本地，不依赖 CDN。
- 不引入数据库、Node 构建流程或前端框架。
- 当前版本不加入搜索功能，20 章规模下优先保持导航和代码简单。
知识库继续直接读取原始 Markdown，因此不存在“Markdown 一份、HTML 内容再维护一份”的重复维护问题。
wordpress-theme-development-lab/
├─ README.md
├─ index.html # v1.1.0 静态知识库入口
├─ .nojekyll # GitHub Pages 静态发布辅助文件
│
├─ assets/ # 知识库前端资源
│ ├─ css/
│ │ ├─ knowledge-viewer.css
│ │ └─ vendor/
│ │ └─ highlight-github.min.css
│ └─ js/
│ ├─ knowledge-viewer.js
│ └─ vendor/
│ ├─ marked.js
│ ├─ highlight.min.js
│ └─ MARKED-LICENSE.md
│
├─ data/
│ └─ docs.json # Markdown 文档导航配置
│
├─ docs/ # 20 章知识文档与项目文档
│ ├─ 00-test-data.md
│ ├─ 01-project-roadmap.md
│ ├─ 01-template-hierarchy.md
│ ├─ 02-default-query.md
│ ├─ ...
│ ├─ 20-query-pagination.md
│ └─ 21-knowledge-map.md
│
├─ test-assets/ # MIME / Attachment 测试资源
│ ├─ wp-lab-image.jpg
│ ├─ wp-lab-note.txt
│ └─ wp-lab-archive.zip
│
├─ adv-01-tpl/
├─ adv-02-default-query/
├─ adv-03-data/
├─ ...
├─ adv-19-query-order/
└─ adv-20-query-fenye/
20 个 adv-* 目录是 20 个独立 WordPress Theme，不是一个主题中的 20 个子模块。
知识库前端与 WordPress 实验主题彼此独立：
WordPress 实验层
→ adv-01 ~ adv-20
知识内容层
→ docs/*.md
阅读展示层
→ index.html + assets + data/docs.json
这套实验最终可以归纳为一条主线：
浏览器 URL / Request
↓
WordPress Main Query
↓
识别当前页面状态
↓
Template Hierarchy
↓
模板 / Loop 输出
页面需要额外数据时：
WordPress 数据模型
↓
WordPress API
↓
Custom WP_Query
↓
查询条件
↓
Order / Orderby
↓
Pagination
↓
Loop / 页面输出
完整知识地图：
需要特别注意：
课程学习顺序 ≠ WordPress 实际运行顺序
例如课程先学习 adv-01 Template Hierarchy，再学习 adv-02 Default Query；但 WordPress 实际处理请求时，是先建立 Main Query，再根据页面状态进入 Template Hierarchy。
| # | 主题目录 | 核心知识 | 配套文档 |
|---|---|---|---|
| 01 | adv-01-tpl |
Template Hierarchy / 模板层级 | 01-template-hierarchy.md |
| 02 | adv-02-default-query |
Default Query / Main Query | 02-default-query.md |
| 03 | adv-03-data |
Post / Meta / Term / Attachment | 03-data.md |
| 04 | adv-04-funcs |
WordPress 常用数据函数 | 04-functions.md |
| 05 | adv-05-query-1 |
WP_Query 基础 | 05-wp-query-basics.md |
| 06 | adv-06-query-author |
Author Parameters | 06-query-author.md |
| 07 | adv-07-query-cat |
Category Parameters | 07-query-category.md |
| 08 | adv-08-query-tag |
Tag Parameters | 08-query-tag.md |
| 09 | adv-09-query-tax |
Tax Query | 09-query-tax.md |
| 10 | adv-10-query-search |
Search Parameters | 10-query-search.md |
| 11 | adv-11-query-post |
Post / Page Parameters | 11-query-post-page.md |
| 12 | adv-12-query-pwd |
Password Parameters | 12-query-password.md |
| 13 | adv-13-query-type |
Post Type | 13-query-post-type.md |
| 14 | adv-14-query-status |
Post Status | 14-query-post-status.md |
| 15 | adv-15-query-cmt |
Comment Count | 15-query-comment-count.md |
| 16 | adv-16-query-date |
Date Query | 16-query-date.md |
| 17 | adv-17-query-meta |
Meta Query | 17-query-meta.md |
| 18 | adv-18-query-mime |
MIME / Attachment | 18-query-mime.md |
| 19 | adv-19-query-order |
Order / Orderby | 19-query-order.md |
| 20 | adv-20-query-fenye |
Pagination / Offset / 原生分页函数 | 20-query-pagination.md |
项目路线与完成状态：
data/docs.json 不按照简单的 01～20 平铺，而是按照知识关系分组：
项目总览
├─ 20 章知识地图
├─ 统一测试数据
└─ 项目路线
01 请求与模板
├─ 01 Template Hierarchy
└─ 02 Default Query
02 数据模型与基础
├─ 03 Data
├─ 04 Functions
└─ 05 WP_Query Basics
03 查询条件
├─ 06 Author
├─ 07 Category
├─ 08 Tag
├─ 09 Tax Query
├─ 10 Search
├─ 11 Post / Page
├─ 12 Password
├─ 13 Post Type
├─ 14 Post Status
├─ 15 Comment Count
├─ 16 Date Query
├─ 17 Meta Query
└─ 18 MIME / Attachment
04 结果控制
├─ 19 Order / Orderby
└─ 20 Pagination / Offset
默认打开的是 20 章 WordPress 知识地图，先建立整体认识，再进入具体章节。
知识库没有把 Markdown 转成一批固定 HTML 文件，而是运行时读取：
data/docs.json
↓
找到 docs/*.md
↓
fetch()
↓
marked.js
↓
HTML
↓
highlight.js
↓
代码高亮
以后修改知识内容，只需要编辑对应 .md 文件。
新增文档时，一般只需要：
- 把新的 Markdown 放入
docs/； - 在
data/docs.json增加一条配置； - 刷新知识库页面。
因为阅读器通过 fetch() 读取 JSON 和 Markdown，不建议直接双击 index.html 使用 file:// 打开。
在仓库根目录启动一个简单 HTTP 服务即可。例如电脑已经安装 Python 时：
python -m http.server 8000然后浏览器访问：
http://localhost:8000/
不需要 PHP、MySQL、Node.js 或数据库。
仓库根目录的 index.html 可以直接作为静态站点入口。将仓库通过 GitHub Pages 发布后，就可以在线浏览同一套 docs/*.md 知识内容。
v1.1.0 保持阅读器最小化，不加入搜索、数据库、后台编辑器和前端框架。
如果把全部实验写进一个大主题，很容易出现：
一个知识点的代码
↓
被其他 Hook / Query / Template / Meta Box 干扰
↓
无法确定当前结果究竟由什么造成
本项目采用：
一个知识点
=
一个最小 WordPress 主题
=
一个相对独立的实验环境
例如忘记某个知识点时，可以直接切换对应主题：
Template Hierarchy → adv-01-tpl
Tax Query → adv-09-query-tax
Post Status → adv-14-query-status
Meta Query → adv-17-query-meta
Pagination → adv-20-query-fenye
这种结构更适合学习、调试和以后快速复习。
把：
adv-01-tpl
...
adv-20-query-fenye
复制到：
/wp-content/themes/
然后在 WordPress 后台按章节切换实验主题。
建议使用便于观察 URL 的固定链接结构，例如“文章名”。
每个实验主题的 functions.php 都会注册测试用：
product
product_cat
post_copy
主题切换后通过 after_switch_theme 刷新 rewrite rules，而不是在每次 init 请求中执行 flush_rewrite_rules()。
完整步骤：
统一数据包括：
3 个测试作者
4 个 Category
3 个 Tag
3 个 post_copy Term
2 个 product_cat Term
3 个 Product
5 个 Page
10 篇已发布文章
特殊 Post Status 测试文章
评论测试数据
Post Meta / Term Meta
JPG / TXT / ZIP Attachment
测试数据原则：
固定 Name
固定 Slug
动态取得真实数据库 ID
而不是把某个数据库里的 Post ID、Category ID、Term ID、Attachment ID 直接硬编码成项目依赖。
01 Template Hierarchy
02 Default Query
建立：
Request
→ Main Query
→ 页面状态
→ Template Hierarchy
→ Loop
03 Data
04 Functions
重点理解：
Post
Post Meta
Term
Term Meta
Attachment
05 WP_Query Basics
建立：
Main Query
vs
Custom WP_Query
以及：
new WP_Query();
have_posts();
the_post();
wp_reset_postdata();06 Author
07 Category
08 Tag
09 Tax Query
10 Search
11 Post / Page
12 Password
13 Post Type
14 Post Status
15 Comment Count
16 Date Query
17 Meta Query
18 MIME / Attachment
不要优先死记所有参数，可以先判断：
我现在到底想按照哪个维度筛选 Post？
19 Order / Orderby
20 Pagination / Offset
最终形成：
筛选
→ 哪些 Post 进入结果集
排序
→ 这些结果按照什么顺序排列
分页
→ 当前只读取结果集中的哪一部分
越具体的模板
→ 优先级越高
→ 找不到再向通用模板回退
Main Query
→ WordPress 根据 Request 自动建立
Custom WP_Query
→ 模板主动创建的附加查询
自定义 Loop 结束后通常需要：
wp_reset_postdata();可复用的分类关系
→ Taxonomy / Term
→ tax_query
属于某篇 Post 的额外属性
→ Post Meta
→ meta_query
例如：
Slug: page-grandchild
Path:
page-parent/page-child/page-grandchild
使用 get_page_by_path() 定位层级 Page 时要注意完整路径。
测试值：
2
10
100
字符串排序可能得到：
10
100
2
数字排序可以使用：
meta_value_num
或在 Meta Query 中明确数字类型。
正常分页：
posts_per_page + paged
固定 offset 会改变正常分页起点，需要单独计算分页逻辑。
Main Query
→ the_posts_pagination()
Custom WP_Query
→ paginate_links()
而 wp_link_pages() 解决的是单篇正文分页，不是文章列表分页。
每个实验尽量按照同一种方式记录：
- 知识点名称
- 解决什么问题
- 核心概念
- 基础语法
- 参数说明
- 本课测试数据准备
- 测试源码
- 如何访问 / 运行
- 预期结果
- 常见错误与排查
- 实际开发建议
- 官方参考
因此这个仓库同时承担三种职责：
WordPress 可运行实验源码
+
Markdown 学习手册
+
静态知识库阅读页面
本项目当前专注于：
WordPress Classic Theme
Template Hierarchy
WordPress 数据模型与读取 API
WP_Query
查询条件
查询结果排序与分页
Markdown 知识整理
当前版本不追求覆盖：
完整商业主题工程
Block Theme / Site Editor
大型前端框架
复杂构建工具
完整插件架构
REST API 应用
生产环境安全与性能体系
部分实验为了观察 WordPress 内部数据，会直接输出数组、查询变量或调试信息。这些代码具有教学用途，不应该未经判断直接复制到生产网站。
adv-14-query-status 会研究 Draft、Pending、Future、Private 等非公开状态，因此实验页包含权限限制，应使用具备编辑文章权限的测试账号进行学习。
当前 20 个最小实验已经完成。下一阶段如果继续扩展，优先考虑增加一个完整但仍然保持简单的 Classic Theme：
adv-21-theme-project/
├─ style.css
├─ functions.php
├─ header.php
├─ footer.php
├─ index.php
├─ single.php
├─ archive.php
├─ single-product.php
├─ archive-product.php
├─ taxonomy-product_cat.php
└─ template-parts/
目标从：
单知识点实验
过渡到：
主题结构
模板复用
页面职责
代码组织
v1.1.0 的知识库阅读器已经满足当前 20 章文档的阅读需要，因此暂不增加搜索、数据库或内容后台。
在 v1.0.0 的 20 个已验证实验主题基础上新增静态 Markdown 知识库：
✓ 新增 index.html 知识库入口
✓ 新增 assets/ 前端资源目录
✓ 新增 data/docs.json 文档导航配置
✓ docs/ 直接作为唯一知识内容源
✓ marked.js Markdown 渲染
✓ highlight.js 代码高亮
✓ 代码一键复制
✓ 分组折叠导航
✓ Hash 章节路由
✓ Markdown 表格响应式处理
✓ 手机端导航适配
✓ GitHub Pages 静态发布结构
✓ 不引入搜索、数据库和构建工具
首个完整学习版本：
✓ 20 个独立 WordPress Classic Theme 实验
✓ 统一测试数据体系
✓ Template Hierarchy / Main Query 实际验证
✓ WordPress 数据对象与读取 API
✓ WP_Query 主要查询参数实验
✓ Author / Category / Tag / Tax Query
✓ Search / Post / Password / Post Type / Post Status
✓ Comment Count / Date Query / Meta Query / MIME
✓ Order / Orderby
✓ Pagination / Offset / WordPress 原生分页函数
✓ 20 章配套中文知识文档
✓ 20 章总知识地图
知识库阅读器本地使用：
marked.js：Markdown 解析highlight.js：代码语法高亮
第三方库遵循其各自许可证；项目保留了相关源码头部许可证信息及 MARKED-LICENSE.md。
这是一个以学习和研究为目的的个人实验仓库。
源码和文档优先追求：
小
清晰
可运行
可验证
可复习
可长期维护