Quarto-Blogs-Template

專案介紹

這是一個基於 Quarto 構建的現代化個人部落格/網站模板，專為研究人員、學生和開發者設計，用於展示研究筆記、專案成果、論文閱讀心得和學習記錄。

專案連結

主要特點

• 模組化結構：支援部落格、專案、論文閱讀和學習筆記等多種內容型別
• 中英文雙語支援：內建語言切換功能，輕鬆實現內容國際化
• 響應式設計：適配各種裝置螢幕尺寸
• 快速開發：提供一鍵指令碼，簡化本地預覽、構建和發布流程
• 自動聚合：首頁自動聚合各模組最新內容
• 可擴充套件性：支援自定義樣式和內容結構

環境要求

• Quarto：安裝指南
• Bash：用於執行指令碼（Windows 使用者可使用 WSL 或 Git Bash）
• rsync：用於發布時的檔案同步（部分指令碼需要）

快速開始

本地預覽

./scripts/preview.sh   # 启动本地服务器（热更新）

構建專案

./scripts/build.sh     # 构建网站到 site/ 目录

發布網站

./scripts/publish.sh   # 备份旧 docs/ 并同步 site/ -> docs/

詳細使用說明

目錄結構（核心）

├── content/              # 所有可渲染内容
│   ├── assets/           # 全站共享图片素材
│   ├── blogs/entries/    # 博客文章
│   ├── projects/entries/ # 项目介绍
│   ├── papers/entries/   # 论文阅读笔记
│   └── learning-notes/   # 学习笔记（含子模块）
├── includes/             # 页面片段（如语言切换按钮）
├── pages/                # 页面文件
│   ├── index.qmd         # 默认首页（About Me）
│   └── home.qmd          # Home 页面（聚合各模块最新内容）
├── scripts/              # 一键脚本
├── site/                 # 构建产物（默认输出目录）
├── docs/                 # 发布目录（GitHub Pages）
├── styles.css            # 全站样式
└── _quarto.yml           # 项目配置文件

新增內容

1. 新增部落格文章

1. 進入部落格文章目錄：content/blogs/entries/
2. 新建檔案，例如 my-blog-post.qmd
3. 新增 YAML 頭部並開始寫作：

---
title: "我的博客文章"
date: 2026-01-13
categories: [blogs]
description: "这是一篇示例博客文章"
---

4. 插入圖片（使用相對路徑）：

![示例图片](../../assets/image.png)

2. 新增專案

1. 進入專案目錄：content/projects/entries/
2. 新建檔案，例如 my-project.qmd
3. 按照上述部落格文章的格式編寫內容

3. 新增論文閱讀筆記

1. 進入論文目錄：content/papers/entries/
2. 新建檔案，例如 paper-review.qmd
3. 按照上述格式編寫內容

4. 新增學習筆記

1. 進入學習筆記目錄：content/learning-notes/
2. 可以建立新的子模組（如 lesson4/）並在其中新增 entries/ 目錄
3. 或者在現有子模組中新增新筆記

語言切換功能

專案支援中英文雙語內容切換，使用方法如下：

::: {.lang-zh}
这是中文内容
:::

::: {.lang-en}
This is English content
:::

在導航欄和頁面標題中也可以使用 HTML 標籤實現語言切換：

<span class="lang-en">About Me</span><span class="lang-zh">关于我</span>

自定義樣式

• 修改 styles.css 檔案可以自定義全站樣式
• 支援自定義主題顏色、字型大小、佈局等

指令碼說明

1. 本地預覽指令碼 (preview.sh)

• 啟動 Quarto 本地伺服器
• 支援熱更新，修改內容後自動重新整理頁面
• 預設埠：4321

2. 構建指令碼 (build.sh)

• 構建網站到 site/ 目錄
• 生成靜態 HTML 檔案

3. 發布指令碼 (publish.sh)

• 備份舊的 docs/ 目錄到 backup/
• 構建網站
• 將構建產物從 site/ 同步到 docs/（GitHub Pages 發布目錄）
• 自動清理舊備份（預設保留最近 3 個備份）

4. 渲染後清理指令碼 (post-render-clean.sh)

• 在專案渲染後自動執行
• 清理巢狀目錄結構
• 最佳化檔案組織

5. 備份清理指令碼 (prune-backups.sh)

• 清理舊的備份檔案
• 可以手動執行以釋放儲存空間

配置檔案說明

_quarto.yml

主要配置檔案，包含：

• 專案型別和輸出目錄
• 渲染規則和資源管理
• 網站導航欄和頁尾設定
• 主題和格式配置

渲染規則

render:
  - pages/index.qmd
  - pages/home.qmd
  - content/**/index.qmd
  - content/**/entries/**/*.qmd
  - content/**/entries/**/*.md

資源管理

resources:
  - assets/**
  - content/assets/**

部署

GitHub Pages

1. 將專案推送到 GitHub 倉庫
2. 配置 GitHub Pages 從 docs/ 目錄部署
3. 執行 ./scripts/publish.sh 構建併發布網站

其他靜態網站託管

1. 執行 ./scripts/build.sh 構建網站
2. 將 site/ 目錄中的內容部署到你的託管服務

注意事項

• tmp/ 目錄用於存放草稿，不會被渲染和提交到 Git
• backup/ 目錄存放發布備份，可隨時清理
• 確保所有內容檔案都有正確的 YAML 頭部
• 使用相對路徑引用圖片和其他資源

許可證

Apache License

貢獻

歡迎提交 Issues 和 Pull Requests 來改進這個模板！