WiKiss 0.3 页面语法与常用操作详解
以官方 Aide/AideTables 页面源文件为取证基准的 WiKiss 0.3 页面语法全清单：标题/TOC/样式/列表/代码块/链接/图片/表格逐项渲染 HTML 实测，含中文锚点塌缩、缩进列表不支持、表头无 th 等边界结论，以及建页/改名/锁定等页面操作实录。
WiKiss 0.3 页面语法与常用操作详解
WiKiss 0.3 的页面语法到底支持哪些写法、渲染成什么 HTML？本文的语法清单直接取证自官方发布包自带的两个帮助页源文件——pages/Aide.txt（通用语法）与 pages/AideTables.txt（表格语法），与 0.3.tgz 原始包逐字节 diff 一致（未受改动），全部语法元素在 《Ubuntu 22.04 安装 WiKiss 0.3 指南（PHP 8.1 兼容修复实录）》 的 Ubuntu 22.04 + PHP 8.1 实测环境中逐条渲染验证，每条给出真实 HTML 回显；页面操作（建页、改名、锁定、历史找回）同样全部实测。页面生命周期与鉴权机制的完整行为见 《WiKiss 0.3 核心使用与鉴权配置详解》，本文专注「写什么、渲染成什么、怎么管页面」。
一、语法体系与官方帮助页
WiKiss 的官方语法手册不是独立文档，而是站点自带的两张页面：pages/Aide.txt 与 pages/AideTables.txt——它们本身就是普通 Wiki 页面，可以用编辑框打开查看源码、也能直接修改（改坏了从 historique/Aide/ 找回即可）。这种「语法文档即页面」的设计与 《PmWiki 2.3.38 配置参数详解》 中 PmWiki 的 PmWikiZhCN 文档组思路类似，但 WiKiss 把它压缩到了两张页面的体量。
渲染管线分两个阶段，理解它才能解释后文的多数"怪行为"：
- 保存期：编辑保存时，正文中的
<一律替换为<后落盘（HTML 注入防护在存储层完成），.txt文件里存的就是转义后的文本； - 渲染期：读取页面后按固定顺序做正则替换——标题 → 列表 → 代码块 → 表格（插件）→ 链接 → 样式标记 → 特殊字符/转义，最后塞进
template.html的{CONTENT}占位符。
一张速查总表（全部在本文实测验证过）：
| 语法 | 写法示例 | 渲染结果 |
|---|---|---|
| 标题 | ! !! !!!（行首） | <h1> <h2> <h3> |
| 目录 | 单独一行 TOC | <div id="toc"> 标题目录 |
| 粗体/斜体 | '''X''' / ''X'' | <strong> / <em> |
| 粗斜体 | '''''X''''' | <strong><em> |
| 删除线/下划线 | '--X--' / '__X__' | <del> / <u> |
| 分隔线 | ---- | <hr /> |
| 有序/无序列表 | 行首 # / * | <ol> / <ul> |
| 代码块 | {{...}} | <pre><code> |
| 自动链接 | 裸 URL / 邮箱 | <a class="url"> / mailto: |
| 带文字链接 | `[文字 | URL]` |
| 站内页面链接 | [页面名] | ./?page=页面名，不存在则 class="pending" |
| 维基百科链接 | [?词条] | http://<LANG>.wikipedia.org/wiki/词条 |
| 图片 | [图片URL]（可加 ` | left |
| 表格 | ` | ` 开头的连续行 |
| 转义 | ^X | 输出字面 X |
二、标题与目录（TOC）
2.1 标题写法与锚点
行首感叹号数量决定标题级别（13 级），渲染为带锚点的 <h1><h3>。实测渲染回显：
! 一级标题 → <h1><a name="_____________"> 一级标题</a></h1>
!! 二级标题 → <h2><a name="_____________"> 二级标题</a></h2>
!!! 三级标题 → <h3><a name="_____________"> 三级标题</a></h3>
三个关键细节（全部实测发现）：
- 感叹号后的空格会保留进标题文本：
! 一级标题渲染出的标题文本是一级标题（带前导空格），写!一级标题顶格更干净； - 锚点规则：锚点 = 标题文本中所有非字母数字字符替换为下划线（
preg_replace("/[^\da-z]/i","_",...)）。ASCII 标题正常，如官方 Aide 页的!Aide渲染为<h1><a name="Aide">Aide</a></h1>； - 中文标题的锚点会塌缩：中文字符全部不在
[a-z0-9]范围内，! 安装步骤、! 配置详解两条标题的锚点实测均为_____________（13 个下划线）——同一页面写多个中文标题，锚点全部同名，目录跳转与页内锚点链接会失效。中文站要么给标题加英文前缀（如! 1-Setup 安装步骤），要么放弃页内锚点跳转。
2.2 TOC 目录
在页面任意位置写单独一行 TOC，WiKiss 会在正文区域上方生成标题目录，实测渲染：
<div id="toc"><h1><a href="#_Alpha"> Alpha</a></h1> <h1><a href="#_Beta"> Beta</a></h1> <h2><a href="#_Beta_1"> Beta.1</a></h2> </div>
- 目录条目按标题级别用
<h1>~<h3>包裹，配合style.css的#toc规则（float:right右浮动、#toc h2缩进.5em起）呈现为右上角目录块； - 正文里第一个
TOC字样会被吞掉（作为占位符消耗），所以官方 Aide 页第一行写的TOC实测同样被替换成目录块——想在正文里显示"TOC"这三个字母，就得多写一个会被吞掉的占位行，或者用转义写法； TOC写在第一行与写在末尾效果相同（占位符是全文第一个匹配，目录块位置由模板固定在正文上方），官方帮助页建议"写在最后一行更清晰"只是排版习惯。
三、文字样式与分隔线
实测渲染回显（一行正文混用全部样式）：
普通正文，支持 <strong>粗体</strong>、<em>斜体</em>、<strong><em>粗斜体</em></strong>、<del>删除线</del>、<u>下划线</u>。
对应写法与注意点：
'''粗体'''→<strong>；''斜体''→<em>；'''''粗斜体'''''→<strong><em>（五撇必须整对出现，替换顺序是先匹配五撇再三撇后二撇，实测混写'''''X'''''不会拆成"斜体+斜体"）；- 删除线是单引号包裹双连字符
'--X--'→<del>，下划线同理'__X__'→<u>——注意不是裸的--X--，裸写不会被识别； - 行首四个及以上连字符
----渲染为<hr />（源码正则/----*(\r\n|\r|\n)/m，五根、六根横线都行）。
四、列表与代码块
4.1 两种列表（必须顶格）
# 有序列表一 → <ol><li> 有序列表一</li><li> 有序列表二</li></ol>
# 有序列表二
* 无序列表一 → <ul><li> 无序列表一</li><li> 无序列表二</li></ul>
* 无序列表二
注意 <li> 后保留了写法中的空格（# 有序列表一 的空格原样进入 <li> 文本），不影响显示。
嵌套列表不支持——这是官方 Aide 页没有明说、实测才能确认的边界。缩进两格写 * 缩进的子项，渲染结果是一行带 缩进的字面文本：
* 缩进的子项<br />
星号原样输出、没有进入任何 <ul>：列表标记只认行首顶格的 #/*，行首空格会被转换成 （这是 WiKiss 保留缩进排版的方式），列表标记因此失效。0.3 没有多级列表，需要层级感只能用缩进正文模拟。
4.2 代码块
双花括号包裹（可跨行）渲染为 <pre><code>，实测：
{{#!/bin/bash
echo "hello $USER"
}}
↓
<pre><code>#!/bin/bash
echo "hello $USER"
</code></pre>
两个要点：代码块内容不经过其他语法替换（*、#、''' 都原样保留），适合贴脚本与配置；但 $ 与 \ 两个字符在渲染期会被转义为 HTML 实体（$、\）——这是全文渲染管线的统一行为（防与替换逻辑冲突），页面上显示效果仍是 $，只是查看 HTML 源码时看到的是实体。
五、链接与图片
5.1 自动链接与手写链接
自动链接：http://wikiss.tuxfamily.org/ → <a href="http://wikiss.tuxfamily.org/" class="url">http://wikiss.tuxfamily.org/</a>
邮箱：mail@example.org → <a href="mailto:mail@example.org">mail@example.org</a>
带文字链接：[WiKiss 官网|http://...] → <a href="http://wikiss.tuxfamily.org/" class="url">WiKiss 官网</a>
站内链接：[Accueil] → <a href="./?page=Accueil">Accueil</a>
维基百科：[?WiKiss] → <a href="http://fr.wikipedia.org/wiki/WiKiss" class="url" title="Wikipedia">WiKiss</a>
- 裸 URL 与邮箱"automagically"识别（官方 Aide 页原话），链接都带
class="url"； - 维基百科链接的语言由配置项
$LANG决定：实测把_config.php的$LANG从fr改为en后，同一[?Wiki]的渲染从http://fr.wikipedia.org/wiki/Wiki变为http://en.wikipedia.org/wiki/Wiki——中文站要链中文维基可设$LANG = "zh"（该变量的完整行为与副作用解析见本专栏配置参数详解篇）； - 站内页面链接
[页面名]渲染为./?page=页面名，中文页面名不做 URL 编码（实测href="./?page=中文页面"），交给浏览器自动编码，实测点击与渲染均正常； - 链接指向不存在的页面时带
class="pending"：
[不存在页面XYZ] → <a href="./?page=不存在页面XYZ" class="pending" >不存在页面XYZ</a>
.pending 在默认样式中显示为红色——这就是 Wiki 经典的"红色待建链接"，点击即进入该页的编辑表单，保存后完成建页（建页行为细节见使用篇）。
5.2 图片
把图片 URL 放进方括号即成 <img>，实测四种形态：
[http://.../logo_100.png] → <img src="http://.../logo_100.png" alt="http://.../logo_100.png" style="float:;"/>
[http://.../logo_100.png|left] → <img src="..." style="float:left;"/>
[http://.../logo_100.png|http://wikiss...] → <a href="http://wikiss.tuxfamily.org/" class="url"><img src="..." style="float:right;"/></a>
[/logo_100.png] → <img src="/logo_100.png" alt="/logo_100.png" style="float:"/>
[图片URL|left]/|right左右浮动；[图片URL|目标URL]变成带链接的图片；- 什么浮动都不写时渲染出
style="float:;"空浮动——0.3 的一个小瑕疵，CSS 会忽略非法值，无实际影响； - 本地图片用根相对路径
/logo_100.png（实测）：把图片文件放到站点根目录（与index.php同级）即可引用，这是自托管场景最常用的插图方式。
六、特殊字符与转义
6.1 自动转换的特殊字符
特殊字符：<-- --> <-> (c) (C) (r) (R)
↓
特殊字符：← → <-> © © ® ®
<--→←（←）、-->→→（→）、<->不转换（原样输出）；(c)/(C)→©（©）、(r)/(R)→®（®），小写大写都认。
6.2 ^ 转义体系
插入符 ^ 是 WiKiss 的转义前缀：^X 把字符 X 以字面形式输出、阻止其参与语法解析。实测：
^[WiKiss] 与 ^^ 与 ^< 与 ^(c)
↓
[WiKiss] 与 ^ 与 &lt; 与 (c)
^[WiKiss]显示为[WiKiss]文本（不再成为链接）、^^显示^、^(c)显示(c)（不会被转成 ©）——这是在页面里展示"语法本身"（比如写本文这类教程页）的标准手段，官方 Aide 页通篇就是这么写的（源文件里满屏^''^'Gras^''^'）；^<是个双转义边界：保存期<先被转成<落盘，渲染期^实际转义的是&，得到&lt;——页面上显示的是<四个字符而不是<。同理^--、^-->想显示字面箭头也要过这道转换。想让读者看到<，写^<才是正解；^X按单字节处理（安装篇 PHP 8.1 修复实录中^é乱码问题的同一根源），对中文等多字节字符无意义——中文站直接写原生 UTF-8 字符即可，^转义只在需要展示 ASCII 语法符号时使用。
七、表格语法（wkp_Tables 插件）
表格由自带插件 wkp_Tables.php 提供（插件机制见使用篇），连续的、以 | 开头的行构成一个表格块。官方样例（AideTables 页源文件）实测渲染：
|h 标题 A|h 标题 B|
|r 右对齐|l 左对齐|
|2 跨两列|
|t ,2 跨两行| 甲 |
| 乙 |
↓
<table class="wikitable">
<tr><td class="em">标题 A</td><td class="em">标题 B</td></tr>
<tr><td style="text-align: right; ">右对齐</td><td style="text-align: left; ">左对齐</td></tr>
<tr><td colspan="2" >跨两列</td></tr>
<tr><td rowspan="2" style="vertical-align: top; ">跨两行</td><td >甲 </td></tr>
<tr><td >乙 </td></tr>
</table>
7.1 单元格前缀标记
单元格开头写「标记字母 + 空格」控制样式，可组合（如 hl），数字控制跨行跨列：
| 前缀 | 作用 | 渲染（实测） |
|---|---|---|
h | 表头样式 | class="em"（加粗）——0.3 不渲染 <th>，表头只是加了样式的 <td> |
l / r | 水平对齐 | style="text-align: left; " / right |
t / b | 垂直对齐 | style="vertical-align: top; " / bottom |
数字 | 跨列（colspan） | <td colspan="2"> |
,数字 | 跨行（rowspan） | <td rowspan="2" style="vertical-align: top; "> |
跨行单元格的续行写法：被跨的行写一个缩进的 | 单元格 |（见上例 | 乙 |），| 乙 | 会归入同一表格的第二行。
7.2 表格块边界与多表格
表格块以第一行非 | 开头的行结束；一行不以 | 开头的文字会把表格"切断"，之后的 | 行再起新表格。实测同一页面写两个表格块，渲染出两个独立的 <table class="wikitable">（上文示例与带 hl/hr 表头的第二个表格），互不粘连。这个特性也是排障点：表格中间手滑写了一行没带 | 的文字，表格就会在那里断开，看起来像"表格只剩一半"。
7.3 表格内的行内语法：支持与边界
- 单元格内链接正常：
|单元格内链接：[Accueil|?page=Accueil]|实测渲染<a href="?page=Accueil" class="url">Accueil</a>（表格插件对链接做"暂存-回填"处理，相对?page=形态也可用）； - 纯样式单元格的粗体/斜体/删除线正常：官方 AideTables 页内嵌演示表实测渲染出
<em>italique</em>、<strong>gras</strong>、<strong><em>gras italique</em></strong>、<del>rayé</del>； - 实测边界：同一单元格内混用"链接 + 粗体"时，粗体标记会被吞掉——写
|'''X''' 与链接：[Accueil|?page=Accueil]|渲染为单元格内粗体：X 与链接：<a ...>，三撇原样消失、只剩裸文本 X，链接则正常。混用场景建议拆到不同单元格； - 表格内不支持的语法（官方 AideTables 页"Syntaxe non supportée"一节明确声明）：标题
!!、列表*/#、分隔线----——单元格里写这些只会得到字面文本。
八、页面常用操作（实测）
8.1 建页：三个入口，一个本质
三个入口最终都走同一条路——编辑表单 + 保存：浏览器直接访问不存在的页面名（./?page=新页面，看到 $DEFAULT_CONTENT 配置的占位文本）、点击红色 pending 链接、或在任意编辑框把 page 字段改成新名字。本质都是「页面名即文件名」：保存后 pages/新页面.txt 落盘。空格页面名与中文页面名实测均可用：Space Test 落盘为 pages/Space Test.txt、URL 用 ?page=Space%20Test 访问正常渲染；中文页面 落盘为 pages/中文页面.txt。
8.2 页面改名：两步 mv，缺一不可
WiKiss 没有改名功能，直接在服务器上改文件即可，但页面文件与历史目录必须一起改（实测）：
cd /var/www/wikiss
# 第一步：改页面文件
sudo mv pages/RenameA.txt pages/RenameB.txt
# 第二步：改历史备份目录（漏掉这步历史就"丢"了）
sudo mv historique/RenameA historique/RenameB
两步都做完后，?page=RenameB 正常渲染原内容，?page=RenameB&action=history 里 .bak 历史备份完整保留（实测 20261030-0654.bak 随目录迁移）。反例实测：只改 .txt 不动 historique/RenameA/，新页面名的 history 页显示"Aucun historique existant."（无历史记录）——旧备份目录成了孤儿，改名后新保存的备份还会开一个新目录，历史从此分家。
8.3 页面锁定：chmod 444
0.3 的"锁定"是文件系统级的：把页面文件改为对 Apache 运行用户（www-data）只读，页面右上角的"Éditer"按钮实测变为 Page verrouillée：
sudo chmod 444 pages/Aide.txt # 锁定：编辑按钮消失，显示"Page verrouillée"
sudo chmod 664 pages/Aide.txt # 解锁：Éditer 按钮实测回归
页面右上角的锁定提示对应配置项 $PROTECTED_BUTTON，提示文案可在 _config.php 中修改。判断逻辑在源码里很直白：is_writable() 为假就渲染锁定文案。注意 historique/ 目录权限别跟着锁死，否则下次保存会因为写不了备份报错。
8.4 删除、恢复与编辑 Cookie
- 删除页面 = 编辑框清空后保存（实测等价于
unlink），.bak历史备份不随删除清理——误删页面的找回路径是查看historique/页面名/下的备份并用&time=时间戳&restore=1回填（完整流程见使用篇）； - 编辑 Cookie 的清除：通过口令登录后（Cookie
AutorisationWiKiss），页面底部会出现Eff. cookie链接（实测形态<a href="./?page=BackupOff&erasecookie=1" rel="nofollow">Eff. cookie</a>），点击访问&erasecookie=1后 Cookie 被置空、链接实测消失——公共电脑上编辑完记得点它。
九、FAQ
Q：列表能嵌套吗？ 不能。缩进的 */# 会被转成 缩进的字面文本（第四节实测回显）。0.3 只有一级列表。
Q：单元格里能放标题/列表/分隔线吗？ 不能，官方 AideTables 页明确声明这三类不支持。粗体斜体在纯样式单元格内可用，但与链接同格混用时粗体标记实测会被吞（7.3 节）。
Q：目录（TOC）跳转对中文标题失效？ 是锚点塌缩：中文标题的锚点全部变成同名下划线串（2.1 节实测），同一页多个中文标题的锚点互相覆盖。给标题补英文/数字前缀可规避。
Q：表格渲染成空的 <table></table> 或直接消失？ 这是 PHP 8.1 兼容问题的静默失败形态（wkp_Tables 的两处 /e 修饰符），修复方法见安装篇的修复 4/8 与一键补丁脚本。
Q：想显示语法本身怎么办？ 用 ^ 转义（6.2 节）：^''^'X^''^' 显示 '''X'''。官方 Aide 页全文都是这么写的，直接打开 ?page=Aide 点编辑看源码是最快的学习方式。
Q：图片想放页面子目录里行吗？ 行，路径相对站点根：把图片放 img/ 子目录后写 [/img/pic.png] 即可（与 /logo_100.png 同机制）。但注意 pages/、historique/ 目录不要用来存图片——它们是 WiKiss 的数据目录，会被页面列表/最近更改等动作扫描。