使用 Quarto 建立 Blog

目錄

• 緣起
• 簡單紀錄我的建立過程
  • 在本機(localthost)檢視網頁
• Quarto Blog Project 的基本架構筆記
• 功能調整
  • 基本 HTML 元素
  • 首頁文章按日期最新排列
  • light / dark theme 切換
  • 插入目錄在每篇文章
  • 轉換檔名
  • 文章加入最後修改日期
  • 插入 .bib 參考文獻
  • 自定義 CSS
• 其他東西
  • 文章部分
• 部署 & 發佈網站
  • 部署到 GitHub Pages 上
  • 部署到 Netlify 上
• 延伸閱讀

緣起

很早以前就想建立自己的小小網站了，雖然在這之前，我用過 Blogger 寫文章，不過用得不是很順手，後來忘記帳密就沒再用了。到近期我才發現自己比較偏好用特定指令寫文章，這件事還是因為要寫數學筆記辦了 hackmd 才發現的。

不得不說， hackmd 是一個非常好用的網站，不只可以用自己熟悉的 markdown 語法寫文章，也可以練習當時還不怎麼熟悉的 html 語法，同時跟一般的線上 markdown editor 相比，它既可以用 code 畫心智圖跟流程圖，也可以發佈成網站。一度想說就這樣繼續用下去吧，但它對我來說有個小小的缺點：寫的文章越長越容易卡頓。

於是我開始異想天開：如果是自己建立的網站應該就不會卡了吧？

在進入軟體業之前，我對網頁設計跟原理都沒有概念，進入軟體業之後雖然稍微有了一點”常識”，也接觸一些諸如 gitbook 等用來寫說明文件非常方便的軟體服務，但對於網頁是怎麼從寫成到上線，還是只有很模糊的：「呃…總之就是先在 localhost 寫一寫，再丟到測試機檢查，沒問題再丟到正式機吧？」過程中會用到的技術幾乎是0概念，但我還是很興奮地去研究各種可能的方案。

第一個閃過的想法，是從頭學 html 跟 css 語法，自己刻一個網站，但我很快就發現非常花時間，而且要用其他引擎渲染 markdown 數學符號，實在是太麻煩。第二個想法是用 C# 建立網站，也是有同樣的問題，再加上 C# 的語法長得實在是看得不習慣(也可能是我只喜歡語法簡潔的東西，像是 markdown 或是 python，方案二也放棄了。

第三個想法，就是用 python 或是 r 的相關套件來建立模板，有需要再自己改模板就好，不過上了研究所後會用來做筆記的檔案類型不只 .md 檔，還有 .ipynb、.rmd、.r等等，雖然很多都是 markdown 的延伸，但還是想要盡可能的在不改變副檔名的前提下整合他們。同時又想找美觀又可以調整 light/ dark theme 的模板來使用。就這樣多方考慮後我選擇了 Quarto 來作為我的模板，主要原因是官網上提供的範例無論是在提供的功能還是美觀方面看起來都非常吸引人！也支援前述提到的檔案格式，再加上官網上的教學看起來相當易懂，於是就來用用看了。想要看完整教學的可以的點此。

簡單紀錄我的建立過程

1. 按照官網指示下載檔案，再點選常用的 IDE，我是 Windows / Vscode 路線。
2. 按照官網指示，在 Vscode 安裝 Quarto 的 Extension。
3. 在Vscode的環境下新增檔案(File/New File…)，點選 “Quarto Project”，並選擇你想建立的網站類型，我是選擇 Blog Project。
4. Quarto 會自動生出設定sample檔。

生成sample後先暫時不要動它，來試跑看看，也就是在本機(localthost)檢視網頁！

在本機(localthost)檢視網頁

檢視網頁有2種方法:

• 第一種：在 Terminal cd 到目前 Project 的資料夾，使用 quarto preview 指令。這會另外開啟常用瀏覽器檢視，指令碼複製如下：

quarto preview

• 第二種：在 Vscode 右上角有個 的符號，點擊可在右側 preview 網頁渲染結果。

兩種方法都不錯，我覺得第一種方法適合螢幕小或想要檢視不同瀏覽器運作情況的人，第二種適合電腦螢幕大時使用，看個人需求了。

知道怎麼檢視網頁後，接下來就可以認識 Blog Project 的架構跟調整設定了。

Quarto Blog Project 的基本架構筆記

基本架構大概像這樣：

Quarto Blog Project      ← 專案資料夾
├── _quarto.yml          ← 整體設定（佈景主題、導覽列）
├── index.qmd            ← 首頁
├── about.qmd            ← 關於頁面
├── posts/               ← 文章存放區
│   └── post1/           ← 單篇文章的資料夾
│         ├── index.qumd
│         └── image.png
├── _docs/             ← 用 github page 部署時會出現的資料夾（自動產生）
└── _site/               ← 渲染後輸出的網站內容（自動產生）

就像許多個人網站的架構那樣，屬於 Blog Project 資料夾的最外層會有個用來當首頁的index.qmd，.qmd是 Quarto 的檔案格式之一，我個人的理解是類似 RMarkdown 可以寫 markdown 語法也可以跑程式，但它可以更沒有障礙的跑 python 的程式碼。¹此外還有主要用來控制顯示網站 head 部分的 _quarto.yml，以及自我介紹用的about.qmd跟可以自定義 CSS 風格的 styles.css。

存放文章的地方在資料夾 posts裡，每份文章都以資料夾的形式包著。文章的內容本體也是.qmd檔，可以直接修改，這篇文章也是用.qmd檔撰寫的。另外，文章資料夾的命名可以隨意，因為網站在渲染過程中會直接讀取posts下的所有資料夾，資料夾本身的名稱不會影響讀取。

功能調整

基本 HTML 元素

Project 下最外層的 _quarto.yml 可以設定 HTML 網站的基本元素：

website:
 title: "紙魚ㄉ部落格" #網站名稱
 description: "用來記錄各種東西的部落格，包含玩具、最近學到的知識" #對應html<meta name="description" contant=...>
 favicon: "paperfish_logo.png" # 網站小圖示
 site-url: https://paperfishblog.netlify.app/ #對應html<link rel="canonical" href=...>


lang: zh-TW # 網站語言:繁體中文

首頁文章按日期最新排列

若想所有文章按日期最新排列，可以在 Project 下最外層的 _quarto.yml 調整，首先撰寫文章的 index.qmd 的YAML都要設定日期，這部分預設模板有給：

date: "2025-07-23"

　再來是修改最外層的_quarto.yml，新增下面語法

listing:
  contents: posts
  sort: "date desc"  # 日期最新的在前面

需要注意 yaml 的順序跟階層關係很重要，順序跟階層不對會報錯。

light / dark theme 切換

一樣修改最外層的，語法如下：

format:
  html:
    theme:
      light: flatly
      dark: darkly

這樣網站的右上角會出現一個小小的切換鈕，但個人覺得這個設計不太直觀，有機會再來研究看看可以怎麼改。

插入目錄在每篇文章

一樣在最外層的 _quarto.yaml 的 format:層下輸入

    toc: true
    toc-location: body
    toc-depth: 2
    toc-title: "目錄"
    number-sections: false

第一個語法會召喚開啟文章目錄，第二個則是目錄出現位置，body是文章開頭，另有left(文章左側)跟right(文章右側)可選。如果要顧及使用手機閱覽的使用者，可以用left-body(同時在左側與文章開頭中顯示目錄)或right-body(同時在右側與文章開頭顯示目錄)。

第三個是文章目錄在直接顯示時要顯示 header 幾，這裡的 2 表示在網頁剛載入時，目錄會顯示文章到 header 2 (markdown 語法 ## )為止的標題。

注意如果前面的toc-location設定為left或right，用滑鼠點擊大 header 還是可以展開底下所有的小 header，只是初始載入會隱藏。

number-sections則是要不要幫每個 header 標上編號，格式按 header 大小為 1、1.1、1.1.1…，以此類推，我覺得很醜所以用false取消編號。如果這個語法沒有設定，會導致有些檔案格式的文章如.qmd不編號，.md卻編號的情況，因此如果要統一還是要強制設定。

轉換檔名

.qmd為 Quarto 官方提供的檔案格式，雖然用它寫 markdown + run python 很好用，但有時候要 render 時卻會出錯，找不出問題時有一個暴力硬解法－轉換副檔名為.ipynb。

轉換成 ipynb 的其他好處

.ipynb 可以同時跑 python 跟 R，也有 package 專把 .ipynb 編譯成網站，例如介紹過的jpyterbook

quarto convert your_file.qmd --to ipynb

轉換後大致上可以無痛 work ，但有時有些設定會跑掉，還是要先 preview 檢查。

文章加入最後修改日期

預設模板的 YAML 僅列出常用的參數，但實際上還有其他東西可以加進去，最後修改日期是其中之一。在想要修改的文章中的 YAML 加入即可，範例：

date-modified: '2025-10-22'

插入 .bib 參考文獻

插入 .bib 參考文獻可不是 \(\LaTeX\) 的專利，基於 Pandoc 設計的 Quarto 也做得到，只是它有自己的語法跟做法。

首先準備好你的 bib 檔放在要插入文獻的文章資料夾，接著在文章的 YAML 加入相關設定：

bibliography: ref.bib #你的 bib 檔名
csl: apa.csl # 引用格式，建議需要對應csl檔放在同資料下
nocite: "@*" #不在內文引用也列出

其中.csl不一定要放，不過這樣會使用預設設定，有點醜所以我還是設了。

接著在文章最後加入 :

::: {#refs}

:::

即可，理論上應該是所有支援 markdown 語法的檔案類型都能適用。

自定義 CSS

儘管受限於使用的 theme ，導致不是每個 CSS 語法都能起作用，不過 Quarto 支援 CSS 及 SCSS ，讓我們可以有限度的修改 theme 的風格。以下紀錄目前有用到的 CSS 語法，首先若要引用CSS語法需要先建一個副檔名為 .css的檔案在想要修改的檔案位置，如果是要修改整體網站的話，則是放在專案資料夾的最外圍。

接著撰寫 CSS 語法後在想要修改的檔案的 YAML 中這樣寫即可：

format:
  html:
    css: styles.css  # 假設 styles.css 為要引用的檔案

這樣就完成了引用，正常情況下裡面的語法能 work ，如果無法 work 則可能代表 CSS 語法本身有誤(語法錯誤或是指定對象有誤)，或是這裡的 CSS 語法對目前使用的 theme 不起作用。

以下紀錄能 work 的語法：

code 文字、背景顏色指定

這裡的 code 指的是像是 code 這樣的效果。

/* 指定對象須視實際情況調整 */
body.quarto-dark .listing-description code {
  color: #9d32fa; /*字體顏色*/
  background-color: #f8f8f2; /*背景顏色*/
}

修改 Categories 標題文字內容

流程為隱藏舊文字，加入新文字

/* 隱藏舊文字 */
h5.quarto-listing-category-title {
color: transparent!important; /* 利用!important 強制蓋掉預設指令*/
 position: relative;
}

/* 加入新文字  */
h5.quarto-listing-category-title::after {
  content: "標籤/tags"; /* 要顯示的新文字 */
  color: coral; /* 文字顏色，必留 */
  font-size: 1rem; /* 正常大小 */
  font-weight: bold;
  position: absolute; /* 位置參數，必留 */
  left: 0; /* 位置參數，必留 */
  top: 0; /* 位置參數，必留 */
}

隱藏文章列表

#listing-listing {
  display: none !important;
}

其他東西

有些東西模板沒有出現，是後來研究後才發現可以用，就記錄在這。可能跟首次建立部落格關係不大，有需要可直接前往建立網站。

文章部分

隱藏正在撰寫的文章

在文章的 yaml 中加入設定

draft: true

部署 & 發佈網站

部署到 GitHub Pages 上

這裡實在是困難重重(對我來說)，只能先筆記下摸索出來的方法。

先假設前置所需的 git 跟 Github 都設定完成。

首先打開 Terminal ， cd 到 Project 資料夾，key 入:

quarto render

成功的話 terminal 會出現以下命令：

Output created: docs\index.html

我的不知道為什麼，第一次生成一個叫 doc 的資料夾，但 Github Page 只認 docs，所以生成後要修改檔名。

然後在最外層的_quarto.yml設定：

project:
  type: website
  output-dir: docs

接著按照先前學過的，檢查確認 localhost 的 preiew 沒問題後，將本地端 push 到 Github repository。

再來前往 Github repository setting / Pages ，將設定改成mian\docs。等待幾分鐘後，如果成功Pages的頁面會生成網址，可以點進去檢查。

部署到 Netlify 上

與部署到 GitHub Pages 上類似，只是部署到 Netlify 上時可選擇要部署純靜態網頁還是要再另外自動執行 quarto render 指令，這裡只寫部署純靜態網頁因為自動執行我失敗了QQ

第一步要先建立一個叫做 netlify.toml 的東西，內容打：

[build]
  command = "echo 'no build step, just deploy _site'"
  publish = "docs"  # ← 根據你的 Quarto 輸出資料夾修改

後面的步驟與部署到 GitHub Pages 類似，都要先執行quarto render，只是網站輸出的資料夾不一定要是 docs，Quarto 預設的輸出資料夾 _site也可以部署。只需要知道 render 後的靜態網站在哪個資料夾即可 push 到你指定的 repo ，接著開始後續的部署作業。

再來到 Netlify的網站上用 GitHub 帳號登入，首次使用時系統會自動指引你 add new project，如果非首次使用可以在這裡看到：

點選後選擇 import an existing project，進入設定新的 Project 介面，前面按指示設定就好，到 3. Configure project and deploy這裡才需要注意 Build settings，要修改的地方有：

• Branch to deploy : 就main

• Build command : 請輸入純 cmd print 訊息指令echo： echo 'no build step, just deploy'

• Publish directory : 請輸入 render 後的輸出資料夾(同netlify.toml publish 的設定)

只要有設定這些，就能完成部署最低需求。

延伸閱讀

本文只記錄了我的建立過程，很多 Quarto 可以玩的設定跟不同安裝路線都沒紀錄，如果還想看看其他人怎麼玩的話：

• https://albert-rapp.de/posts/13_quarto_blog_writing_guide/13_quarto_blog_writing_guide.html

• https://beamilz.com/posts/2022-06-05-creating-a-blog-with-quarto/en/

• https://www.crumplab.com/blog/post_887_8_25_22_quartoblog/

也有寫得更全面的教學文：

• https://randomrealizations.com/posts/blogging-with-quarto-and-jupyter/

也有其他中文的教學文，寫得滿好der：

• https://xiaolong70701.github.io/blog/posts/2023-07-06-r-blog-with-quarto-zh/

腳註

1. rmd可以使用python，但其原理是要通過R的套件使用，但qmd則是可以直接用python處理。