TerseBlog

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

🔗 Live Demo: blog.qwara.top

---

中文版本

Features

• 📝 Markdown — Write posts in Markdown 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
• 🌓 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
• 📡 RSS Feed — Per-locale auto-generated RSS
• 🗺 Sitemap — Auto-generated sitemap
• 📱 Responsive — Desktop and mobile friendly
• 🔄 View Transitions — Built-in page transition animations

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

Multi-language (i18n)

i18n is disabled by default. You can toggle it 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 /zh-CN/.

When disabled, the build emits a single-locale site: no locale-prefixed routes, no per-locale RSS/search-index, no i18n middleware, and the dictionary JSON files are not loaded by any client bundle.

The toggle script physically moves the inactive page tree out of src/pages/ into src/pages/_i18n_disabled/ (along with thin wrappers that import the canonical page implementation in src/components/page-pages/), so Astro only builds the active tree.

Post translations live in src/posts/<locale>/. 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.

Project Structure

TerseBlog/
├── astro.config.ts
├── tsconfig.json
├── package.json
├── src/
│   ├── config.ts              # Site configuration (including i18n)
│   ├── i18n/
│   │   ├── config.ts          # Locale resolver, path helpers
│   │   ├── load.ts            # Server-side dictionary loader
│   │   ├── runtime.ts         # Client-side i18n runtime (lazy)
│   │   ├── lookup.ts          # Shared getNested/format helpers
│   │   └── 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
│   │   ├── MobileMenu.astro
│   │   ├── SortToggle.astro
│   │   └── DiffViewer.astro
│   ├── pages/                 # Active Astro routes
│   │   ├── index.astro        # Renders <IndexPage /> (flat or i18n redirect)
│   │   ├── about.astro
│   │   ├── archive.astro
│   │   ├── 404.astro
│   │   ├── posts/[...slug].astro
│   │   ├── tags/{index,[tag]}.astro
│   │   ├── rss.xml.ts
│   │   └── search-index.json.ts
│   │   _i18n_disabled/        # Inactive tree (managed by i18n-toggle.mjs)
│   │   ├── root-index.astro   # Used as the i18n-on root redirect
│   │   ├── flat/              # Flat thin wrappers (stashed when i18n=on)
│   │   ├── en/, zh-CN/, zh-TW/, ja/   # i18n thin wrappers (stashed when i18n=off)
│   ├── lib/
│   │   ├── content.ts         # Content collection helpers + reading time
│   │   ├── utils.ts           # formatDate, isExternalUrl, groupPostsByYear
│   │   ├── search.ts          # Client-side Fuse.js search engine
│   │   ├── build-feed.ts      # Shared RSS / search-index builders
│   │   ├── translate.ts       # Shared withFallback() helper
│   │   ├── rehype-external-links.ts
│   │   └── types.ts
│   ├── styles/
│   │   ├── global.css
│   │   └── interactivity.css
│   └── posts/                 # Blog posts (locale subdirectories)
│       ├── en/
│       ├── zh-CN/
│       ├── zh-TW/
│       └── ja/
└── public/                    # Static assets

Page architecture

To avoid duplicating the home/post/tag pages 5× (once for flat, once for each locale), the canonical implementation lives in src/components/page-pages/<Page>.astro and accepts an optional lang prop. Both the active flat route (e.g. src/pages/index.astro) and the i18n wrapper route (e.g. src/pages/_i18n_disabled/en/index.astro) are 5-line Astro files that render the canonical. getStaticPaths lives in the route file (Astro requires it on the route, not on a component).

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
rehype-katex	Markdown math
@astrojs/sitemap	Sitemap
@astrojs/rss	RSS feed

License

CC BY-NC-SA 4.0

---

中文

TerseBlog

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

🔗 示例站点: blog.qwara.top

功能特性

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

快速开始

# 中国大陆用户可先配置 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

多语言开关

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

开启后 4 种语言分别用 URL 前缀访问：/en/ /zh-CN/ /zh-TW/ /ja/。根路径 / 自动探测浏览器语言跳转。

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

部署

详见上方 Deployment 章节。

同步上游更新

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

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

---

技术栈

技术	用途
Astro 5	静态站点生成器
TypeScript	类型安全
KaTeX	LaTeX 数学公式渲染
Fuse.js	模糊搜索
@astrojs/sitemap	站点地图
@astrojs/rss	RSS 订阅

许可证

CC BY-NC-SA 4.0