用写文建站写文章、编排 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 是结果；需要修正时，回到源文件里修改。