Theme Development

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

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.png

The 34 bundled themes (yecha, teadoc, xinglan, wenshu, …) are working examples; browse them in the theme gallery.

theme.json

FieldMeaning
name / version / descriptionShown in admin and /theme
requires_coreRequired core version (e.g. 1.2.5)
author / licenseAuthor and licence
homelanding enables the portal home layout
settingsAdmin 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

VariableMeaning
$title / $htmlLangPage title, <html lang>
$main / $sideRendered body and sidebar HTML
$posts / $post / $tocList rows, current content, TOC entries (page-type dependent)
HelperUse
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 at 390px.
  • Reuse pre/code styles; pre[data-lang]::before shows the language badge (all content pages since 1.2.5).

Debug & fallback

  1. php -l every file; flush page/block caches and rebuild the baked home page after switching (cache).
  2. Missing views fall back to the default yecha theme and are logged to var/log/php-error.log — never silent.
  3. Escape every $_GET / DB value; never rely on JavaScript to render main content.
  4. Check both Chinese and /en/ pages; no hard-coded Chinese in English views.

Release checklist

  • [ ] theme.json complete, requires_core matches the tested version
  • [ ] php -l passes for every PHP file
  • [ ] layout.php, landing.php (if declared), 404.php present
  • [ ] 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