网站版本 1.0 正式版

本文面向 访客与自建站参考者，说明本站 v1.0 正式版 的目录结构、设计架构，以及撰写博客时在 +++（TOML front matter）中可用的全部字段。技术栈为 Zola + Ametrine 主题；站点级定制在仓库根目录，不修改 themes/。

更细的模板 / Markdown 写法见 Zola 模板开发要点与 Markdown 语法速查；本轮功能迭代见 Nanolog 更新总结。

一、版本 1.0 能力总览

构建命令：

./build-site.sh    # 加密 → zola build → 搜索索引补丁
zola serve         # 本地预览（加密解密需 localhost 或 HTTPS）

二、源码目录树

以下为 访客可见逻辑相关的仓库结构（省略 public/ 构建产物与主题内 demo 细节）：

00BlogZola/
├── zola.toml                 # 全站配置（导航、CSP、统计、加密、分类…）
├── build-site.sh             # 正式构建入口
├── scripts/
│   ├── encrypt-content.mjs   # 构建前：加密标记文章 → static/encryption/pages/
│   ├── encryption-lib.mjs    # 加密路径 / front matter 解析共用库
│   └── patch-search-index.mjs
├── content/                  # 所有页面内容（Markdown）
│   ├── _index.md             # 首页
│   ├── 00Read_blog_Math/     # 在读 · 数学
│   ├── 00Read_blog_English/
│   ├── 01Write_blog_*/       # 写作各子专栏（CMake / CXX / 论文…）
│   ├── 02Engineer_blog_Debug/
│   ├── 03Share_blog/
│   ├── kanban/               # 周计划（列表 + 每周 .md）
│   ├── nanolog/              # 开发日志（单文件即一篇）
│   ├── design/               # Design 页 + apps/* 子应用
│   ├── basb/                 # 树状笔记
│   └── archive/
├── templates/                # 覆盖主题的 Tera 模板（优先级高于 theme）
│   ├── base.html             # 全站：加密配置 + admin.js 注入
│   ├── article.html          # 文章：普通 / 加密分支
│   ├── partials/
│   │   ├── encrypted_article.html
│   │   ├── encryption_config.html
│   │   └── heatmap_component.html
│   ├── kanban.html / kanban_list.html
│   ├── nanolog.html / nanolog_list.html
│   ├── design.html / design_app.html
│   ├── archive.html / basb.html
│   ├── shortcodes/           # Markdown 短代码
│   └── macros/encryption.html
├── static/                   # 原样拷贝到站点根 URL
│   ├── analytic/umami.js
│   ├── encryption/           # 加解密运行时（admin / visitor / crypto / article）
│   ├── js/                   # kanban、nanolog、热力图、滚动条…
│   └── kanban/ …
├── sass/                     # 站点 SCSS（编译为 CSS）
│   ├── kanban/ nanolog/ design/ home/ …
└── themes/ametrine/          # 上游主题（勿改；用 templates/ 扩展）

模板覆盖原则： templates/foo.html 与主题同名时 完全替换 主题文件；常用模式为 {%% extends "ametrine/templates/....html" %%} + {%% block %%} 扩展。

三、设计架构

3.1 分层示意

flowchart TB
  subgraph build [构建期]
    MD[content/*.md]
    ENC[scripts/encrypt-content.mjs]
    ZOLA[zola build]
    MD --> ENC
    ENC -->|密文 JSON| STATIC_ENC[static/encryption/pages/]
    MD --> ZOLA
    STATIC_ENC --> ZOLA
    ZOLA --> PUBLIC[public/ 静态站点]
  end

  subgraph runtime [浏览器运行时]
    PUBLIC --> HTML[HTML + textarea 配置]
    HTML --> ADMIN[admin.js 特权模式]
    HTML --> VISITOR[visitor.js 随机解密]
    HTML --> ARTICLE[article.js 解密渲染]
    ADMIN --> ARTICLE
    VISITOR --> ARTICLE
    HTML --> UMAMI[umami.js 统计]
    HTML --> KANBAN[kanban-board.js]
    HTML --> NANO[nanolog.js]
  end

  subgraph theme [Ametrine 主题层]
    BASE[base.html 骨架]
    SIDE[sidebar 导航]
    HEAD[head.html CSP/脚本]
  end

  HTML --> BASE
  BASE --> SIDE
  BASE --> HEAD

3.2 内容 → 模板绑定

3.3 安全与特权模型

stateDiagram-v2
  [*] --> Visitor: 默认
  Visitor --> Admin: 连点左上角图标 6 次
  Admin --> Visitor: admin_ttl_secs 到期
  Visitor --> LuckyDecrypt: 同文刷新 9~20 次 session
  LuckyDecrypt --> Visitor: 关闭标签页 / 新 session
  Admin --> Decrypted: 全部加密文可读
  LuckyDecrypt --> Decrypted: 单篇可读

• 访客： 加密文默认上锁；看板固定「只读（已过期）」样式；隐藏 Edit Post / ReDeplog。
• 管理员： html.encryption-admin-active 时显示编辑按钮、可解密、看板在有效期内可解锁。
• 配置： zola.toml → [extra.encryption]（见下文站点级表）。

四、Front matter（+++）字段速查

Zola 使用 TOML 作为 front matter。以下汇总 本站实际可用 的字段；未列出的键也可写入 [extra]，但需自行在模板中读取才会生效。

4.1 顶层通用字段（Page / Section 均可）

Section _index.md 示例：

+++
title = "效率-工作流"
sort_by = "date"
template = "article_list.html"
page_template = "article.html"
paginate_by = 10
generate_feeds = true
[extra]
no_header = true
scripts = ["analytic/umami.js"]
+++

4.2 [taxonomies] 分类法

本站 zola.toml 启用：

taxonomies = [
  { name = "tags", feed = true, paginate_by = 10 },
  { name = "categories", feed = true },
]

categories 可选枚举（zola.toml → [[extra.categories]]）：

4.3 [extra] — 页面 / 专栏扩展（Ametrine + 本站）

继承规则：页面 page.extra.* 优先，否则回退 section.extra.*，再回退 config.extra.*。

布局与展示

accent_color 枚举与格式（主题文档）：

预设名可选：red · orange · yellow · green · blue · purple

元数据与社交卡片 [extra.meta]

声明块（文章顶部提示）

资源加载

常用 scripts 值：

功能开关

Fediverse 评论 [extra.fediverse]

侧栏媒体 [extra.music] / [extra.weather]

music — 数组，每项：

weather — 表：

4.4 [extra.encryption] — 本站加密（单篇文章）

站点级开关与密钥在 zola.toml → [extra.encryption]，不要写在单篇文章里。

4.5 看板专用 [extra]（content/kanban/*.md）

4.6 Design 页专用 [extra]（content/design/index.md）

子应用页：content/design/apps/<slug>/index.md 使用 template = "design_app.html"。

4.7 首页专用 [extra]（content/_index.md）

4.8 Nanolog 单篇

可为空 front matter：

+++
+++

正文直接写 Markdown；日期由 文件名 YYYY-MM-DDTHH:MM:SSZ.md 决定。

4.9 完整文章示例（含常用字段）

+++
title = "文章标题"
description = "摘要，用于 SEO 与列表"
date = 2026-06-24
updated = 2026-06-24
draft = false
[taxonomies]
tags = ["Zola", "CXX"]
categories = ["Featured"]
[extra]
accent_color = ["hsl(254 44% 55%)", "hsl(290 20% 71%)"]
banner = "cover.webp"
no_header = false
copy_button = true
[extra.encryption]
encrypt = false
[extra.fediverse]
host = "vmst.io"
user = "username"
id = "113295812044964246"
+++

五、zola.toml 站点级配置（非单篇 front matter）

访客了解全站行为时可查阅：

六、Markdown 与 Shortcode（正文内）

正文除标准 Markdown 外，常用扩展包括：

本站 templates/shortcodes/ 额外提供：badges · polaroid · window · masonry · todo · now_playing · online · games · age · icons · beeper。

七、参考链接

• Zola 官方文档
• Ametrine 主题
• daudix.one 参考站
• 本站模板速查：@/03Share_blog/2026-06-22-zola-template-markdown-guide/index.md
• 本站 v1.0 迭代记录：@/nanolog/2026-06-24T04:00:00Z.md

v1.0 正式版：在「毛坯房但够用」的基础上，补齐统计、加密、看板与文档化；后续版本将在此基础上迭代，而不推翻目录结构。