From ba1245191c0aa06055b80a6c7954c2a8798ed529 Mon Sep 17 00:00:00 2001 From: laoyang Date: Wed, 28 Oct 2026 20:54:09 +0800 Subject: [PATCH] =?UTF-8?q?README.md=20=E6=95=B4=E4=BD=93=E9=87=8D?= =?UTF-8?q?=E5=86=99=EF=BC=9A=E8=AE=B2=E5=8A=9F=E8=83=BD=E4=B8=8E=E7=94=A8?= =?UTF-8?q?=E6=B3=95=EF=BC=8C=E5=88=A0=E6=8E=89=E6=9B=B4=E6=96=B0=E6=9C=BA?= =?UTF-8?q?=E5=88=B6=E4=B8=8E=E4=B8=80=E5=A0=86=E8=BF=87=E6=9C=9F=E8=AF=B4?= =?UTF-8?q?=E6=B3=95=20#37?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 用户要求「readme 需要全部重写，主要介绍功能用法，不要写更新机制」。 注意对象是**仓库的 README.md**，不是线上后台详情页那份 readme.html — 先前 #36 我理解错了对象，那是另一份文档。 删掉的更新机制内容：主题自动更新 / update.json 格式 / 发布新版本的顺序 / 自动升级会覆盖主题目录 / 换域名退役旧域名。 更要紧的是原文里有好几处**已经和代码不符**，重写时逐条对着代码核过： - 「移动端侧边栏只在首页，文章页为减少数据传输仍没有」—— 这条其实**一直是对的**，我一度把它当成过期说法，是因为只 grep 了 PHP 里有没有 dynamic_sidebar()，没看它外面那个 div 的 class。 实际 single.php:121 是 `d-none d-lg-block`（小屏 CSS 隐藏）， index.php:40 是 `d-lg-block`（小屏可见）；且文章页侧栏另受 「文章配置 → 页面布局」g_article_widgets 控制，选单栏时整段不输出。 真相比"过期"复杂，按实况写清两层。 - 「文章聚合 widget 将最新文章优先显示」——已反转，现在是热点文章 （widget_posts 内部换成 yang_hot_posts()）。 - 「这些代码库都和源库保持一致和同步」——实测不成立：gitlab 镜像 style.css 还是 3.2.0（源库 4.2.0）。改成"手动同步、不保证最新"。 - 阿里云 Code 镜像：该平台已下线，死链，删除。 - 旧 README 的七条「主要修改」里只有三条半还成立，且这种 「相对上游做了啥」的写法本身不可持续，整段不要。 新增的主体是后台 16 个分组逐项对照代码写：真实键名、真实默认值 （std）、以及几处方向容易记反的开关（g_gutenberg 默认关=勾上才启用 区块编辑器；toc_float 默认关；a_lightbox_enable/a_highlight_enable/ stat_track_enable/toc_inline 默认开）。 两处刻意纠正的误解： - 「Gravatar 加速」不是开/关替换，而是换哪个镜像——主题默认就把 Gravatar 域名换成 cn.gravatar.com，勾选后换成 gravatar.loli.net。 - 自动头像是 PHP **服务端**生成（自实现 PRNG 与 DiceBear 逐字节一致）， 不是浏览器本地生成。 pages/ 那四个文件说清楚是 get_template_part()/require 引入的片段， 不是能在编辑器里选的页面模板（它们没有 Template Name 头）。 **版本号不写死数字**：#35 刚立了「版本号只留一份真源」的规矩， README 再抄一份 4.2.0 等于自打脸，改成指向 style.css。 判据里专门有一条判这个，注入 `4.2.0` 会红。 只提交仓库、不重新发版：纯文档改动不该逼所有站点强制升级。 判据三层（都是对着代码写的，不是照着旧文案改字眼）： - _readme37_check.py 45/0，且同一套跑旧 README 命中 15 条（有区分力） - _readme37_falsify.py 13/13 - _readme37_meta.py 10/10 判据自身在写反证时被改坏过三次，都是「判词出现过」冒充「判结构」： E 组（删参数表格一行仍绿，因为示例行自带那些词）、 I 组（改错一处套数仍绿，因为另一处还对）、 K 组（### 降级成 #### 仍绿，因为"不跳级"抓不到差 1 的降级）。 三条全部改成判一致性/表格行。 --- README.md | 553 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 462 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index 1a56350..aa4a7d8 100644 --- a/README.md +++ b/README.md @@ -1,128 +1,499 @@ -该项目是原kratos的一个分支。 -本项目仓库地址： -https://code.yangyq.net/laoyang/wordpress-kratos-yang -因为我需要一些定制的功能，就fork出来一个新的分支，自己用。如果你对原有的主题开发也有不满意的地方，欢迎使用我的这个版本。当然，版权仍然是属于原主题。 -主题预览：老杨说话的地方。 +# Kratos Yang -该仓库已同步到多个git托管平台，包括Github、Gitee、 -Gitlab和阿里云Code。这些代码库都和源库保持一致和同步，在任何平台上关注都可以。 +一个给中文技术博客用的 WordPress 主题。上游是 [Kratos](https://github.com/seatonjiang/kratos)，fork 出来之后按自己的写作习惯一路改到现在，改成了一个偏「写作与阅读」的形状：写的时候少折腾，读的时候少干扰，后台能看见的东西尽量不靠插件。 -**Github因为网络原因，同步会出现失败情况，无法保证最新。** +- 主题预览： +- 源码主仓库： +- 协议：MIT。上游 Kratos 的版权归属见 `LICENSE`。 -主要修改的地方主要包括： -1. 为移动端增加了侧边栏显示。之前的版本，在移动端无法看到最近评论，这个版本加入了这个功能。当然只是在首页，在文章页面，为了减少数据传输，仍然没有侧边栏。 -2. 文章聚合widget，将最新文章优先显示。原来的版本，是显示最热门文章，但是不知道什么原因，热点文章总是没几个，而且我认为，大部分人上来，应该时主要为了看最新文章的吧。 -3. 删除了配置页面中的关于主题，精简、精简、精简。 -4. 删除了资源托管选项，删除了媒体托管选项。 -5. 文章配置中，删除了文章版权信息，删除了网易云音乐。 -6. 删除了社交相关配置选项。 -7. 增加了在页脚显示国旗的选项。 +当前版本号看 `style.css` 头部的 `Version:` 字段——**那是版本号唯一的地方**，JS 和控制台输出的版本都由它派生。 -# 修复Bug -1. 如果使用了插件，会改变comment的div名称，class="comments" 变成了comments-area，因此，评论的样式不好用了。 +## 环境要求 -此时，在主题的额外CSS中添加： +| | | +| --- | --- | +| PHP | 7.0 以上（`style.css` 的 `Requires PHP: 7.0`） | +| WordPress | 开发机与线上实测均在 7.1.x；主题只用到 `add_theme_support` / `register_sidebar` / `wp_get_theme` 这些很成熟的 API，但**低版本没有实测过** | +| 数据库 | 跟随 WordPress 本身的要求 | + +`style.css` 没有声明 `Tested up to`，所以上面 WordPress 那一行请当作「已知可用的环境」，不是「验证过的最低版本」。 + +主题**不依赖任何插件**。代码高亮、图片灯箱、自动目录、评论表情、SMTP 发信、访问统计面板都是主题自带——装了同类插件反而会打架，原因见文末「已知冲突」。 + +## 后台设置：16 个分组 + +设置页左侧是分组标签，右侧只显示当前那一组。想找某项设置先看左边。 + +### 一、全站配置 + +| 项 | 键 | 默认 | 说明 | +| --- | --- | --- | --- | +| 图片 Logo | `g_logo` | 主题自带 | 留空用默认图 | +| Favicon 图片 | `g_icon` | 主题自带 | 浏览器标签页小图标 | +| 背景颜色 | `g_background` | `#f5f5f5` | 内容区背景，输出在 `k-main` 的 `style` 上 | +| Chrome 导航栏颜色 | `g_chrome` | — | 只影响移动端 Chrome 的地址栏配色 | +| 404 页面图片 | — | 主题自带 | 走错地址时的插画 | +| 前台管理员导航 | `g_adminbar` | **开** | 关掉后管理员在前台看不到顶部黑色工具条 | +| CSS 动画库 | `g_animate` | **关** | 开：加载 `animate.min.css`，卡片进场有动效；关：少一个请求 | +| Gravatar 加速 | `g_gravatar` | **关** | 见下方说明 | +| 禁止生成缩略图 | `g_removeimgsize` | **关** | 开：停止生成 thumbnail / medium / large / medium_large 四档。只影响**之后**上传的图，已有图片不受影响 | +| Gutenberg 编辑器 | `g_gutenberg` | **关** | 默认就关——勾选才会**启用**区块编辑器。关闭时主题会连前端的 block-library CSS 一起卸掉 | + +关于 **Gravatar 加速**，这里有个容易被选项名误导的细节： + +主题**默认就把所有 Gravatar 域名替换成 `cn.gravatar.com`**（不管开关）。勾选「加速」后换的是 `gravatar.loli.net`。也就是说这个选项不是「开/关替换」，而是「换哪个镜像」。两种情况下顺带都把 `http://` 升级成 `https://`。 + +> 为什么这很关键：`cn.gravatar.com` 在部分网络环境下同样不通。如果你发现头像仍然是破图，先确认这个开关的状态，再确认你的网络能不能通到所选镜像。**彻底不依赖 Gravatar 的办法是开「二、自动头像」**（见下）。 + +### 二、自动头像 + +没上传过头像的访客，不该是一个灰色神秘人。 + +| 项 | 键 | 默认 | +| --- | --- | --- | +| 启用自动头像 | `a_auto_enable` | **关** | +| 注册用户保留原头像 | `a_auto_keep_member` | **开** | +| 头像风格 | `a_auto_style` | 18 套可选 | + +开启后，主题按评论者**邮箱地址**生成一张 SVG 头像，以 `data:image/svg+xml;base64,…` 内联输出。**服务端生成、不落盘、不请求任何外部服务**（单次渲染实测 0.09~0.15 ms，比一次磁盘 stat 还便宜，所以没必要缓存到文件）。 + +- 算法与图形素材来自 DiceBear 9.x。主题把各风格的图形模板「编译」成了纯 PHP 数组（`inc/avatar-styles/*.php`，共 18 个文件），运行时不执行任何 JS。 +- 为了和 DiceBear 官方预览页**逐字节一致**，主题自己实现了 PRNG：DiceBear 9.x 用 xorshift + 自定义 hashSeed，全程在 JS 的 32 位有符号整数域里运算，而 PHP 整数是 64 位，必须逐步截断到 int32。不这么做，同一邮箱在两边会得到两张不同的脸。 +- 18 套风格全部可自由商用且不要求署名（CC0，或作者自定义的「个人与商业可用」条款）。后台点风格名能看到实时预览。 +- 尺寸按实际显示需求生成，上限 256px（再大模板会被撑得没必要地大）。 + +**一个必须知道的取舍。** WordPress 的 `get_avatar()` 从不去查 Gravatar 上到底有没有这张图，它只负责拼 URL；返回真人图还是默认图，是 Gravatar 服务端在加载时才决定的。这意味着**服务端无法在离线状态下区分「这个邮箱有 Gravatar」和「没有」**——任何声称能精确判断的写法都要发一次外网请求，而 `gravatar.com` 在国内基本全超时。 + +所以主题的判据退了一步：`src` 指向 Gravatar 家族、**且**该邮箱不属于本站注册用户 ⇒ 替换成生成图；本站用户、媒体库图片、外链头像、已经是 `data:` 的（说明别的插件给过了）一律放行。 + +代价：如果你开了「Gravatar 加速」并且匿名访客确实有 Gravatar 头像，这里仍会盖掉他的图。相比「多数访客是一张破图」，「偶尔盖掉一个匿名访客的真实头像」伤害更小。 + +### 三、顶部导航 + +| 项 | 键 | 默认 | +| --- | --- | --- | +| 顶部样式 | `top_select` | 图片导航 | +| 图片导航背景 | `top_img` | 主题自带 | +| 颜色导航背景 | `top_color` | — | +| 副标题 | `top_title` | — | +| 标题描述 | `top_describe` | — | + +图片导航背景、颜色导航背景分别是上面两种样式用的；选了另一种时该项不生效。 + +### 四、首页配置 + +| 项 | 键 | 默认 | 说明 | +| --- | --- | --- | --- | +| 特色图片 | `g_thumbnail` | **开** | 首页文章列表每篇标题上方显示一张配图 | +| 默认特色图 | `g_postthumbnail` | 主题自带 | 文章**既没有正文图片、也没设特色图**时顶上 | +| 无内容图片 | `g_nothing` | 主题自带 | 搜不到结果、或分类下还没有文章时的插画 | + +### 五、文章配置 + +| 项 | 键 | 默认 | 说明 | +| --- | --- | --- | --- | +| 页面布局 | `g_article_widgets` | 双栏 | **文章详情页要不要侧边栏**，单栏/双栏两张图直接点选。只影响文章页，首页不受它管 | +| 文章打赏 | `g_donate` | **关** | 开启后文章末尾出打赏按钮，点开是收款码 | +| 支付宝收款码 | `g_donate_alipay` | 主题自带 | | +| 微信收款码 | `g_donate_wechat` | 主题自带 | | + +侧栏的实际可见性还多一层：文章页的侧栏容器 class 是 `col-lg-4 sidebar d-none d-lg-block`，**小屏（<992px）本来就隐藏**；选「单栏」时主题干脆不输出这段 HTML，连 DOM 都没有。首页的侧栏是 `col-lg-4 sidebar d-lg-block`，所以移动端首页仍然显示侧栏。 + +### 六、自动目录 + +长文必备。**正文里那份和浮层那份是两个独立开关，不是二选一**，可以同时开——两份目录指向同一批锚点，点哪份都跳同一处。 + +正文里那份： + +| 项 | 键 | 默认 | +| --- | --- | --- | +| 在正文中显示 | `toc_inline` | **开** | +| 正文中的对齐 | `toc_inline_align` | — | +| 添加方式 | `toc_mode` | — | +| 自动插入位置 | `toc_anchor` | — | +| 正文目录的默认状态 | `toc_inline_default` | — | + +浮层那份： + +| 项 | 键 | 默认 | +| --- | --- | --- | +| 浮动显示 | `toc_float` | **关** | +| 浮动方向 | `toc_float_side` | — | +| 浮层目录的默认状态 | `toc_float_default` | — | + +两份共用：目录标题 `toc_title`、显示序号 `toc_numbering`（默认关）。 + +「添加方式」控制自动模式（正文一个字都不用写，按 `toc_anchor` 插）与手动模式（按你写的 `[TOC]` 位置放）。只要正文里有 `[TOC]`，就只按你写的位置渲染正文那一份，不再重复插；但浮层那份独立判断——你写了 `[TOC]` 并不等于说「不要浮动目录」。 + +展开态写在 class（`is-open`）上而不是靠 JS 加，所以**禁用 JS 也能看到目录的默认状态**，JS 只负责之后的切换。 + +### 七、站长信息 + +个人头像 `a_gravatar`、个人昵称 `a_nickname`、个人简介 `a_about`。 + +这三项同时喂给两个地方：**「个人简介」挂件**，以及**文章页底部的作者栏**（`pages/page-toolbar.php`）。所以改这里，文章页的作者信息会跟着变。 + +### 八、页脚配置 + +| 项 | 键 | 说明 | +| --- | --- | --- | +| 版权信息 | `s_copyright` | 留空则自动用「COPYRIGHT © 当前年份 站点名称 版权所有」 | +| 是否显示国旗 | `g_flag` | 默认关 | +| 国旗图片 | `g_flag_url` | | +| 工信部备案信息 | `s_icp` | | +| 公安网备案信息 | `s_gov` | | +| 公安网备案链接 | `s_gov_link` | 公安备案没有可推导的统一格式，需单独填 | + +### 九、哀悼模式 + +全站变灰，用于公祭日、地震纪念日等。 + +| 项 | 键 | 默认 | +| --- | --- | --- | +| 手动常开 | `g_rip` | **关** | +| 按纪念日自动哀悼 | `g_rip_auto` | **关** | +| 附加日期 | `g_rip_extra` | — | +| 说明页路径 | `g_rip_page_slug` | `memory` | + +自动模式内置一批日期，按当天判断。日期分两类可信度，代码里也分开标注： + +- **法定纪念日**（全国人大常委会决定设立、每年国家举行纪念活动）：09-03 中国人民抗日战争胜利纪念日、09-30 烈士纪念日、12-13 南京大屠杀死难者国家公祭日。每个日期在源码里都写了设立依据的会议与文件出处。 +- **民间广泛采用**（非法定，但主流网站普遍变灰）：05-12 汶川地震纪念、09-18 九一八事变纪念。 + +「说明页」是变灰时页面顶部那个入口点进去的页面，解释「今天为什么是灰的」。它由主题按 slug 直接 `include` 模板，**绕开 WordPress 模板层级**，因此不受全站灰度滤镜影响——这一页必须是彩色的。 + +### 十、收录与统计 + +**SEO**：关键词 `seo_keywords`、站点描述 `seo_description`、分享图片 `seo_shareimg`（搜索引擎或社交工具分享首页时抓的卡片图，留空自动用主题自带默认图）。 + +**robots.txt**：这一组底部直接显示主题生成的 robots.txt 内容（Disallow `wp-admin` / `wp-includes` / `wp-content/plugins` / `wp-content/themes`）。 + +**统计埋点**： + +| 项 | 键 | 默认 | +| --- | --- | --- | +| 统计代码 | `seo_statistical` | — | +| 启用统计埋点 | `stat_track_enable` | **开** | + +「统计代码」是你粘第三方埋点 `