Aonote 青笺https://aonote.vercel.app/用 Python 编写的 no-JS 静态博客生成器：Markdown 进，纯 HTML/CSS 出，无需浏览器端 JavaScript。zh-cnWed, 20 May 2026 00:00:00 +0000Aonote 青笺https://aonote.vercel.app/posts/welcome-to-aonote/Wed, 20 May 2026 00:00:00 +0000https://aonote.vercel.app/posts/welcome-to-aonote/Runsli项目用 Python 将 Markdown 生成为纯 HTML/CSS 的 no-JS 静态博客生成器。本站即官方站点与可运行演示。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。
  • 增量构建与构建后健康检查。

链接

命名

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

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

]]>项目生态https://aonote.vercel.app/posts/doc-ecosystem/Wed, 20 May 2026 00:00:00 +0000https://aonote.vercel.app/posts/doc-ecosystem/Runsli文档Aonote 青笺、astro-theme-aonote 与 Runsli 小站的关系说明，以及如何选择与互链。项目生态

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，例如：

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

许可与反馈

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

相关阅读

]]>更新日志https://aonote.vercel.app/posts/doc-changelog/Tue, 19 May 2026 00:00:00 +0000https://aonote.vercel.app/posts/doc-changelog/Runsli文档Aonote 青笺版本记录与主要变更说明。更新日志

本页记录 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 获取后续正式版本。

]]>快速开始https://aonote.vercel.app/posts/doc-quickstart/Mon, 18 May 2026 00:00:00 +0000https://aonote.vercel.app/posts/doc-quickstart/Runsli文档从克隆仓库到本地预览与部署 Aonote 站点的最短路径。快速开始

本文介绍如何把 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-JShttps://aonote.vercel.app/posts/doc-why-no-js/Sun, 17 May 2026 00:00:00 +0000https://aonote.vercel.app/posts/doc-why-no-js/Runsli文档Aonote 将页面视为文档而非应用：无客户端脚本、构建期增强与可检查性。为什么坚持 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 排版示例https://aonote.vercel.app/posts/markdown-basics/Sat, 10 Jan 2026 00:00:00 +0000https://aonote.vercel.app/posts/markdown-basics/Runsli示例Aonote 官网保留的语法预览页：标题、列表、链接、公式、脚注与中英文混排等基础排版效果。本站保留此页作为 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=mc2。

块级公式示例：

∫01x2dx=13
行内公式示例：$E = mc^2$。

块级公式示例：

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

列表

无序列表

  • 无序列表项
  • 无序列表项
  • 列表中的列表项
    • 更多的列表项
    • 更多的列表项
    • 更多的列表项

  • 列表中的长列表项，这个列表项很长。

    而且由很多个段落构成。

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

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

    而且由很多个段落构成。

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

有序列表

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

Tip

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

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

任务列表

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

定义列表

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

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

引用

引用也可以连用

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

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

带来源的引用

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

Aonote 阅读样式测试

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

脚注

这里有一个脚注引用。1

这里有一个脚注引用。[^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()` 混排的测试文本，用来观察行高、换行和标点间距。

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

]]>