月更 技术博客 CXX优先 Zola 2026-06-24T00:00:00+00:00 https://suchaharcan.github.io/tags/release/atom.xml 2026-06-24T00:00:00+00:00 2026-06-24T00:00:00+00:00 Suchaharcan https://suchaharcan.github.io/03Share_blog/website-v1-release/ <p>本文面向 <strong>访客与自建站参考者</strong>，说明本站 <strong>v1.0 正式版</strong> 的目录结构、设计架构，以及撰写博客时在 <code>+++</code>（TOML front matter）中可用的全部字段。技术栈为 <a class="external" rel="external" href="https://www.getzola.org/">Zola</a> + <a class="external" rel="external" href="https://ametrine.daudix.one">Ametrine</a> 主题；站点级定制在仓库根目录，<strong>不修改 <code>themes/</code></strong>。</p> <p>更细的模板 / Markdown 写法见 <a href="https://suchaharcan.github.io/03Share_blog/zola-template-markdown-guide/">Zola 模板开发要点与 Markdown 语法速查</a>；本轮功能迭代见 <a href="https://suchaharcan.github.io/nanolog/2026-06-24t04-00-00z/">Nanolog 更新总结</a>。</p> <hr /> <h2 id="yi-ban-ben-1-0-neng-li-zong-lan">一、版本 1.0 能力总览</h2> <table><thead><tr><th>模块</th><th>路径 / 入口</th><th>说明</th></tr></thead><tbody> <tr><td>首页 Hub</td><td><code>/</code></td><td>个人介绍、徽章、联系方式</td></tr> <tr><td>In - Reading</td><td><code>/00Read_blog_Math/</code> 等</td><td>在读笔记（可加密）</td></tr> <tr><td>Out - Writing</td><td><code>/01Write_blog_CXX20/</code> 等</td><td>原创技术文</td></tr> <tr><td>Out - Share</td><td><code>/03Share_blog/</code></td><td>工作流、工具分享</td></tr> <tr><td>Debug</td><td><code>/02Engineer_blog_Debug/</code></td><td>排障记录</td></tr> <tr><td>周计划看板</td><td><code>/kanban/</code></td><td>Trello 风格 + Markdown 规则引擎</td></tr> <tr><td>Design</td><td><code>/design/</code></td><td>产品 / CLI / 插件展示</td></tr> <tr><td>Nanolog</td><td><code>/nanolog/</code></td><td>站点开发短日志</td></tr> <tr><td>BasB</td><td><code>/basb/</code></td><td>笔记树状整理</td></tr> <tr><td>Archive</td><td><code>/archive/</code></td><td>全站文章归档 + 热力图</td></tr> <tr><td>Umami 统计</td><td>全站</td><td>隐私友好访问量</td></tr> <tr><td>文章加密</td><td>按文启用</td><td>构建期 AES-GCM + 管理员 / 访客双模式解密</td></tr> </tbody></table> <p><strong>构建命令：</strong></p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">./build-site.sh</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 加密 → zola build → 搜索索引补丁</span></span> <span class="giallo-l"><span class="z-entity z-name">zola</span><span class="z-string"> serve</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 本地预览（加密解密需 localhost 或 HTTPS）</span></span></code></pre> <hr /> <h2 id="er-yuan-ma-mu-lu-shu">二、源码目录树</h2> <p>以下为 <strong>访客可见逻辑相关的仓库结构</strong>（省略 <code>public/</code> 构建产物与主题内 demo 细节）：</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>00BlogZola/</span></span> <span class="giallo-l"><span>├── zola.toml # 全站配置（导航、CSP、统计、加密、分类…）</span></span> <span class="giallo-l"><span>├── build-site.sh # 正式构建入口</span></span> <span class="giallo-l"><span>├── scripts/</span></span> <span class="giallo-l"><span>│ ├── encrypt-content.mjs # 构建前：加密标记文章 → static/encryption/pages/</span></span> <span class="giallo-l"><span>│ ├── encryption-lib.mjs # 加密路径 / front matter 解析共用库</span></span> <span class="giallo-l"><span>│ └── patch-search-index.mjs</span></span> <span class="giallo-l"><span>├── content/ # 所有页面内容（Markdown）</span></span> <span class="giallo-l"><span>│ ├── _index.md # 首页</span></span> <span class="giallo-l"><span>│ ├── 00Read_blog_Math/ # 在读 · 数学</span></span> <span class="giallo-l"><span>│ ├── 00Read_blog_English/</span></span> <span class="giallo-l"><span>│ ├── 01Write_blog_*/ # 写作各子专栏（CMake / CXX / 论文…）</span></span> <span class="giallo-l"><span>│ ├── 02Engineer_blog_Debug/</span></span> <span class="giallo-l"><span>│ ├── 03Share_blog/</span></span> <span class="giallo-l"><span>│ ├── kanban/ # 周计划（列表 + 每周 .md）</span></span> <span class="giallo-l"><span>│ ├── nanolog/ # 开发日志（单文件即一篇）</span></span> <span class="giallo-l"><span>│ ├── design/ # Design 页 + apps/* 子应用</span></span> <span class="giallo-l"><span>│ ├── basb/ # 树状笔记</span></span> <span class="giallo-l"><span>│ └── archive/</span></span> <span class="giallo-l"><span>├── templates/ # 覆盖主题的 Tera 模板（优先级高于 theme）</span></span> <span class="giallo-l"><span>│ ├── base.html # 全站：加密配置 + admin.js 注入</span></span> <span class="giallo-l"><span>│ ├── article.html # 文章：普通 / 加密分支</span></span> <span class="giallo-l"><span>│ ├── partials/</span></span> <span class="giallo-l"><span>│ │ ├── encrypted_article.html</span></span> <span class="giallo-l"><span>│ │ ├── encryption_config.html</span></span> <span class="giallo-l"><span>│ │ └── heatmap_component.html</span></span> <span class="giallo-l"><span>│ ├── kanban.html / kanban_list.html</span></span> <span class="giallo-l"><span>│ ├── nanolog.html / nanolog_list.html</span></span> <span class="giallo-l"><span>│ ├── design.html / design_app.html</span></span> <span class="giallo-l"><span>│ ├── archive.html / basb.html</span></span> <span class="giallo-l"><span>│ ├── shortcodes/ # Markdown 短代码</span></span> <span class="giallo-l"><span>│ └── macros/encryption.html</span></span> <span class="giallo-l"><span>├── static/ # 原样拷贝到站点根 URL</span></span> <span class="giallo-l"><span>│ ├── analytic/umami.js</span></span> <span class="giallo-l"><span>│ ├── encryption/ # 加解密运行时（admin / visitor / crypto / article）</span></span> <span class="giallo-l"><span>│ ├── js/ # kanban、nanolog、热力图、滚动条…</span></span> <span class="giallo-l"><span>│ └── kanban/ …</span></span> <span class="giallo-l"><span>├── sass/ # 站点 SCSS（编译为 CSS）</span></span> <span class="giallo-l"><span>│ ├── kanban/ nanolog/ design/ home/ …</span></span> <span class="giallo-l"><span>└── themes/ametrine/ # 上游主题（勿改；用 templates/ 扩展）</span></span></code></pre> <p><strong>模板覆盖原则：</strong> <code>templates/foo.html</code> 与主题同名时 <strong>完全替换</strong> 主题文件；常用模式为 <code>{%% extends "ametrine/templates/....html" %%}</code> + <code>{%% block %%}</code> 扩展。</p> <hr /> <h2 id="san-she-ji-jia-gou">三、设计架构</h2> <h3 id="3-1-fen-ceng-shi-yi">3.1 分层示意</h3> <pre class="giallo z-code"><code data-lang="mermaid"><span class="giallo-l"><span>flowchart TB</span></span> <span class="giallo-l"><span> subgraph build [构建期]</span></span> <span class="giallo-l"><span> MD[content/*.md]</span></span> <span class="giallo-l"><span> ENC[scripts/encrypt-content.mjs]</span></span> <span class="giallo-l"><span> ZOLA[zola build]</span></span> <span class="giallo-l"><span> MD --&gt; ENC</span></span> <span class="giallo-l"><span> ENC --&gt;|密文 JSON| STATIC_ENC[static/encryption/pages/]</span></span> <span class="giallo-l"><span> MD --&gt; ZOLA</span></span> <span class="giallo-l"><span> STATIC_ENC --&gt; ZOLA</span></span> <span class="giallo-l"><span> ZOLA --&gt; PUBLIC[public/ 静态站点]</span></span> <span class="giallo-l"><span> end</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> subgraph runtime [浏览器运行时]</span></span> <span class="giallo-l"><span> PUBLIC --&gt; HTML[HTML + textarea 配置]</span></span> <span class="giallo-l"><span> HTML --&gt; ADMIN[admin.js 特权模式]</span></span> <span class="giallo-l"><span> HTML --&gt; VISITOR[visitor.js 随机解密]</span></span> <span class="giallo-l"><span> HTML --&gt; ARTICLE[article.js 解密渲染]</span></span> <span class="giallo-l"><span> ADMIN --&gt; ARTICLE</span></span> <span class="giallo-l"><span> VISITOR --&gt; ARTICLE</span></span> <span class="giallo-l"><span> HTML --&gt; UMAMI[umami.js 统计]</span></span> <span class="giallo-l"><span> HTML --&gt; KANBAN[kanban-board.js]</span></span> <span class="giallo-l"><span> HTML --&gt; NANO[nanolog.js]</span></span> <span class="giallo-l"><span> end</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> subgraph theme [Ametrine 主题层]</span></span> <span class="giallo-l"><span> BASE[base.html 骨架]</span></span> <span class="giallo-l"><span> SIDE[sidebar 导航]</span></span> <span class="giallo-l"><span> HEAD[head.html CSP/脚本]</span></span> <span class="giallo-l"><span> end</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> HTML --&gt; BASE</span></span> <span class="giallo-l"><span> BASE --&gt; SIDE</span></span> <span class="giallo-l"><span> BASE --&gt; HEAD</span></span></code></pre><h3 id="3-2-nei-rong-mo-ban-bang-ding">3.2 内容 → 模板绑定</h3> <table><thead><tr><th>内容类型</th><th>front matter 关键字段</th><th>渲染模板</th></tr></thead><tbody> <tr><td>专栏列表</td><td><code>template = "article_list.html"</code></td><td>文章卡片列表</td></tr> <tr><td>普通文章</td><td><code>page_template = "article.html"</code>（section 默认）</td><td>文章页 + 可选热力图</td></tr> <tr><td>加密文章</td><td><code>[extra.encryption] encrypt = true</code></td><td><code>partials/encrypted_article.html</code></td></tr> <tr><td>周计划列表</td><td><code>template = "kanban_list.html"</code></td><td>周卡片 + 进度</td></tr> <tr><td>周计划明细</td><td><code>page_template = "kanban.html"</code></td><td>五列看板</td></tr> <tr><td>Nanolog 列表</td><td><code>template = "nanolog_list.html"</code></td><td>时间线短帖</td></tr> <tr><td>Nanolog 单篇</td><td><code>page_template = "nanolog.html"</code></td><td>单条日志</td></tr> <tr><td>Design</td><td><code>template = "design.html"</code></td><td>产品网格</td></tr> <tr><td>Archive</td><td><code>template = "archive.html"</code></td><td>归档 + 热力图</td></tr> <tr><td>BasB</td><td><code>template = "basb.html"</code></td><td>树状笔记索引</td></tr> </tbody></table> <h3 id="3-3-an-quan-yu-te-quan-mo-xing">3.3 安全与特权模型</h3> <pre class="giallo z-code"><code data-lang="mermaid"><span class="giallo-l"><span>stateDiagram-v2</span></span> <span class="giallo-l"><span> [*] --&gt; Visitor: 默认</span></span> <span class="giallo-l"><span> Visitor --&gt; Admin: 连点左上角图标 6 次</span></span> <span class="giallo-l"><span> Admin --&gt; Visitor: admin_ttl_secs 到期</span></span> <span class="giallo-l"><span> Visitor --&gt; LuckyDecrypt: 同文刷新 9~20 次 session</span></span> <span class="giallo-l"><span> LuckyDecrypt --&gt; Visitor: 关闭标签页 / 新 session</span></span> <span class="giallo-l"><span> Admin --&gt; Decrypted: 全部加密文可读</span></span> <span class="giallo-l"><span> LuckyDecrypt --&gt; Decrypted: 单篇可读</span></span></code></pre> <ul> <li><strong>访客：</strong> 加密文默认上锁；看板固定「只读（已过期）」样式；隐藏 Edit Post / ReDeplog。</li> <li><strong>管理员：</strong> <code>html.encryption-admin-active</code> 时显示编辑按钮、可解密、看板在有效期内可解锁。</li> <li><strong>配置：</strong> <code>zola.toml</code> → <code>[extra.encryption]</code>（见下文站点级表）。</li> </ul> <hr /> <h2 id="si-front-matter-zi-duan-su-cha">四、Front matter（<code>+++</code>）字段速查</h2> <p>Zola 使用 <strong>TOML</strong> 作为 front matter。以下汇总 <strong>本站实际可用</strong> 的字段；未列出的键也可写入 <code>[extra]</code>，但需自行在模板中读取才会生效。</p> <h3 id="4-1-ding-ceng-tong-yong-zi-duan-page-section-jun-ke">4.1 顶层通用字段（Page / Section 均可）</h3> <table><thead><tr><th>字段</th><th>类型</th><th>必填</th><th>说明</th></tr></thead><tbody> <tr><td><code>title</code></td><td>string</td><td>推荐</td><td>标题；侧边栏、<code>&lt;title&gt;</code>、列表卡片</td></tr> <tr><td><code>description</code></td><td>string</td><td>推荐</td><td>摘要；SEO、<code>og:description</code></td></tr> <tr><td><code>date</code></td><td>date</td><td>文章推荐</td><td>发布日期，如 <code>2026-06-24</code></td></tr> <tr><td><code>updated</code></td><td>date</td><td>可选</td><td>更新日期，显示在文章元信息</td></tr> <tr><td><code>draft</code></td><td>bool</td><td>可选</td><td><code>true</code> 时默认不构建；需 <code>zola build --drafts</code></td></tr> <tr><td><code>weight</code></td><td>int</td><td>可选</td><td>排序权重（配合 <code>sort_by = "weight"</code>）</td></tr> <tr><td><code>sort_by</code></td><td>string</td><td>Section</td><td>子页排序：<code>date</code> / <code>weight</code> / <code>title</code> 等</td></tr> <tr><td><code>template</code></td><td>string</td><td>Section</td><td><strong>当前页</strong>使用的模板文件名</td></tr> <tr><td><code>page_template</code></td><td>string</td><td>Section</td><td><strong>子页面</strong>默认模板</td></tr> <tr><td><code>paginate_by</code></td><td>int</td><td>Section</td><td>列表分页条数，如 <code>10</code></td></tr> <tr><td><code>generate_feeds</code></td><td>bool</td><td>Section</td><td>是否生成 atom/rss</td></tr> <tr><td><code>aliases</code></td><td>[string]</td><td>可选</td><td>URL 别名，如 <code>["home"]</code>、<code>["Dev_log"]</code></td></tr> <tr><td><code>authors</code></td><td>[string]</td><td>可选</td><td>多作者（主题支持时显示）</td></tr> <tr><td><code>transparent</code></td><td>bool</td><td>可选</td><td>用于 Archive / BasB 等透明背景布局</td></tr> </tbody></table> <p><strong>Section <code>_index.md</code> 示例：</strong></p> <pre class="giallo z-code"><code data-lang="toml"><span class="giallo-l"><span class="z-invalid">+++</span></span> <span class="giallo-l"><span class="z-variable z-other">title</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">效率-工作流</span><span class="z-punctuation">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other">sort_by</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">date</span><span class="z-punctuation">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other">template</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">article_list.html</span><span class="z-punctuation">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other">page_template</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">article.html</span><span class="z-punctuation">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other">paginate_by</span><span class="z-punctuation"> =</span><span class="z-constant z-numeric"> 10</span></span> <span class="giallo-l"><span class="z-variable z-other">generate_feeds</span><span class="z-punctuation"> =</span><span class="z-constant z-language"> true</span></span> <span class="giallo-l"><span class="z-punctuation">[</span><span class="z-entity z-name z-section">extra</span><span class="z-punctuation">]</span></span> <span class="giallo-l"><span class="z-variable z-other">no_header</span><span class="z-punctuation"> =</span><span class="z-constant z-language"> true</span></span> <span class="giallo-l"><span class="z-variable z-other">scripts</span><span class="z-punctuation"> =</span><span class="z-punctuation"> [</span><span class="z-punctuation">&quot;</span><span class="z-string">analytic/umami.js</span><span class="z-punctuation">&quot;</span><span class="z-punctuation">]</span></span> <span class="giallo-l"><span class="z-invalid">+++</span></span></code></pre> <hr /> <h3 id="4-2-taxonomies-fen-lei-fa">4.2 <code>[taxonomies]</code> 分类法</h3> <p>本站 <code>zola.toml</code> 启用：</p> <pre class="giallo z-code"><code data-lang="toml"><span class="giallo-l"><span class="z-variable z-other">taxonomies</span><span class="z-punctuation"> =</span><span class="z-punctuation"> [</span></span> <span class="giallo-l"><span class="z-punctuation"> {</span><span class="z-variable z-other"> name</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">tags</span><span class="z-punctuation">&quot;</span><span class="z-punctuation">,</span><span class="z-variable z-other"> feed</span><span class="z-punctuation"> =</span><span class="z-constant z-language"> true</span><span class="z-punctuation">,</span><span class="z-variable z-other"> paginate_by</span><span class="z-punctuation"> =</span><span class="z-constant z-numeric"> 10</span><span class="z-punctuation"> }</span><span class="z-punctuation">,</span></span> <span class="giallo-l"><span class="z-punctuation"> {</span><span class="z-variable z-other"> name</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">categories</span><span class="z-punctuation">&quot;</span><span class="z-punctuation">,</span><span class="z-variable z-other"> feed</span><span class="z-punctuation"> =</span><span class="z-constant z-language"> true</span><span class="z-punctuation"> }</span><span class="z-punctuation">,</span></span> <span class="giallo-l"><span class="z-punctuation">]</span></span></code></pre><table><thead><tr><th>字段</th><th>类型</th><th>说明</th></tr></thead><tbody> <tr><td><code>tags</code></td><td>[string]</td><td>自由标签，如 <code>["Zola", "CXX"]</code></td></tr> <tr><td><code>categories</code></td><td>[string]</td><td>分类；<strong>枚举值</strong>见下表</td></tr> </tbody></table> <p><strong><code>categories</code> 可选枚举（<code>zola.toml</code> → <code>[[extra.categories]]</code>）：</strong></p> <table><thead><tr><th>值</th><th>含义</th><th>主题色</th></tr></thead><tbody> <tr><td><code>Archived</code></td><td>归档文</td><td>purple</td></tr> <tr><td><code>Featured</code></td><td>精选</td><td>yellow</td></tr> <tr><td><code>Hot</code></td><td>热门</td><td>red</td></tr> </tbody></table> <hr /> <h3 id="4-3-extra-ye-mian-zhuan-lan-kuo-zhan-ametrine-ben-zhan">4.3 <code>[extra]</code> — 页面 / 专栏扩展（Ametrine + 本站）</h3> <p>继承规则：<strong>页面 <code>page.extra.*</code> 优先，否则回退 <code>section.extra.*</code>，再回退 <code>config.extra.*</code>。</strong></p> <h4 id="bu-ju-yu-zhan-shi">布局与展示</h4> <table><thead><tr><th>字段</th><th>类型</th><th>枚举 / 格式</th><th>作用</th></tr></thead><tbody> <tr><td><code>no_header</code></td><td>bool</td><td><code>true</code> / <code>false</code></td><td>不渲染正文顶部 <code>&lt;h1&gt;</code></td></tr> <tr><td><code>backlinks</code></td><td>bool</td><td><code>true</code> / <code>false</code></td><td>文末显示反向链接（需全局 <code>show_backlinks</code>）</td></tr> <tr><td><code>toc</code></td><td>bool</td><td><code>true</code> / <code>false</code></td><td>侧栏目录（实际由文内标题 + Zola <code>page.toc</code> 生成）</td></tr> <tr><td><code>accent_color</code></td><td>string 或 [string, string]</td><td>见下方 <strong>强调色枚举</strong></td><td>页面主题色 / <code>theme-color</code></td></tr> <tr><td><code>accent_color_dark</code></td><td>string</td><td>HSL 或预设名</td><td>仅深色模式强调色（可选）</td></tr> <tr><td><code>banner</code></td><td>string</td><td>文件名</td><td>与 <code>index.md</code> 同目录的横幅图</td></tr> <tr><td><code>banner_position</code></td><td>string</td><td>CSS 值，如 <code>center top</code></td><td>列表缩略图裁剪位置</td></tr> <tr><td><code>banner_pixels</code></td><td>bool</td><td><code>true</code></td><td>横幅像素风渲染</td></tr> </tbody></table> <p><strong><code>accent_color</code> 枚举与格式（主题文档）：</strong></p> <table><thead><tr><th>写法</th><th>示例</th><th>说明</th></tr></thead><tbody> <tr><td>预设名（双色同用）</td><td><code>"blue"</code></td><td>浅色/深色各用主题预设</td></tr> <tr><td>预设数组</td><td><code>["red", "blue"]</code></td><td>浅色 red、深色 blue</td></tr> <tr><td>单色 HSL</td><td><code>"hsl(270 50% 60%)"</code></td><td>两模式同色</td></tr> <tr><td>HSL 数组</td><td><code>["hsl(26 25% 34%)", "hsl(27 31% 53%)"]</code></td><td>浅色 / 深色各一</td></tr> </tbody></table> <p>预设名可选：<code>red</code> · <code>orange</code> · <code>yellow</code> · <code>green</code> · <code>blue</code> · <code>purple</code></p> <h4 id="yuan-shu-ju-yu-she-jiao-qia-pian-extra-meta">元数据与社交卡片 <code>[extra.meta]</code></h4> <table><thead><tr><th>字段</th><th>类型</th><th>说明</th></tr></thead><tbody> <tr><td><code>meta.card</code></td><td>string</td><td>自定义 OG 卡片图（相对页面路径）</td></tr> <tr><td><code>meta.favicon</code></td><td>string</td><td>页级 favicon</td></tr> <tr><td><code>meta.apple_touch_icon</code></td><td>string / bool</td><td>页级 Apple 图标</td></tr> </tbody></table> <h4 id="sheng-ming-kuai-wen-zhang-ding-bu-ti-shi">声明块（文章顶部提示）</h4> <table><thead><tr><th>字段</th><th>类型</th><th>说明</th></tr></thead><tbody> <tr><td><code>archive</code></td><td>string (markdown)</td><td>归档说明条</td></tr> <tr><td><code>trigger</code></td><td>string (markdown)</td><td>内容预警条</td></tr> <tr><td><code>disclaimer</code></td><td>string (markdown)</td><td>免责声明条</td></tr> </tbody></table> <h4 id="zi-yuan-jia-zai">资源加载</h4> <table><thead><tr><th>字段</th><th>类型</th><th>格式</th><th>说明</th></tr></thead><tbody> <tr><td><code>styles</code></td><td>[string]</td><td>相对 <code>static/</code> 或 sass 输出</td><td>额外 CSS，如 <code>["kanban/style.css"]</code></td></tr> <tr><td><code>scripts</code></td><td>[string]</td><td>相对 <code>static/</code></td><td>额外 JS；页面级覆盖 section</td></tr> </tbody></table> <p><strong>常用 <code>scripts</code> 值：</strong></p> <table><thead><tr><th>值</th><th>用途</th></tr></thead><tbody> <tr><td><code>analytic/umami.js</code></td><td>Umami 统计</td></tr> <tr><td><code>js/nanolog.js</code></td><td>Nanolog 发布 / 编辑</td></tr> <tr><td><code>js/kanban-rules.js</code></td><td>看板规则引擎</td></tr> <tr><td><code>js/kanban-board.js</code></td><td>看板明细交互</td></tr> <tr><td><code>js/kanban-list.js</code></td><td>看板列表</td></tr> <tr><td><code>js/design-apps.js</code></td><td>Design 应用网格</td></tr> <tr><td><code>encryption/*.js</code></td><td>由 <code>base.html</code> 全站注入，一般无需手写</td></tr> </tbody></table> <h4 id="gong-neng-kai-guan">功能开关</h4> <table><thead><tr><th>字段</th><th>类型</th><th>说明</th></tr></thead><tbody> <tr><td><code>copy_button</code></td><td>bool</td><td>代码块复制按钮（可覆盖全站 <code>copy_button</code>）</td></tr> <tr><td><code>audio_button</code></td><td>bool</td><td>文章朗读按钮</td></tr> </tbody></table> <h4 id="fediverse-ping-lun-extra-fediverse">Fediverse 评论 <code>[extra.fediverse]</code></h4> <table><thead><tr><th>字段</th><th>类型</th><th>说明</th></tr></thead><tbody> <tr><td><code>host</code></td><td>string</td><td>实例域名，如 <code>vmst.io</code></td></tr> <tr><td><code>user</code></td><td>string</td><td>用户名</td></tr> <tr><td><code>id</code></td><td>string</td><td>帖子 ID；<strong>三者齐全时</strong>加载评论线程</td></tr> </tbody></table> <h4 id="ce-lan-mei-ti-extra-music-extra-weather">侧栏媒体 <code>[extra.music]</code> / <code>[extra.weather]</code></h4> <p><strong>music</strong> — 数组，每项：</p> <table><thead><tr><th>键</th><th>类型</th><th>枚举 / 说明</th></tr></thead><tbody> <tr><td><code>type</code></td><td>string</td><td><code>album</code> · <code>track</code></td></tr> <tr><td><code>mbid</code></td><td>string</td><td>MusicBrainz ID（可选）</td></tr> <tr><td><code>artist</code></td><td>string</td><td>艺术家名</td></tr> <tr><td><code>name</code></td><td>string</td><td>曲名 / 专辑名</td></tr> </tbody></table> <p><strong>weather</strong> — 表：</p> <table><thead><tr><th>键</th><th>类型</th><th>枚举 / 说明</th></tr></thead><tbody> <tr><td><code>condition</code></td><td>string</td><td>描述文字</td></tr> <tr><td><code>style</code></td><td>string</td><td><code>cloudy</code> · <code>showers</code> · <code>snowing</code></td></tr> <tr><td><code>icon</code></td><td>string</td><td><a class="external" rel="external" href="https://phosphoricons.com">Phosphor</a> 图标名</td></tr> <tr><td><code>temp</code></td><td>string</td><td>温度数值</td></tr> <tr><td><code>unit</code></td><td>string</td><td><code>C</code>（默认）或 <code>F</code></td></tr> </tbody></table> <hr /> <h3 id="4-4-extra-encryption-ben-zhan-jia-mi-dan-pian-wen-zhang">4.4 <code>[extra.encryption]</code> — 本站加密（单篇文章）</h3> <table><thead><tr><th>字段</th><th>类型</th><th>说明</th></tr></thead><tbody> <tr><td><code>encrypt</code></td><td>bool</td><td><code>true</code> 时构建期加密正文</td></tr> </tbody></table> <p>站点级开关与密钥在 <code>zola.toml</code> → <code>[extra.encryption]</code>，<strong>不要</strong>写在单篇文章里。</p> <hr /> <h3 id="4-5-kan-ban-zhuan-yong-extra-content-kanban-md">4.5 看板专用 <code>[extra]</code>（<code>content/kanban/*.md</code>）</h3> <table><thead><tr><th>字段</th><th>类型</th><th>说明</th></tr></thead><tbody> <tr><td><code>week_start</code></td><td>string</td><td>周一开始 <code>YYYY-MM-DD</code></td></tr> <tr><td><code>week_end</code></td><td>string</td><td>周日结束 <code>YYYY-MM-DD</code></td></tr> <tr><td><code>core_tasks</code></td><td>string</td><td>列表页 / 明细页核心任务一行摘要</td></tr> <tr><td><code>importance</code></td><td>int</td><td>1–5 重要等级（列表五星）</td></tr> <tr><td><code>stats</code></td><td>table</td><td><code>{ total, done, todo, doing, progress_pct }</code> 预计算进度</td></tr> </tbody></table> <hr /> <h3 id="4-6-design-ye-zhuan-yong-extra-content-design-index-md">4.6 Design 页专用 <code>[extra]</code>（<code>content/design/index.md</code>）</h3> <table><thead><tr><th>字段</th><th>类型</th><th>说明</th></tr></thead><tbody> <tr><td><code>cli</code></td><td>array of tables</td><td><code>{ name, icon, repo, summary }</code></td></tr> <tr><td><code>plugins</code></td><td>array of tables</td><td>同上</td></tr> <tr><td><code>apps</code></td><td>array of tables</td><td><code>{ name, slug, icon, summary, description }</code></td></tr> </tbody></table> <p>子应用页：<code>content/design/apps/&lt;slug&gt;/index.md</code> 使用 <code>template = "design_app.html"</code>。</p> <hr /> <h3 id="4-7-shou-ye-zhuan-yong-extra-content-index-md">4.7 首页专用 <code>[extra]</code>（<code>content/_index.md</code>）</h3> <table><thead><tr><th>字段</th><th>类型</th><th>子键</th><th>说明</th></tr></thead><tbody> <tr><td><code>graphics</code></td><td>array</td><td><code>name</code>, <code>text</code>, <code>url?</code></td><td>顶部图形徽章</td></tr> <tr><td><code>badges</code></td><td>array</td><td><code>name</code>, <code>url?</code></td><td>88×31 风格徽章 GIF</td></tr> <tr><td><code>contacts</code></td><td>array</td><td><code>name</code>, <code>url</code>, <code>favorite?</code></td><td>联系方式</td></tr> <tr><td><code>socials</code></td><td>array</td><td>同上</td><td>社交网络</td></tr> <tr><td><code>forges</code></td><td>array</td><td>同上</td><td>代码托管 / 部署链接</td></tr> </tbody></table> <hr /> <h3 id="4-8-nanolog-dan-pian">4.8 Nanolog 单篇</h3> <p>可为空 front matter：</p> <pre class="giallo z-code"><code data-lang="toml"><span class="giallo-l"><span class="z-invalid">+++</span></span> <span class="giallo-l"><span class="z-invalid">+++</span></span></code></pre> <p>正文直接写 Markdown；日期由 <strong>文件名</strong> <code>YYYY-MM-DDTHH:MM:SSZ.md</code> 决定。</p> <hr /> <h3 id="4-9-wan-zheng-wen-zhang-shi-li-han-chang-yong-zi-duan">4.9 完整文章示例（含常用字段）</h3> <pre class="giallo z-code"><code data-lang="toml"><span class="giallo-l"><span class="z-invalid">+++</span></span> <span class="giallo-l"><span class="z-variable z-other">title</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">文章标题</span><span class="z-punctuation">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other">description</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">摘要，用于 SEO 与列表</span><span class="z-punctuation">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other">date</span><span class="z-punctuation"> =</span><span class="z-constant z-other"> 2026-06-24</span></span> <span class="giallo-l"><span class="z-variable z-other">updated</span><span class="z-punctuation"> =</span><span class="z-constant z-other"> 2026-06-24</span></span> <span class="giallo-l"><span class="z-variable z-other">draft</span><span class="z-punctuation"> =</span><span class="z-constant z-language"> false</span></span> <span class="giallo-l"><span class="z-punctuation">[</span><span class="z-entity z-name z-section">taxonomies</span><span class="z-punctuation">]</span></span> <span class="giallo-l"><span class="z-variable z-other">tags</span><span class="z-punctuation"> =</span><span class="z-punctuation"> [</span><span class="z-punctuation">&quot;</span><span class="z-string">Zola</span><span class="z-punctuation">&quot;</span><span class="z-punctuation">,</span><span class="z-punctuation"> &quot;</span><span class="z-string">CXX</span><span class="z-punctuation">&quot;</span><span class="z-punctuation">]</span></span> <span class="giallo-l"><span class="z-variable z-other">categories</span><span class="z-punctuation"> =</span><span class="z-punctuation"> [</span><span class="z-punctuation">&quot;</span><span class="z-string">Featured</span><span class="z-punctuation">&quot;</span><span class="z-punctuation">]</span></span> <span class="giallo-l"><span class="z-punctuation">[</span><span class="z-entity z-name z-section">extra</span><span class="z-punctuation">]</span></span> <span class="giallo-l"><span class="z-variable z-other">accent_color</span><span class="z-punctuation"> =</span><span class="z-punctuation"> [</span><span class="z-punctuation">&quot;</span><span class="z-string">hsl(254 44% 55%)</span><span class="z-punctuation">&quot;</span><span class="z-punctuation">,</span><span class="z-punctuation"> &quot;</span><span class="z-string">hsl(290 20% 71%)</span><span class="z-punctuation">&quot;</span><span class="z-punctuation">]</span></span> <span class="giallo-l"><span class="z-variable z-other">banner</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">cover.webp</span><span class="z-punctuation">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other">no_header</span><span class="z-punctuation"> =</span><span class="z-constant z-language"> false</span></span> <span class="giallo-l"><span class="z-variable z-other">copy_button</span><span class="z-punctuation"> =</span><span class="z-constant z-language"> true</span></span> <span class="giallo-l"><span class="z-punctuation">[</span><span class="z-entity z-name z-section">extra</span><span class="z-source">.</span><span class="z-entity z-name z-section">encryption</span><span class="z-punctuation">]</span></span> <span class="giallo-l"><span class="z-variable z-other">encrypt</span><span class="z-punctuation"> =</span><span class="z-constant z-language"> false</span></span> <span class="giallo-l"><span class="z-punctuation">[</span><span class="z-entity z-name z-section">extra</span><span class="z-source">.</span><span class="z-entity z-name z-section">fediverse</span><span class="z-punctuation">]</span></span> <span class="giallo-l"><span class="z-variable z-other">host</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">vmst.io</span><span class="z-punctuation">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other">user</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">username</span><span class="z-punctuation">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other">id</span><span class="z-punctuation"> =</span><span class="z-punctuation"> &quot;</span><span class="z-string">113295812044964246</span><span class="z-punctuation">&quot;</span></span> <span class="giallo-l"><span class="z-invalid">+++</span></span></code></pre> <hr /> <h2 id="wu-zola-toml-zhan-dian-ji-pei-zhi-fei-dan-pian-front-matter">五、<code>zola.toml</code> 站点级配置（非单篇 front matter）</h2> <p>访客了解全站行为时可查阅：</p> <table><thead><tr><th>段</th><th>关键字段</th><th>说明</th></tr></thead><tbody> <tr><td><code>[extra.analytics]</code></td><td><code>service</code></td><td><strong><code>goatcounter</code></strong> · <strong><code>umami</code></strong> · <strong><code>plausible</code></strong></td></tr> <tr><td></td><td><code>id</code></td><td>各平台追踪 ID</td></tr> <tr><td></td><td><code>self_hosted_url</code></td><td>自托管根 URL；<strong>Umami Cloud 留空</strong></td></tr> <tr><td></td><td><code>exclude_hash</code> / <code>exclude_search</code> / <code>do_not_track</code></td><td>Umami 选项</td></tr> <tr><td><code>[extra.encryption]</code></td><td><code>enabled</code>, <code>key</code>, <code>algorithm</code></td><td>全站加密开关（<code>AES-GCM</code>）</td></tr> <tr><td></td><td><code>admin_ttl_secs</code></td><td>管理员特权秒数</td></tr> <tr><td></td><td><code>visitor_refresh_min</code> / <code>max</code></td><td>访客随机解密刷新次数区间</td></tr> <tr><td><code>[extra.csp]</code></td><td><code>directive</code> + <code>domains</code></td><td>CSP 白名单扩展</td></tr> <tr><td><code>[extra.nav]</code></td><td><code>links</code></td><td>侧栏导航树</td></tr> <tr><td><code>[extra.categories]</code></td><td><code>name</code>, <code>color</code>, <code>icon</code></td><td>分类元数据</td></tr> <tr><td><code>[extra]</code></td><td><code>scripts</code>, <code>source_url</code>, <code>replog_url</code></td><td>全站脚本与编辑链接</td></tr> </tbody></table> <hr /> <h2 id="liu-markdown-yu-shortcode-zheng-wen-nei">六、Markdown 与 Shortcode（正文内）</h2> <p>正文除标准 Markdown 外，常用扩展包括：</p> <table><thead><tr><th>能力</th><th>写法</th></tr></thead><tbody> <tr><td>站内链接</td><td><code>[文字](@/03Share_blog/xxx/index.md)</code></td></tr> <tr><td>GitHub Alerts</td><td><code>&gt; [!NOTE]</code> / <code>WARNING</code> / <code>TIP</code></td></tr> <tr><td>图片 URL 样式</td><td><code></code></td></tr> <tr><td>Shortcode</td><td><code>{%% youtube(id="…") %%}</code>、<code>{%% crt() %%}…{%% end %%}</code> 等</td></tr> </tbody></table> <p>本站 <code>templates/shortcodes/</code> 额外提供：<code>badges</code> · <code>polaroid</code> · <code>window</code> · <code>masonry</code> · <code>todo</code> · <code>now_playing</code> · <code>online</code> · <code>games</code> · <code>age</code> · <code>icons</code> · <code>beeper</code>。</p> <hr /> <h2 id="qi-can-kao-lian-jie">七、参考链接</h2> <ul> <li><a class="external" rel="external" href="https://www.getzola.org/documentation/">Zola 官方文档</a></li> <li><a class="external" rel="external" href="https://ametrine.daudix.one">Ametrine 主题</a></li> <li><a class="external" rel="external" href="https://github.com/daudix/daudix.one">daudix.one 参考站</a></li> <li>本站模板速查：<a href="https://suchaharcan.github.io/03Share_blog/zola-template-markdown-guide/">@/03Share_blog/2026-06-22-zola-template-markdown-guide/index.md</a></li> <li>本站 v1.0 迭代记录：<a href="https://suchaharcan.github.io/nanolog/2026-06-24t04-00-00z/">@/nanolog/2026-06-24T04:00:00Z.md</a></li> </ul> <hr /> <p><em>v1.0 正式版：在「毛坯房但够用」的基础上，补齐统计、加密、看板与文档化；后续版本将在此基础上迭代，而不推翻目录结构。</em></p>