一套主题 = 一个目录 + 一份 theme.json + 若干 PHP 视图。内核不编译模板、不引入模板引擎,视图就是普通 PHP 文件,服务端直接输出 HTML。
本页导航
目录结构
themes/<id>/
theme.json # 元数据 + 后台可调设置(必需)
style.css # 主题样式
views/
layout.php # 整页外壳(必需)
landing.php # 门户首页(home.landing=1 时启用)
landing-en.php # 英文首页(/en/ 优先)
landing-cms.php # 门户首页共用取数与版式(可选)
404.php
partials/ # list / post / page / search / archives / sidebar / toc-side …
logo.png / favicon.png内置 34 套主题(yecha、teadoc、xinglan、wenshu…)都是可直接照抄的范例;主题广场可逐套查看。
theme.json
| 字段 | 说明 |
|---|---|
name / version / description | 后台与/theme展示的名称、版本、简介 |
requires_core | 依赖内核版本(如 1.2.5) |
author / license | 作者与许可 |
home | 设为 landing 时首页走门户版式 |
settings | 后台可调项数组:key / type(select、color、number、checkbox) / label / def / opts |
后台「主题设置」只收集这里声明过的键,写入 ye_options.theme.options(JSON);模板里用 theme_opt('key', '默认值') 读。
最小可用主题
themes/hello/theme.json:
{
"name": "Hello",
"version": "0.1.0",
"requires_core": "1.2.5",
"description": "最小示例主题",
"settings": [
{ "key": "accent", "type": "color", "label": "主色", "def": "#b3541e" }
]
}themes/hello/views/layout.php:
<!DOCTYPE html>
<html lang="<?= e($htmlLang ?? 'zh-CN') ?>">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title><?= e($title) ?></title>
<link rel="stylesheet" href="<?= e(View::asset('style.css')) ?>">
</head>
<body>
<header><?php foreach (Nav::list('top', Lang::short()) as $n): ?>
<a href="<?= e($n['href']) ?>"<?= $n['active'] ? ' class="active"' : '' ?>><?= e($n['label']) ?></a>
<?php endforeach; ?></header>
<main><?= $main ?></main>
<aside><?= $side ?></aside>
</body>
</html>放进 themes/ 后后台「主题」即可见并切换。
视图与变量
| 变量 | 含义 |
|---|---|
$title / $htmlLang | 页面标题、<html lang> |
$main / $side | 正文 HTML、侧栏 HTML(内核已渲染好,直接输出) |
$posts / $post / $toc | 列表数据、当前内容、目录条目(按页面类型提供) |
常用函数:
| 函数 | 用途 | |
|---|---|---|
e() | HTML 转义,所有动态文本必须过一遍 | |
__() | 语言包取值(如 __('nav.docs')) | |
site_label() / site_name() | 站点名(含英文回落) | |
theme_opt() | 读主题设置 | |
| `Nav::list('top'\ | 'foot')` | 导航项(已带语言前缀与 active) |
Poly::termUrl() / Poly::termName() | 多语术语链接与名称 | |
View::asset('style.css') | 带 ?v=<mtime> 的资源 URL,改样式不必手工改版本号 |
正文由 core/Markdown.php 渲染:标题自动生成锚点与右栏目录,显式 {#id} 可自定义锚点,```lang 围栏代码块带语言角标。
首页版式
home.landing=1 时,首页走 views/landing.php(中文)/ views/landing-en.php(英文)。官网默认主题把取数与结构抽到 partials/landing-cms.php:主题/插件数来自目录扫描、安装包数来自 download/pkg/index.json、更新条目来自 /changelog 内容页、版本来自 core/version.php——数字不写死,避免文档与展示脱节。
自己做首页时建议沿用这个约定;纯文章列表首页(home.landing=0)由内核 Front::home() 提供数据,视图只负责排版。
样式与暗色
- 主题色用 CSS 变量,默认主题为茶褐
--accent:#b3541e,另有--line、--soft、--bg、--fg。 - 暗色模式挂在
html.dark上,所有面板/代码块/表格都要写深色分支,文字对比度要够。 - 响应式:
768px以下单列,侧栏落到正文下方;390px窄屏检查导航折叠。 - 代码样式复用
pre/code;pre[data-lang]::before显示语言角标(1.2.5 起所有内容页通用)。
调试与回落
- 逐文件
php -l,切换主题后清页缓存/区块缓存、重建首页静态件(见运维:缓存)。 - 缺模板时内核回落到默认主题
yecha,并在var/log/php-error.log留记录,不静默失败。 - 模板里不要输出未转义的
$_GET/ 数据库字段;不要依赖 JS 渲染主体内容(无 JS 也要能看全)。 - 多语检查:中文页与
/en/页都要跑一遍,别把中文硬编码进英文视图。
发布清单
- [ ]
theme.json字段齐全,requires_core与实测版本一致 - [ ] 所有 PHP 文件
php -l通过 - [ ]
layout.php、landing.php(如声明)、404.php齐全 - [ ] 中文 / 英文 / 暗色 / 窄屏四种组合目检
- [ ] 区块缓存、首页静态件、页缓存清理后复测
- [ ] 打包到云市场前校验 SHA-256,包内不含密钥、缓存、上传目录