Aonote 青笺

2026-05-20T00:00:00Z

Aonote 青笺

Aonote 青笺 是一个用 Python 编写的 no-JS 静态博客生成器。它把 markdown/ 里的文章转成可直接部署的 HTML/CSS 页面：不依赖前端框架，也不要求浏览器执行 JavaScript。

本站 aonote.vercel.app 同时承担 项目官网 与 在线演示——你正在阅读的页面，就是用它自己构建出来的。

为什么做它

内容站应该是文档，不是 Web App：阅读、订阅、搜索索引不应绑定客户端运行时。
构建期完成重活：代码高亮、数学公式（MathML）、目录与 SEO 元信息在构建时生成。
默认可检查：check_site.py 在构建后检查链接、no-JS、无障碍与订阅源，减少上线后的隐性问题。

快速开始

git clone https://github.com/Runsli/Aonote.git
cd Aonote
pip install -r requirements.txt

编辑 config.py 中的 BASE_URL、BLOG_TITLE、BLOG_AUTHOR，替换 markdown/ 里的欢迎文与关于页，然后：

python autobuild.py
cd _site && python -m http.server 8000

更完整的步骤见快速开始。

核心能力

首页、文章、归档、标签、关于页与真实 404。
Markdown 扩展：代码高亮、目录、表格、脚注、任务列表、提示块、数学公式等。
RSS、Atom、Sitemap、Open Graph；结构化数据使用 Microdata，无 JSON-LD <script>。
浅色/暗色模式、移动端导航、键盘焦点与 prefers-reduced-motion。
增量构建与构建后健康检查。

链接

源码与 Issue：github.com/Runsli/Aonote
项目生态（Aonote / Astro 主题 / 个人站）：doc-ecosystem
Astro 主题（可选 JS）：astro-theme-aonote · 在线演示
作者：Runsli 的小站
关于本项目：关于页
更新日志：changelog
Markdown 渲染预览：Markdown 排版示例

命名

Aonote 保留 note（笔记）的含义；中文名青笺强调纸页与安静书写。少一点运行时，多一点内容本身。

若你 Fork 本仓库做自己的博客，请阅读仓库 README 中的「Fork 后定制」一节。

项目生态

2026-05-20T00:00:00Z

项目生态

Aonote 青笺 不是孤立仓库：它与同系列的 Astro 主题、作者个人站一起构成一套「同款阅读体验、不同技术约束」的选择。本文是完整版说明；其它仓库 README 与 Astro 主题文档会链到此处，避免多处维护同一张大表。

三个入口分别是什么

Aonote 系列三个入口
入口	链接	角色
Aonote 青笺（本仓库）	github.com/Runsli/Aonote · aonote.vercel.app	Python 构建的 no-JS 静态博客生成器；本页所在项目官网
astro-theme-aonote	github.com/runsli/astro-theme-aonote · astro-theme-aonote.vercel.app	同款版式与内容模型的 Astro 5 移植；可按需加客户端 JS
Runsli 的小站	www.runsli.com	作者个人博客（note / jotting），不是 Aonote 产品文档站

三者独立部署、独立维护，但在视觉与 Markdown 能力上尽量对齐，方便你在不同场景切换。

如何选择

需要零浏览器 JS、Python 构建、check_site 质检、申 nojs / 体积类 Club？
  → Aonote 青笺（本仓库）

需要 Astro 生态、组件化、客户端增强或 npm 模板一键建站？
  → astro-theme-aonote

想了解作者、阅读建站随笔（与产品文档无关的个人内容）？
  → runsli.com

不必二选一：有人用 Aonote 做生产博客，用 Astro 主题做实验站；也有人从 Python 版迁到 Astro 版以扩展交互。

技术对照

Aonote 与 Astro 主题技术对照
维度	Aonote 青笺	astro-theme-aonote
运行时	构建期 Python；页面无必需 JS	Node 构建；页面可按需含 JS
内容目录	`markdown/`	`src/content/posts/`
站点配置	`config.py`	`src/site.config.ts`
布局模板	`templates/base.html`	`src/layouts/BaseLayout.astro`
样式	`assets/style.css`	`src/styles/aonote.css`
界面文案	`i18n.py`	`src/i18n.ts`
构建产物	`_site/`	`dist/`
构建命令	`python autobuild.py`	`npm run build`
特色	`check_site.py`、增量构建、no-JS 约束	Astro 集成、Shiki、模板 `npm create astro`

更细的 upstream mapping 见 astro-theme-aonote README。

与 Runsli 小站的关系

runsli.com 使用 Thought Lite 系 Astro 主题（与 Aonote 产品线不同），主要发个人笔记与建站日志。其中与 Aonote 相关的文章会链回本官网与 GitHub，例如：

Aonote 近期更新（建站日志）
项目生态说明（个人站短文）（链回本页）

产品选型、配置对照、Fork 说明请以本官网文档为准；个人站文章偏经历与回顾，可能滞后于仓库最新 commit。

许可与反馈

Aonote 与 astro-theme-aonote 源码许可见各自仓库 LICENSE（均为 MIT）。
问题与 PR：各仓库 GitHub Issues；Aonote 也可在关于页查看作者联系方式。

更新日志

2026-05-19T00:00:00Z

更新日志

本页记录 Aonote 青笺 官网与生成器的重要变更。完整提交历史见 GitHub Commits。

未发布

官网

新增项目生态文档；about、README 与 Astro 主题、runsli.com 互链。
首页支持通过 INDEX_PAGE_TITLE / INDEX_PAGE_SUBTITLE 配置浏览器标签与分享标题（不在正文显示）。
页脚增加 GitHub 仓库链接。
新增本站更新日志页面。

2026-05-20

官网

将 aonote.vercel.app 调整为项目官方网站与在线演示。
新增项目文档：《快速开始》《为什么坚持 no-JS》。
README 补充 Fork 后定制说明；作者信息更新为 Runsli。

2026-05（早期）

文档与维护

移除 changelog 式源码注释；README 按中英文拆分。
优化归档页链接间距；完善模板示例文案。

项目

站点更名为 Aonote 青笺。
Markdown 示例按主题拆分（后整合为官网 + 单篇排版预览）。

2026-04 及更早

功能

构建健康检查按类别输出报告（A11Y、SEO、Links 等）。
任务列表、脚注、表格标题、diff 行等无障碍增强。
键盘导航与焦点顺序检查；锚点滚动优化。
no-JS 约束、Microdata、RSS/Atom、增量构建等核心能力陆续完善。

版本号尚未单独打 Tag；关注 GitHub Releases 获取后续正式版本。

快速开始

2026-05-18T00:00:00Z

快速开始

本文介绍如何把 Aonote 跑起来，并部署到你自己的域名。若你只想浏览功能，可直接看首页与 Markdown 排版示例。

环境要求

Python 3.7+
pip
Git（可选，用于克隆与构建时间戳）

1. 获取代码

git clone https://github.com/Runsli/Aonote.git
cd Aonote
pip install -r requirements.txt

也可在 GitHub 上使用 Use this template 创建你自己的仓库。

2. 配置站点

编辑 config.py，至少修改以下项：

BASE_URL = "https://your-domain.example"
BLOG_TITLE = "你的站点标题"
BLOG_DESCRIPTION = "你的站点描述"
BLOG_AUTHOR = "你的名字"
SITE_LANGUAGE = "zh-CN"  # 或 "en"

若部署在 GitHub Pages 子路径（如 username.github.io/repo-name/），还需设置 REPO_SUBPATH。

3. 准备内容

在 markdown/ 中写作。Front Matter 示例：

---
title: 我的第一篇文章
date: 2026-05-20
summary: 显示在首页与 RSS 中的摘要。
tags: [blog]
---

正文从这里开始。

特殊文件：

about.md：关于页（建议 hidden: true）。
404.md：404 页面内容。

4. 构建与预览

python autobuild.py
cd _site
python -m http.server 8000

浏览器打开 http://localhost:8000。构建通过后会更新 _site/，并在健康检查通过后写入增量构建清单。

单独运行检查：

python check_site.py

5. 部署

将 _site/ 目录发布到任意静态托管即可，例如：

Vercel / Netlify：连接仓库，构建命令 python autobuild.py，发布目录 _site（仓库已含 vercel.json / netlify.toml）。
GitHub Pages：将 _site 内容推送到 gh-pages 分支，或使用 Actions 构建。

部署后确认 BASE_URL 与线上域名一致，否则 canonical、RSS 与 Sitemap 中的链接会不正确。

Fork 官方站内容时

若你 Fork 的是包含本官网内容的仓库，请按关于页 · Fork 做自己的站替换欢迎文、关于页，并删除不需要的 doc-*.md 项目文档。

下一步

为什么坚持 no-JS

2026-05-17T00:00:00Z

为什么坚持 no-JS

Aonote 的目标用户写的是文章、笔记与文档，不是需要复杂客户端状态的应用。因此默认输出不包含可执行的浏览器 JavaScript。

页面是文档

博客与知识库的核心体验是：阅读、跳转、订阅、被搜索引擎索引。这些都不应依赖：

客户端路由与 hydration
运行时 Markdown 或数学渲染
用脚本补上的导航、目录或主题切换

Aonote 把代码高亮、公式（MathML）、目录锚点、Open Graph 等放在 构建阶段 完成，部署后只有 HTML 与 CSS。

结构化数据不用 `<script>`

许多站点用 JSON-LD 的 <script type="application/ld+json"> 做结构化数据。Aonote 改用 Microdata 写在 HTML 元素上，避免在页面里出现 script 标签，也更贴近 nojs.club 所倡导的精神。

交互用 HTML/CSS 原生能力

这些能力不依赖脚本：

移动端导航（:target / checkbox hack 等纯 CSS 方案）
<details> / <summary> 折叠
返回顶部（锚点链接）
浅色/暗色模式（prefers-color-scheme 与 CSS 变量）

可验证

check_site.py 会检查：

是否存在不应出现的可执行脚本
链接、锚点、图片与 Feeds 是否有效
基础无障碍与 SEO 细节

构建失败时不会更新增量清单，避免「坏构建」被当成已发布状态。

不是反对一切 JS

no-JS 指的是 你的读者不必为你的内容站加载脚本。构建工具本身用 Python，与浏览器无关。若你将来需要个别页面的例外，应在明确约束下审慎添加，并仍通过健康检查把关。

若仍需要 JavaScript

no-JS 是本仓库（Python 版）的默认约束，不是否定一切前端能力。若你的站点需要 Astro 组件、客户端增强或更复杂的交互，可使用同系列的 astro-theme-aonote。详见项目生态。

Markdown 排版示例

2026-01-10T00:00:00Z

本站保留此页作为 Markdown 渲染预览。Fork 后若不需要可删除本文件。

这个页面聚焦 Markdown 基础排版能力：标题、段落、行内文本、链接、数学公式、列表、引用、脚注和混排文本。

# 一级标题
## 二级标题
### 三级标题
#### 四级标题
##### 五级标题
###### 六级标题

段落与换行

这是一个段落。

这是另一个段落。

这是一句话不过我要在这里
换行

Tip

上方的代码中 这里 后面有两个空格。

这是一个段落。

这是另一个段落。

这是一句话不过我要在这里  
换行

行内文本

这句话里拥有加粗、倾斜、删除、行内代码、重点标记和快捷键 ⌘ + K。

经典 Emoji: 😉 😢 😆 😋

简写 Emoji: 😎 🙂 😘 ☹️ 🙂 ☹️ 😉

这句话里拥有**加粗**、*倾斜*、~~删除~~、`行内代码`、<mark>重点标记</mark> 和快捷键 <kbd>⌘</kbd> + <kbd>K</kbd>。

经典 Emoji: :wink: :cry: :laughing: :yum:

简写 Emoji: 8-) :) :\* :( :-) :-( ;)

链接

[根目录访问主页](/)
[站内文章示例](/posts/welcome-to-aonote/)
[根目录访问关于](/about)
[归档页面](/archive/)

分割线

---

数学公式

行内公式示例： $E = m c^{2}$ 。

块级公式示例：

\int_{0}^{1} x^{2} d x = \frac{1}{3}

行内公式示例：$E = mc^2$。

块级公式示例：

$$
\int_0^1 x^2 dx = \frac{1}{3}
$$

列表

无序列表

无序列表项
无序列表项
列表中的列表项
- 更多的列表项
- 更多的列表项
- 更多的列表项
列表中的长列表项，这个列表项很长。

而且由很多个段落构成。

甚至最后一个段落还包含了链接。 - 无序列表项

- 无序列表项
- 无序列表项
  - 列表中的列表项
    - 更多的列表项
  - 列表中的长列表项，这个列表项很长。

    而且由很多个段落构成。

    甚至最后一个段落还包含了[链接](#链接)。

有序列表

有序列表第一项
有序列表第二项
第二项的需要换行
再次换行
有序列表第三项

Tip

上方的代码中 换行 后面也有两个空格。

1. 有序列表第一项
1. 有序列表第二项  
   第二项的需要换行  
   再次换行
1. 有序列表第三项

任务列表

已完成: 已完成的任务
未完成: 未完成的任务
未完成: 静态页面中复选框不可点击

- [x] 已完成的任务
- [ ] 未完成的任务
- [ ] 静态页面中复选框不可点击

定义列表

静态站点: 只由 HTML、CSS 和静态资源组成，不依赖客户端 JavaScript 运行时。
RSS: 一种用于订阅网站更新的格式，可以被阅读器聚合。

静态站点
: 只由 HTML、CSS 和静态资源组成，不依赖客户端 JavaScript 运行时。

RSS
: 一种用于订阅网站更新的格式，可以被阅读器聚合。

引用

引用也可以连用

可以添加额外的大于号制造更深的引用

> 引用也可以连用
>
> > 可以添加额外的大于号制造更深的引用

带来源的引用

简洁并不意味着缺少结构，而是每个结构都有清晰的用途。

Aonote 阅读样式测试

> 简洁并不意味着缺少结构，而是每个结构都有清晰的用途。
>
> <cite>Aonote 阅读样式测试</cite>

脚注

这里有一个脚注引用。¹

这里有一个脚注引用。[^markdown-footnote]

[^markdown-footnote]: 这是脚注内容，可以放补充说明、来源或延伸阅读。

混排段落

这是一段中文、English、数字 123、URL https://example.com/path/to/resource 和行内代码 inline_code() 混排的测试文本，用来观察行高、换行和标点间距。

这是一段中文、English、数字 123、URL https://example.com/path/to/resource 和行内代码 `inline_code()` 混排的测试文本，用来观察行高、换行和标点间距。

这是脚注内容，可以放补充说明、来源或延伸阅读。 ↩