A theme is one directory plus theme.json plus plain PHP views. There is no template engine or build step — views output HTML server-side.
On this page
- Structure · theme.json · Minimal theme · Views & variables · Landing layouts · CSS & dark mode · Debug & fallback · Release checklist
Structure
themes/<id>/
theme.json # metadata + admin settings (required)
style.css
views/
layout.php # page shell (required)
landing.php # portal home (when home.landing=1)
landing-en.php # English home (preferred under /en/)
landing-cms.php # shared home data/layout (optional)
404.php
partials/ # list / post / page / search / archives / sidebar / toc-side …
logo.png / favicon.pngThe 34 bundled themes (yecha, teadoc, xinglan, wenshu, …) are working examples; browse them in the theme gallery.
theme.json
| Field | Meaning |
|---|---|
name / version / description | Shown in admin and /theme |
requires_core | Required core version (e.g. 1.2.5) |
author / license | Author and licence |
home | landing enables the portal home layout |
settings | Admin fields: key / type (select, color, number, checkbox) / label / def / opts |
Only declared keys are saved to ye_options.theme.options (JSON); read them with theme_opt('key', 'default').
Minimal theme
themes/hello/theme.json:
{
"name": "Hello",
"version": "0.1.0",
"requires_core": "1.2.5",
"description": "Minimal example theme",
"settings": [
{ "key": "accent", "type": "color", "label": "Accent", "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>Drop it into themes/ and it appears in Themes.
Views & variables
| Variable | Meaning |
|---|---|
$title / $htmlLang | Page title, <html lang> |
$main / $side | Rendered body and sidebar HTML |
$posts / $post / $toc | List rows, current content, TOC entries (page-type dependent) |
| Helper | Use | |
|---|---|---|
e() | Escape all dynamic text | |
__() | Language string, e.g. __('nav.docs') | |
site_label() / site_name() | Site name with English fallback | |
theme_opt() | Theme setting | |
| `Nav::list('top'\ | 'foot')` | Navigation with language prefixes and active state |
Poly::termUrl() / Poly::termName() | Multilingual term URL/name | |
View::asset() | Asset URL with ?v=<mtime> cache busting |
Bodies are rendered by core/Markdown.php: headings get anchors and a right-hand TOC, {#id} sets an explicit anchor, ```lang fences get a language badge.
Landing layouts
With home.landing=1, the home page uses views/landing.php / landing-en.php. The default site theme puts data and structure in partials/landing-cms.php: theme/plugin counts come from directory scans, package count from download/pkg/index.json, updates from the /changelog content page, version from core/version.php — no hard-coded numbers. Keep this convention in your own landing views. With home.landing=0, Front::home() supplies the post list.
CSS & dark mode
- Use CSS variables: the default theme has
--accent:#b3541e,--line,--soft,--bg,--fg. - Dark mode is
html.dark; cover panels, code blocks and tables with sufficient contrast. - Responsive: single column below
768px, sidebar below content; check nav folding at390px. - Reuse
pre/codestyles;pre[data-lang]::beforeshows the language badge (all content pages since 1.2.5).
Debug & fallback
php -levery file; flush page/block caches and rebuild the baked home page after switching (cache).- Missing views fall back to the default
yechatheme and are logged tovar/log/php-error.log— never silent. - Escape every
$_GET/ DB value; never rely on JavaScript to render main content. - Check both Chinese and
/en/pages; no hard-coded Chinese in English views.
Release checklist
- [ ]
theme.jsoncomplete,requires_corematches the tested version - [ ]
php -lpasses for every PHP file - [ ]
layout.php,landing.php(if declared),404.phppresent - [ ] Chinese / English / dark / narrow-screen checked
- [ ] Re-tested after clearing block, page and home-static caches
- [ ] Before market publishing: SHA-256 verified, no secrets, caches or uploads in the package