TerseBlog

A modern static blog built with Astro. Markdown/Markdoc content, LaTeX math, full-text search, dark mode, RSS, multi-language support, Keystatic admin UI, and a settings panel for personalized reading.

🔗 Live Demo: blog.qwara.top

---

中文版本

Features

• 📝 Markdown / Markdoc — Write posts in Markdown or Markdoc with Frontmatter
• 📐 LaTeX Math — KaTeX integration for inline and display math
• 🌐 Multi-language — UI and content i18n (en / zh-CN / zh-TW / ja), toggleable
• 🔍 Full-text Search — Build-time search index, client-side Fuse.js instant search (lazy-loaded)
• 🌓 Dark Mode — Light / Dark / System three modes
• ⚙️ Settings Panel — Font size, content width, font family, TOC visibility, language
• 📑 Table of Contents — Sidebar TOC with scroll-spy highlighting
• ⏱ Reading Time — Auto-estimate for mixed CJK + English content
• 🏷 Tag System — Tag categorization and tag cloud with pagination
• 📡 RSS Feed — Per-locale auto-generated RSS
• 🗺 Sitemap — Auto-generated sitemap
• 📱 Responsive — Desktop and mobile friendly
• 🔄 View Transitions — Built-in page transition animations
• 🛠 Keystatic Admin — Local admin UI for content management

Quick Start

# 1. Clone
git clone https://github.com/Qwara-chan/TerseBlog.git
cd TerseBlog

# 2. Install
npm install

# 3. Dev server
npm run dev

# 4. Build
npm run build

# 5. Preview build
npm run preview

# 6. Type check
npm run check

# 7. Run tests
npm test

Multi-language (i18n)

i18n is controlled via src/config/settings.json:

{
  "i18nEnabled": true,
  "defaultLocale": "zh-CN"
}

Toggle at any time:

npm run i18n          # View current status
npm run i18n:on       # Enable i18n
npm run i18n:off      # Disable i18n (single-locale mode)

When enabled, 4 locales are served under URL prefixes: /en/ /zh-CN/ /zh-TW/ /ja/. The root path / redirects to /{defaultLocale}/.

When disabled, the build emits a single-locale site: no locale-prefixed routes, no per-locale RSS/search-index, no i18n middleware.

The toggle script physically moves the inactive page tree out of src/pages/ into src/pages/_i18n_disabled/, so Astro only builds the active tree.

Post translations live in src/posts/<locale>/<slug>/index.mdoc. If a translation is missing for a given locale, it falls back to the default locale (zh-CN).

UI text (search, settings, pagination, etc.) is translated via dictionary files in src/i18n/dictionaries/. The runtime is loaded only when a locale change happens (lazy import('@/i18n/runtime')).

See docs/configuration.md for details.

Keystatic Admin

The project includes Keystatic for local content management. Build without it in CI:

npm run build          # SKIP_KEYSTATIC=true by default

To enable the admin UI, build without the skip flag:

SKIP_KEYSTATIC=false npm run build

Admin config lives in keystatic.config.ts — defines per-locale post collections and site settings singleton.

Project Structure

TerseBlog/
├── astro.config.ts
├── keystatic.config.ts        # Keystatic admin configuration
├── tsconfig.json
├── package.json
├── vitest.config.ts           # Test configuration
├── src/
│   ├── config/
│   │   ├── settings.json      # i18n source of truth (runtime)
│   │   └── settings.ts        # settings loader
│   ├── config.ts              # Site configuration
│   ├── i18n/
│   │   ├── config.ts          # Locale resolver, path helpers
│   │   ├── load.ts            # Server-side dictionary loader (getDict)
│   │   ├── runtime.ts         # Client-side i18n runtime (lazy)
│   │   ├── lookup.ts          # Shared getNested/format helpers
│   │   ├── i18n-client.ts     # Client-side locale resolution
│   │   └── dictionaries/      # UI text translations
│   │       ├── en.json
│   │       ├── zh-CN.json
│   │       ├── zh-TW.json
│   │       └── ja.json
│   ├── layouts/
│   │   └── BaseLayout.astro   # Base layout
│   ├── components/
│   │   ├── page-pages/        # Canonical page implementations
│   │   │   ├── Index.astro
│   │   │   ├── About.astro
│   │   │   ├── Archive.astro
│   │   │   ├── NotFound.astro
│   │   │   ├── Post.astro
│   │   │   ├── Tag.astro
│   │   │   └── Tags.astro
│   │   ├── Header.astro
│   │   ├── Footer.astro
│   │   ├── PostCard.astro
│   │   ├── Pagination.astro
│   │   ├── TOC.astro
│   │   ├── Search.astro
│   │   ├── SettingsPanel.astro
│   │   ├── LangSwitcher.astro
│   │   ├── BackToTop.astro
│   │   ├── SortToggle.astro
│   │   └── DiffViewer.astro
│   ├── pages/                 # Active Astro routes
│   │   ├── index.astro        # i18n redirect or flat index
│   │   ├── en/, zh-CN/, zh-TW/, ja/  # Locale-prefixed routes (i18n=on)
│   │   └── _i18n_disabled/    # Inactive tree (managed by i18n-toggle.mjs)
│   │       ├── flat/          # Flat thin wrappers (stashed when i18n=on)
│   │       └── root-index.astro
│   ├── lib/
│   │   ├── content.ts         # Content collection helpers + reading time
│   │   ├── utils.ts           # formatDate, isExternalUrl, groupPostsByYear
│   │   ├── search.ts          # SearchEngine (lazy Fuse.js)
│   │   ├── build-feed.ts      # Shared RSS / search-index builders
│   │   ├── translate.ts       # Shared withFallback() helper
│   │   ├── rehype-external-links.ts
│   │   ├── types.ts
│   │   └── client/            # Client-side scripts (extracted from inline)
│   │       ├── mobile-menu.ts
│   │       ├── motion.ts
│   │       └── search.ts
│   ├── styles/
│   │   ├── global.css
│   │   └── interactivity.css
│   ├── posts/                 # Blog posts (locale/slug/index.mdoc)
│   │   ├── en/
│   │   ├── zh-CN/
│   │   ├── zh-TW/
│   │   └── ja/
│   └── public/
│       ├── theme-init.js      # Inline theme initialization
│       ├── favicon.svg
│       └── robots.txt
├── test/                      # Vitest test suite
│   ├── utils.test.ts
│   ├── content.test.ts
│   └── i18n.test.ts
└── scripts/
    ├── i18n-toggle.mjs        # i18n on/off toggle
    ├── new-post.mjs           # Post scaffolding script
    ├── post-build-redirects.mjs
    └── serve.mjs

Page architecture

Canonical page implementations live in src/components/page-pages/<Page>.astro and accept an optional lang prop. Both the active flat route and the i18n wrapper route are thin Astro files that render the canonical. getStaticPaths stays on the route (Astro requires it there).

Deployment

Cloudflare Pages

1. Go to Pages in Cloudflare Dashboard
2. Create a project → Connect to Git
3. Configure build settings:
   • Build command: npm run build
   • Build output directory: dist
4. Save and Deploy

GitHub Pages

1. Go to Settings → Pages in your repo
2. Select GitHub Actions as the Source
3. Push to main — GitHub Actions builds and deploys automatically

A pre-configured workflow is available at .github/workflows/deploy.yml.

Keeping in Sync

If you created your repo from this template, you can pull in upstream updates at any time:

1. Go to Actions → Sync Upstream → Run workflow
2. A pull request will be created with the latest upstream changes
3. Review conflicts (if any) and merge

---

Tech Stack

Technology	Purpose
Astro 5	Static site generator
TypeScript	Type safety
KaTeX	LaTeX math rendering
Fuse.js	Fuzzy search (lazy-loaded)
rehype-katex	Markdown math
@astrojs/sitemap	Sitemap
@astrojs/rss	RSS feed
@astrojs/markdoc	Markdoc format support
Keystatic	Local admin UI
Vitest	Unit testing

License

CC BY-NC-SA 4.0

---

中文

TerseBlog

基于 Astro 构建的现代化静态博客，支持 Markdown/Markdoc、LaTeX 数学公式、全文搜索（懒加载）、暗色模式、RSS 订阅、多语言切换、Keystatic 内容管理，内置设置面板可个性化调整字体大小、内容宽度等。

🔗 示例站点: blog.qwara.top

功能特性

• 📝 Markdown / Markdoc — Markdown 或 Markdoc 编写文章，支持 Frontmatter
• 📐 LaTeX 数学公式 — KaTeX 集成，行内和展示公式
• 🌐 多语言 — 界面与文章 i18n（en / zh-CN / zh-TW / ja），可随时开关
• 🔍 全文搜索 — 构建时生成索引，Fuse.js 客户端即时搜索（懒加载）
• 🌓 暗色模式 — 亮色/暗色/跟随系统三种模式
• ⚙️ 设置面板 — 字体大小、内容宽度、字体切换、TOC 显隐、语言
• 📑 目录导航 — 侧边目录，滚动高亮
• ⏱ 阅读时长 — 中英文混合内容自动估算
• 🏷 标签系统 — 文章标签分类、标签云、分页导航
• 📡 RSS 订阅 — 每种语言独立 RSS Feed
• 📱 响应式设计 — 适配桌面和移动端
• 🔄 页面过渡动画 — 内置 View Transitions API
• 🛠 Keystatic 管理 — 本地内容管理后台
• ✅ 单元测试 — Vitest 测试套件

快速开始

# 中国大陆用户可先配置 npm 镜像
npm config set registry https://registry.npmmirror.com

# 1. 克隆
git clone https://github.com/Qwara-chan/TerseBlog.git
cd TerseBlog

# 2. 安装依赖
npm install

# 3. 启动开发服务器
npm run dev

# 4. 构建
npm run build

# 5. 预览构建结果
npm run preview

# 6. 类型检查
npm run check

# 7. 运行测试
npm test

多语言开关

通过 src/config/settings.json 控制：

{
  "i18nEnabled": true,
  "defaultLocale": "zh-CN"
}

npm run i18n          # 查看当前状态
npm run i18n:on       # 开启多语言
npm run i18n:off      # 关闭多语言（单语言模式）

开启后 4 种语言分别用 URL 前缀访问：/en/ /zh-CN/ /zh-TW/ /ja/。根路径 / 自动跳转到默认语言。

文章翻译放在 src/posts/<语种>/<slug>/index.mdoc 目录下。缺译时自动回退到默认语种（zh-CN）。

Keystatic 内容管理

项目内置 Keystatic 用于本地内容管理：

npm run build                  # SKIP_KEYSTATIC=true（CI 默认排除）
SKIP_KEYSTATIC=false npm run build   # 启用 Admin UI

配置位于 keystatic.config.ts。

部署

详见上方 Deployment 章节。

同步上游更新

如果用此模板创建了仓库，你可以随时拉取上游更新：

1. 进入 Actions → Sync Upstream → Run workflow
2. 会自动创建一个包含上游最新变更的 Pull Request
3. 审查并处理后合并即可

---

技术栈

技术	用途
Astro 5	静态站点生成器
TypeScript	类型安全
KaTeX	LaTeX 数学公式渲染
Fuse.js	模糊搜索（懒加载）
@astrojs/sitemap	站点地图
@astrojs/rss	RSS 订阅
@astrojs/markdoc	Markdoc 格式支持
Keystatic	本地管理后台
Vitest	单元测试

许可证

CC BY-NC-SA 4.0