用寫文建站寫文章、編排 Pages
作者：toewpq約 4 分鐘閱讀更新於 最近一次變動
修改前
我用寫文建站把寫作和版式留在一般檔案裡。文章寫 Markdown，首頁和專案頁寫 YAML 版面，建置後得到 dist/ 裡的靜態 HTML 與本地資源。日常發一篇文章，不需要為網站維護資料庫。
修改後
我用寫文建站把寫作和版式留在一般檔案裡。文章寫 Markdown，首頁和專案頁寫 JSON 版面，建置後得到 dist/ 裡的靜態 HTML 與本地資源。日常發一篇文章，不需要為網站維護資料庫。
修改前
如果是用已發布的 npm 套件開始一個新站，在空目錄裡初始化：
修改後
若要開始一個新站，使用本站固定的已發布 GitHub 原始碼版本，在空目錄裡初始化：
修改前
npm install edgepress
修改後
npm install edgepress@https://codeload.github.com/jsw-teams/edgepress/tar.gz/ac42e0046d022a318e4eef21e56e2e459584b2a5 --save-exact
修改前
content/pages//en.md (page metadata + rows and elements)
修改後
content/pages//en.json (page metadata + rows and elements)
修改前
站名、標準網址、導覽、頁尾和隱私資訊放在 config.yml；建置路徑、啟用語言與文章路徑格式放在 edgepress.config.mjs。語言檔名用小寫，例如 en.md、zh-cn.md，lang 要符合已啟用的語言。每篇文章或每個頁面有自己的目錄，譯文放在同一個目錄裡。
修改後
站名、標準網址、導覽、頁尾和隱私資訊放在 config.yml；建置路徑、啟用語言與文章路徑格式放在 edgepress.config.mjs。語言檔名用小寫：頁面用 en.json、zh-cn.json，文章用 en.md、zh-cn.md，lang 要符合已啟用的語言。每篇文章或每個頁面有自己的目錄，譯文放在同一個目錄裡。
修改前
一個 category 決定文章歸屬。本站的 blog、uncategorized 進入普通見聞，edgepress、ishare、iask、media-viewer 進入產品筆記。tags 用來描述文章，不決定首頁清單。
修改後
一個 category 決定文章歸屬。本站的 blog、uncategorized 進入見聞觀點，edgepress、ishare、iask、media-viewer 進入產品筆記。tags 用來描述文章，不決定首頁清單。
修改前
---
title: Project notes
lang: en
slug: notes
blocks: [ # page (rows)
{ columns: 2, cells: [ # row (two cells)
[ # left cell (heading, text)
{ type: heading, level: 2, text: "What I am making" },
{ type: text, text: "A small tool for everyday writing." }
],
[ # right cell (articles)
{ type: post-list, title: "Notes", category: edgepress, count: 3 }
]
] }
]
---
修改後
{
"title": "Project notes",
"lang": "en",
"slug": "notes",
"blocks": [
{
"columns": 2,
"cells": [
[
{
"type": "heading",
"level": 2,
"text": "What I am making"
},
{
"type": "text",
"text": "A small tool for everyday writing."
}
],
[
{
"type": "post-list",
"title": "Notes",
"category": "edgepress",
"count": 3
}
]
]
}
]
}
修改前
儲存為 content/pages/notes/en.md，第二道分隔線後保持空白。外層 blocks 放列；columns: 2 對應 cells 中兩個內層清單。左欄先放標題，再放文字；右欄放專案文章清單。[] 表示清單，{} 表示物件，同層項目之間需要逗號。這是標準 YAML，說明中的圓括號不屬於設定語法。
原本的縮排寫法繼續有效。長段落和程式碼建議保留 text: |、code: |。section 的 blocks 放子元素，不是另一套列與儲存格。獨立標題用 heading，段落用 text 或 paragraphs，清單和表格使用對應元素。
修改後
儲存為 content/pages/notes/en.json。中繼資料與 blocks 同在一個 JSON 物件裡，不加 YAML 分隔線，也不寫 Markdown 內文。VS Code 能識別並折疊 blocks、每一列、cells、每個儲存格與元素；本機 $schema 提供欄位說明與結構檢查。columns: 2 對應兩個儲存格陣列，元素依序顯示。section 的 blocks 放子元素，長段落用 paragraphs，程式碼字串內換行用 \n。舊 Markdown/YAML 頁面仍可建置，同一頁面的每種語言只保留一種格式。
我用寫文建站把寫作和版式留在一般檔案裡。文章寫 Markdown，首頁和專案頁寫 JSON 版面，建置後得到 dist/ 裡的靜態 HTML 與本地資源。日常發一篇文章，不需要為網站維護資料庫。
先讓專案執行起來
使用目前原始碼儲存庫時，準備 Node.js 22.12 或更新版本，在專案根目錄執行：
npm ci
npm run new -- post "A quiet afternoon"
npm run dev
新增指令會印出產生的檔案路徑。用編輯器開啟它，保留兩道 --- 之間的中繼資料，在第二道分隔線後寫正文。預覽會在儲存原始檔後重新建置；建立文章時用一次指令，之後就在編輯器裡修改。
若要開始一個新站，使用本站固定的已發布 GitHub 原始碼版本，在空目錄裡初始化：
mkdir my-site
cd my-site
npm install edgepress@https://codeload.github.com/jsw-teams/edgepress/tar.gz/ac42e0046d022a318e4eef21e56e2e459584b2a5 --save-exact
npx edgepress init
npm install
npm 發布版本可能與 GitHub 最新原始碼不同。站點的依賴版本和鎖定檔應一起保留；已經透過依賴使用寫文建站的網站，繼續用自己的 npm 指令碼，不必再全域安裝一份。
分清要改哪個檔案
config.yml (site, theme, privacy, consent services)
edgepress.config.mjs (paths, locales, permalink, build plugins)
content/posts/<post-id>/en.md (article metadata + Markdown)
content/pages/<page-id>/en.json (page metadata + rows and elements)
content/assets/images/walk.jpg (published as /images/walk.jpg)
themes/<name>/ (shared layouts and visual styles)
dist/ (generated output)
站名、標準網址、導覽、頁尾和隱私資訊放在 config.yml；建置路徑、啟用語言與文章路徑格式放在 edgepress.config.mjs。語言檔名用小寫：頁面用 en.json、zh-cn.json，文章用 en.md、zh-cn.md，lang 要符合已啟用的語言。每篇文章或每個頁面有自己的目錄，譯文放在同一個目錄裡。
寫一篇文章
---
title: A quiet afternoon
date: 2026-10-11T10:00:00+08:00
lang: en
category: blog
tags: [walk, photography]
---
We stopped by the water.
## A small detail
指令會填入目前時間和站點語言，上面只是檔案結構範例。佈景主題已經顯示文章標題，正文從段落開始，章節用 ##，不用再放一個同名一級標題。照片先儲存到 content/assets/images/walk.jpg，再用 /images/walk.jpg 引用。
一個 category 決定文章歸屬。本站的 blog、uncategorized 進入見聞觀點，edgepress、ishare、iask、media-viewer 進入產品筆記。tags 用來描述文章，不決定首頁清單。
從外往裡看一個頁面
頁面（列清單）→ 列（欄數，儲存格清單）→ 儲存格（依序排列的元素）→ 元素（類型，內容）。下面是一份完整的雙欄頁面：
{
"title": "Project notes",
"lang": "en",
"slug": "notes",
"blocks": [
{
"columns": 2,
"cells": [
[
{
"type": "heading",
"level": 2,
"text": "What I am making"
},
{
"type": "text",
"text": "A small tool for everyday writing."
}
],
[
{
"type": "post-list",
"title": "Notes",
"category": "edgepress",
"count": 3
}
]
]
}
]
}
儲存為 content/pages/notes/en.json。中繼資料與 blocks 同在一個 JSON 物件裡，不加 YAML 分隔線，也不寫 Markdown 內文。VS Code 能識別並折疊 blocks、每一列、cells、每個儲存格與元素；本機 $schema 提供欄位說明與結構檢查。columns: 2 對應兩個儲存格陣列，元素依序顯示。section 的 blocks 放子元素，長段落用 paragraphs，程式碼字串內換行用 \n。舊 Markdown/YAML 頁面仍可建置，同一頁面的每種語言只保留一種格式。
預覽之後再發布
npm run build 驗證並產生網站，npm run check 把頁面報告寫入 tools/reports/。本地檢查首頁、文章、語言連結和手機版面，再把 dist/ 交給既有託管與部署流程。產生的 HTML 是結果；需要修正時，回到原始檔裡修改。