外觀

語言

從 0 建設個人網站

2026 Astro 網站加上部落格:用 Markdown 寫文章

在 Astro 個人網站加上部落格,只要一個放 Markdown 檔的資料夾、一個 content collection 設定檔和兩個頁面(文章列表、文章內頁),不用資料庫。附完整程式碼、RSS 設定,以及我的網站從資料庫搬回檔案的經過。

Kelvin Wang · · 8 分鐘閱讀

在 Astro 網站加上部落格,要做的事只有四件:建一個資料夾放 Markdown 文章、寫一個 src/content.config.ts 告訴 Astro 文章長什麼樣子、做一個文章列表頁、做一個文章內頁。不用資料庫,也不用後台。寫新文章就是新增一個 .md 檔,推到 GitHub,網站重新建置後文章就上線了。每一步都附可以直接貼上的程式碼,用的是 Astro 目前的 content collections 寫法(2026 年 11 月查過官方文件)1。

我的網站 kelvinwang.info 現在有 26 篇中文、26 篇英文舊文,加上這陣子新寫的文章,全部都是 repo 裡的檔案。這套做法我繞了一圈才回來,原因寫在最後一節。

開始之前:你需要一個 Astro 網站

還沒有網站的話,先裝好 Node.js(官方要求 v22.23.4 以上,v23 這類奇數版不支援)2,在終端機執行:

npm create astro@latest my-site
cd my-site
npm run dev

安裝程式問你要哪種範本時選最基本的就好。跑起來之後打開瀏覽器的 http://localhost:4321,看到首頁就代表成功。

如果想跳過這些步驟直接拿一個做好的部落格,Astro 官方有部落格範本:npm create astro@latest -- --template blog5。範本功能齊全,但檔案多,新手不容易看懂哪個檔案在做什麼。自己一步一步做,你會知道每個檔案的用途,之後要改也知道從哪裡改。

想深入 個人網站技術架構怎麼選:為什麼用 Astro + Cloudflare,不用 Next.js 或 WordPress 為什麼選 Astro、怎麼部署到 Cloudflare,以及實際設定檔。

第一步:建資料夾,寫第一篇文章

在專案裡建立 src/content/blog/ 資料夾,新增一個檔案 hello-world.md:

---
title: 我的第一篇文章
description: 用一兩句話說這篇在講什麼,搜尋結果會顯示這段。
pubDate: 2026-11-07
tags: [隨筆]
---

這是內文。Markdown 的寫法:

## 小標題

- 清單用減號
- **粗體**用兩個星號
- [連結](https://example.com) 用中括號加小括號

上下兩條 --- 之間叫 frontmatter,放文章的資料(標題、摘要、日期)。下面才是內文。

檔名會變成網址:hello-world.md 的網址是 /blog/hello-world/。檔名用英文小寫和連字號,發布之後就不要改,改了網址就變,搜尋引擎和別人貼的連結都會失效。

第二步:寫 content collection 設定檔

在 src/ 底下新增 content.config.ts:

import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blog = defineCollection({
  // 讀 src/content/blog 底下所有 .md 和 .mdx 檔
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  // 每篇文章的 frontmatter 必須長這樣,少了或打錯,建置就會失敗
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };

schema 是這個檔案最有用的地方。哪一篇文章忘了寫 description、日期格式寫錯,npm run build 會直接失敗並告訴你是哪個檔案,錯的文章不會悄悄上線。用 AI 寫文章時這條特別有用,AI 偶爾會漏欄位。

第三步:文章列表頁

新增 src/pages/blog/index.astro:

---
import { getCollection } from 'astro:content';

const posts = (await getCollection('blog', ({ data }) => !data.draft))
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());
---
<html lang="zh-Hant">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>文章</title>
  </head>
  <body>
    <h1>文章</h1>
    <ul>
      {posts.map((post) => (
        <li>
          <a href={`/blog/${post.id}/`}>{post.data.title}</a>
          <time datetime={post.data.pubDate.toISOString()}>
            {post.data.pubDate.toLocaleDateString('zh-TW')}
          </time>
        </li>
      ))}
    </ul>
  </body>
</html>

兩個重點:

  • getCollection 的第二個參數是篩選條件,這裡把 draft: true 的草稿排除。
  • 一定要自己排序。官方文件寫明 getCollection 回傳的順序不固定,不排序的話文章順序可能每次建置都不同。

第四步:文章內頁

新增 src/pages/blog/[id].astro。檔名的中括號代表這是一個「每篇文章各產生一頁」的範本:

---
import { getCollection, render } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('blog', ({ data }) => !data.draft);
  return posts.map((post) => ({
    params: { id: post.id },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await render(post);
---
<html lang="zh-Hant">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{post.data.title}</title>
    <meta name="description" content={post.data.description} />
  </head>
  <body>
    <article>
      <h1>{post.data.title}</h1>
      <Content />
    </article>
  </body>
</html>

getStaticPaths 在建置時跑一次,列出所有要產生的頁面;render(post) 把 Markdown 轉成 HTML,<Content /> 就是內文。這裡也要排除草稿,只在列表頁排除的話,草稿雖然不會出現在列表,網址還是打得開。

存檔後打開 http://localhost:4321/blog/,應該會看到第一篇文章的標題,點進去就是內文。

兩個頁面裡的 <html>、<head> 是重複的。網站已經有共用版面(layout)的話,換成你的 layout 元件,把標題和摘要傳進去就好。

第五步(選用):用 MDX 在文章裡放元件

一般 Markdown 只能寫文字、圖片、表格。想在文章裡放互動元件或自訂的提示框,就改用 MDX3:

npx astro add mdx

先做一個元件。最簡單的提示框 src/components/Note.astro:

<aside style="border-left: 4px solid #888; padding: 0.5rem 1rem;">
  <slot />
</aside>

<slot /> 會換成你寫在 <Note> 和 </Note> 中間的內容。接著把文章副檔名改成 .mdx,在 frontmatter 下面 import 這個元件:

---
title: 用 MDX 寫的文章
description: 文章裡可以放元件。
pubDate: 2026-11-07
---

import Note from '../../components/Note.astro';

一般的 Markdown 內文。

<Note>這是一個自訂的提示框。</Note>

第二步的 pattern 已經包含 .mdx,不用再改設定檔。

第六步(選用):加上 RSS

RSS 讓讀者用閱讀器訂閱你的文章。先在 astro.config.mjs 設好網站網址(site: 'https://你的網域'),再安裝官方套件4:

npm install @astrojs/rss

新增 src/pages/rss.xml.js:

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog', ({ data }) => !data.draft);
  return rss({
    title: '我的部落格',
    description: '文章的 RSS',
    site: context.site,
    items: posts.map((post) => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      description: post.data.description,
      link: `/blog/${post.id}/`,
    })),
  });
}

建置之後 /rss.xml 就是訂閱網址。

第七步:發布

寫完文章後:

git add src/content/blog/hello-world.md
git commit -m "post: hello world"
git push

網站如果已經接好自動部署(Cloudflare Workers Builds、Vercel、Netlify 都可以設定成 push 就建置),幾分鐘後文章就上線。沒有接自動部署的話,照你平常部署的方式重新建置一次。

想深入 Cloudflare Workers 教學 2026:Astro 部署與 wrangler 設定 把 Astro 網站部署到 Cloudflare,並設定 push 就自動上線。

用 AI 寫文章時

文章是檔案,AI 寫程式工具可以直接新增和修改。我會在 AI 工具讀的專案說明檔(Claude Code 讀 CLAUDE.md,Codex 讀 AGENTS.md)寫一行文章放在哪裡、檔名規則是什麼,AI 每次就知道要寫到哪個資料夾。schema 會擋掉缺欄位的文章;我的網站另外規定 MDX 文章一定要有 description,沒有就讓建置失敗,因為沒有摘要時頁面會從 MDX 原始碼截一段當搜尋摘要,截出來的可能是 import 語句。

發布前一樣要自己看過。檔案化讓 AI 寫得很快,但 push 之後就是公開的,我的規則是寫稿可以自動,commit、push 之前要我點頭。

我的網站怎麼做(給已經會的人)

我的網站在 2026 年 6 月 10 日加上部落格時,用的就是上面這套:glob() loader 加一篇 hello-world.mdx。隔天(6 月 11 日)我把文章搬進 Supabase 資料庫,建置時從資料庫讀,用自己寫的編輯器發布。

用了五個月之後,2026 年 11 月 5 日又搬回檔案。原因有兩個:

  • 編輯器存的是 HTML,只能放段落、標題、清單、表格和圖片。像交易所事件頁那種需要時間軸、數字卡的文章,編輯器做不到。
  • 我不在後台編輯器裡改文章。AI 起草,我把內容全部看過,確認後說可以發布,剩下的上線工作交給 AI。編輯器用不到,只帶來限制,還讓每篇文章多一份要同步的副本。

搬家時把 52 篇已發布的文章(中英各 26 篇)匯出成檔案,再比對搬家前後建出來的網站:199 個檔案裡 198 個逐位元組相同,唯一的差別是後台程式的一個檔名雜湊。

現在的結構比入門版多了幾層,因為網站有中英兩種語言,還有從資料庫搬來的舊文:

項目入門版我的網站
文章位置src/content/blog/<slug>.mdsrc/content/posts/<slug>/<lang>.mdx
loader官方 glob()自己寫的 loader,同時讀 .mdx 和搬家來的 .html
網址/blog/<id>//zh-hant/blog/<slug>/、/en/blog/<slug>/
文章裡的元件自己做時間軸、數字卡、表格、提示框、資料來源、延伸閱讀卡
草稿draft: truedraft: true,建置時完全不讀

如果你的網站只有一種語言,入門版就夠用很久。

新手常踩的坑

  • 改了檔名,舊網址就 404。 網址來自檔名。要改就加轉址,或乾脆不改。
  • 忘了排序。 getCollection 不保證順序,列表和 RSS 都要自己排。
  • 只在列表排除草稿。 getStaticPaths 裡也要排除,不然草稿的網址還是打得開。
  • 文章放在子資料夾。 glob() 產生的 id 會包含資料夾路徑(例如 2026/hello),id 有斜線時頁面檔名要改成 [...id].astro。
  • 圖片路徑。 最簡單的做法是把圖片放在 public/images/,文章裡用 /images/xxx.webp 引用。

資料來源

  1. 1. Content collections · Astro · 2026-11-07
  2. 2. Install Astro · Astro · 2026-11-07
  3. 3. @astrojs/mdx · Astro · 2026-11-07
  4. 4. Add an RSS feed · Astro · 2026-11-07
  5. 5. Astro blog template · GitHub

關於作者

Kelvin Wang

電機工程師,和 AI Agent 做工具,分享工程與投資的實作筆記。

更多關於我