指南：基于 Astro 的 CMS 站點結(jié)構(gòu)、內(nèi)容模型與主題定制)
CMS后端前端插件系統(tǒng)【免費下載鏈接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress項目地址https://gitcode.com/gh_mirrors/emdas/emdash點擊查看免費下載EmDash 是一個基于 Astro 構(gòu)建的全棧 TypeScript CMS被項目描述為 WordPress 的精神續(xù)作而templates/blog正是官方為以寫作為核心產(chǎn)品的博客場景準(zhǔn)備的完整模板。本文以 templates/blog/CLAUDE.md 為骨架結(jié)合模板內(nèi)的源碼、配置與種子數(shù)據(jù)系統(tǒng)講解該模板的啟動命令、關(guān)鍵文件職責(zé)、內(nèi)容 Schema 設(shè)計、頁面路由實現(xiàn)、視覺系統(tǒng)與定制方法幫助你快速上手并二次開發(fā)一個屬于自己的 EmDash 博客站點。模板定位一個寫作即產(chǎn)品的博客根據(jù) CLAUDE.md 中的模板說明這是一個包含posts文章、pages頁面、categories分類、tags標(biāo)簽、全文搜索與 RSS的博客模板定位是個人寫作、技術(shù)寫作、獨立通訊indie newsletters以及任何以寫作為核心產(chǎn)品的場景。它的視覺基調(diào)是編輯部技術(shù)美學(xué)editorial-tech aesthetic自信的無襯線字體、克制的強調(diào)色、帶 bylines署名與閱讀時間reading time的真實文章結(jié)構(gòu)。整套模板由以下文件構(gòu)成位于 templates/blog文件/目錄用途astro.config.mjsAstro 配置包含emdash()集成、數(shù)據(jù)庫與存儲src/live.config.tsEmDash loader 注冊樣板代碼勿修改seed/seed.jsonSchema 定義 演示內(nèi)容collections、fields、taxonomies、menus、widgetsemdash-env.d.ts集合的生成類型dev server 啟動時自動重新生成src/layouts/Base.astro基礎(chǔ)布局承載 EmDash 接線菜單、搜索、頁面貢獻(xiàn)src/pages/Astro 頁面——全部服務(wù)端渲染快速啟動兩條命令跑起來CLAUDE.md 給出了最核心的兩條命令pnpm dev # 啟動 Astro 開發(fā)服務(wù)器 npx emdash types # 根據(jù)運行中的站點重新生成 TypeScript 類型配套腳本在 package.json 中定義完整devastro dev、buildastro build、previewastro preview、startnode ./dist/server/entry.mjs、typecheckastro check。其中start表明該模板構(gòu)建后以Node 獨立模式standalone運行。管理后臺Admin UI地址為http://localhost:4321/_emdash/admin。開發(fā)模式下啟動后即可在后臺登錄、寫文章、管理分類標(biāo)簽所有改動實時反映到前臺頁面。類型生成機制npx emdash types會基于運行中的站點即當(dāng)前 seed 的集合與字段定義重新生成 emdash-env.d.ts。這個文件的類型會在 dev server 啟動時自動重新生成因此當(dāng)你修改了 seed 中的字段后重啟開發(fā)服務(wù)器即可獲得帶完整類型提示的查詢 API 體驗。關(guān)鍵文件地圖CLAUDE.md 用一張表概括了核心文件職責(zé)理解它們就等于理解了模板的運行骨架astro.config.mjs— Astro 配置含emdash()集成、數(shù)據(jù)庫和存儲配置src/live.config.ts— EmDash loader 注冊屬于樣板代碼不要修改seed/seed.json— Schema 定義與演示內(nèi)容集合、字段、分類法、菜單、組件區(qū)emdash-env.d.ts— 集合的生成類型src/layouts/Base.astro— 基礎(chǔ)布局含 EmDash 接線菜單、搜索、頁面貢獻(xiàn)src/pages/— 全部服務(wù)端渲染的 Astro 頁面。架構(gòu)核心emdash()集成、數(shù)據(jù)庫與存儲astro.config.mjs 是整個模板的裝配中心import node from astrojs/node; import react from astrojs/react; import auditLog from emdash-cms/plugin-audit-log; import { defineConfig, fontProviders } from astro/config; import emdash, { local } from emdash/astro; import { sqlite } from emdash/db; export default defineConfig({ output: server, adapter: node({ mode: standalone, }), image: { layout: constrained, responsiveStyles: true, }, integrations: [ react(), emdash({ database: sqlite({ url: file:./data.db }), storage: local({ directory: ./uploads, baseUrl: /_emdash/api/media/file, }), plugins: [auditLog], }), ], fonts: [ /* 見下文字體管線 */ ], devToolbar: { enabled: false }, });要點解讀output: server Node adapter這呼應(yīng)了 CLAUDE.md 的硬性規(guī)則——所有內(nèi)容頁面必須服務(wù)端渲染禁止為 CMS 內(nèi)容使用getStaticPaths()emdash()集成接收三類配置database這里用sqlite({ url: file:./data.db })本地開發(fā)默認(rèn) SQLite 單文件數(shù)據(jù)庫storagelocal({ directory: ./uploads, baseUrl: /_emdash/api/media/file })媒體文件存儲在./uploads通過/_emdash/api/media/file對外提供plugins默認(rèn)掛載了emdash-cms/plugin-audit-log審計日志插件這是工作區(qū)內(nèi)的官方插件react()集成用于后臺管理 UI 與評論組件等 React 渲染部分devToolbar: { enabled: false }關(guān)閉了 Astro 默認(rèn)的 dev toolbar。內(nèi)容加載器live.config.tssrc/live.config.ts 定義了 EmDash 的 Live Content Collectionsimport { defineLiveCollection } from astro:content; import { emdashLoader } from emdash/runtime; export const collections { _emdash: defineLiveCollection({ loader: emdashLoader() }), };它建立了_emdash集合覆蓋數(shù)據(jù)庫中所有內(nèi)容類型。頁面中通過getEmDashCollection()與getEmDashEntry()按類型查詢具體內(nèi)容——這正是 CLAUDE.md 要求不要修改的原因它是模板與 EmDash 運行時之間的固定接線。內(nèi)容 Schemaseed.json 決定一切CLAUDE.md 中的 Schema 一節(jié)可以用 seed/seed.json 完整印證。整個文件以$schema聲明、version: 1開頭meta提供元信息然后依次定義settings站點設(shè)置settings: { title: My Blog, tagline: Thoughts on building for the web }CLAUDE.md 指出站點設(shè)置的title和tagline都會渲染在 header / footer 中。模板的 site-identity.ts 會讀取它們并解析出siteTitle、siteTagline、siteLogo。collections集合posts集合字段titlestring必填可搜索——文章標(biāo)題featured_imageimage——頭圖contentportableText可搜索——正文Portable Text 富文本excerpttext——摘要。posts的supports聲明為[drafts, revisions, search, seo]即支持草稿、修訂歷史、全文搜索與 SEO且commentsEnabled: true開啟了評論。pages集合字段titlestring必填可搜索contentportableText可搜索。用于/about等靜態(tài)頁面。taxonomies分類法{ name: category, label: Categories, hierarchical: true, collections: [posts], terms: [...] } { name: tag, label: Tags, hierarchical: false, collections: [posts], terms: [...] }注意name是查詢時使用的精確標(biāo)識如category而非categories——這是 CLAUDE.md 規(guī)則列表中的明確要求。分類是層級化的hierarchical: true標(biāo)簽則扁平。種子數(shù)據(jù)中分類含 development / design / notes標(biāo)簽含 webdev / opinion / tools / creativity。bylines署名bylines: [ { id: byline-editorial, slug: emdash-editorial, displayName: EmDash Editorial }, { id: byline-guest, slug: guest-contributor, displayName: Guest Contributor, isGuest: true } ]文章通過bylines關(guān)聯(lián)作者署名isGuest標(biāo)記客座作者。menus菜單單一的primary菜單默認(rèn)包含 Home、About、Posts 三個自定義鏈接項type: custom。此外 Base.astro 還會嘗試讀取可選的social菜單用于頁腳Connect欄——如果 seed 未定義該欄只顯示 RSS。widgetAreas組件區(qū)seed 定義了sidebar單篇文章頁右側(cè)欄與footer頁腳兩個組件區(qū)sidebar 掛載了core:search搜索、core:categories分類、core:tags標(biāo)簽、core:recent-posts最新文章count: 5、showDate: true、core:archives歸檔月度、limit: 6footer 掛載了一個content類型的小組件渲染一段 Portable Text 簡介。sections區(qū)塊與 content內(nèi)容newsletter-signup與about-author兩個 theme 區(qū)塊帶keywords便于檢索復(fù)用以及 7 篇演示文章 1 篇草稿status: draft草稿不會出現(xiàn)在公開列表和 1 個 About 頁面。演示文章使用$media語法引用外部圖片作為featured_image每篇均聲明了bylines與taxonomies歸屬。頁面與路由每個 URL 都對應(yīng)一個 Astro 文件CLAUDE.md 的 Pages 表列出了模板的完整路由在 src/pages 中一一對應(yīng)頁面路徑內(nèi)容首頁/精選文章 Hero大圖 摘要、最新文章網(wǎng)格全部文章/posts文章計數(shù)、帶摘要與標(biāo)簽徽章的文章列表文章詳情/posts/[slug]頭圖、標(biāo)題、正文、左側(cè)元信息列作者 日期、右側(cè) TOC 搜索 分類欄搜索/search全文搜索 UI頁面/pages/[slug]靜態(tài)頁面內(nèi)容Portable Text分類/category/[slug]按分類過濾的文章標(biāo)簽/tag/[slug]按標(biāo)簽過濾的文章RSS/rss.xml生成的 feed首頁的數(shù)據(jù)查詢模式src/pages/index.astro 是理解模板查詢約定的最佳范例用getEmDashCollection(posts, { orderBy: { published_at: desc }, limit: POSTS_PER_PAGE 1 })讓數(shù)據(jù)庫做切片POSTS_PER_PAGE 7多取 1 條用于判斷是否顯示View all而不是拉全量再在 JS 里裁剪自動挑選第一篇有featured_image的文章作為 Hero其余進(jìn)網(wǎng)格用getTermsForEntries(posts, ids, tag)一次性批量查詢多篇文章的標(biāo)簽避免逐篇調(diào)用getEntryTerms()造成 N1 查詢查完內(nèi)容后立即Astro.cache.set(cacheHint)。文章詳情頁的三欄閱讀布局src/pages/posts/[slug].astro 實現(xiàn)了 CLAUDE.md 強調(diào)的招牌三欄閱讀視圖左側(cè)元信息列--meta-col-width180pxsticky 定位展示 bylines 頭像與署名、發(fā)布時間、閱讀時間、標(biāo)簽中間正文列--content-width680pxPortableText value{post.data.content} /渲染富文本并用Image組件渲染頭圖右側(cè)欄--gutter-width200px客戶端腳本從正文的 h2/h3 構(gòu)建 TOC帶 IntersectionObserver 滾動高亮下方是WidgetArea namesidebar /渲染的側(cè)欄組件區(qū)底部還有Continue reading相關(guān)文章區(qū)塊與Comments/CommentForm評論系統(tǒng)seed 中commentsEnabled: true。頁面還展示了 SEO 的完整鏈路getSeoMeta(post, {...})生成標(biāo)題、描述、OG 圖、canonical、robots再通過getImageUrl()從圖片對象src或meta.storageKey推導(dǎo) OG 回退圖最后以createPublicPageContext()注入 Base 布局。搜索頁走 FTS 而不是 JS 過濾src/pages/search.astro 的注釋點明了設(shè)計意圖調(diào)用 EmDash 的search(query, { collections: [posts], limit: 30 })全文搜索 API由數(shù)據(jù)庫完成分詞、詞干化與排序而不是把全部文章拉到 JS 里過濾——后者在文章數(shù)超過幾百篇后會迅速不可用。返回結(jié)果中的snippet已包含mark高亮標(biāo)簽頁面用set:html渲染。六條硬性規(guī)則來自 CLAUDE.md所有內(nèi)容頁面必須服務(wù)端渲染output: serverCMS 內(nèi)容禁用getStaticPaths()圖片字段是對象{ src, alt }而非字符串必須用emdash/ui的Image image{...} /渲染entry.id是 slug用于 URLentry.data.id是數(shù)據(jù)庫 ULID用于getEntryTerms等 API 調(diào)用查詢內(nèi)容的頁面必須調(diào)用Astro.cache.set(cacheHint)設(shè)置緩存提示查詢中的分類法名稱必須與 seed 的name字段完全一致例如category而不是categories。這些規(guī)則在源碼中都能找到對應(yīng)實現(xiàn)所有頁面均帶cacheHint調(diào)用getTermsForEntries使用entry.data.id頁面跳轉(zhuǎn)鏈接使用p.idslug。視覺系統(tǒng)單字體、單強調(diào)色、三欄文章版式CLAUDE.md 的 Visual character 一節(jié)精確描述了模板的視覺 DNA源碼可在 src/styles/tokens.css 驗證單一字體族全站使用Inter綁定--font-body標(biāo)題默認(rèn)復(fù)用正文字體靠字重與字號建立層級--font-weight-heading600、--font-weight-display700 用于 h1/頁標(biāo)題h1/h2 收緊字距--tracking-tight/--tracking-snugJetBrains Mono綁定--font-mono用于行內(nèi)代碼與代碼塊品牌色#0066cc--color-brand用于鏈接、文章卡片標(biāo)題 hover 與搜索框 focus 光環(huán)另有--color-text-secondary與--color-muted用于次級文本與元信息。不要添加第二個強調(diào)色文章三欄版式是標(biāo)志性功能左欄元信息、中間 680px 正文、右欄搜索 TOC 分類。桌面端不要把它壓成一欄——這個布局在向讀者傳遞這是值得閱讀的內(nèi)容。深色模式與主題切換tokens.css 中所有顏色都用light-dark(light, dark)定義同一個 token 同時攜帶明暗兩套值無需維護(hù)單獨的暗色面板。Base.astro 的內(nèi)聯(lián)腳本會在頁面渲染前立即根據(jù)themecookie 應(yīng)用主題防止閃爍頁腳提供 light / dark / system 三個切換按鈕通過寫themecookie 與給html加 class 實現(xiàn)。此外還有針對不支持light-dark()的舊瀏覽器Safari 17.5、Chrome 123的純亮色回退塊。定制化token 覆蓋、字體管線與 CSS 變量清單設(shè)計 token 的分層覆蓋機制CLAUDE.md 明確指出設(shè)計 token 的默認(rèn)值全部在src/styles/tokens.css而重新?lián)Q膚應(yīng)該改src/styles/theme.css——因為 theme.css 中的聲明是**無分層unlayered**的永遠(yuǎn)壓過layer base的默認(rèn)值無需技巧性的選擇器優(yōu)先級對抗。不要為了視覺改動而去編輯tokens.css或Base.astro。theme.css 的注釋給出了示例:root { --color-brand: light-dark(#0f766e, #2dd4bf); --font-heading: Iowan Old Style, Georgia, serif; --radius: 8px; }覆蓋顏色的兩條規(guī)則用純色值覆蓋會同時改變明暗兩套模式想保持明暗區(qū)分就用light-dark(light, dark)覆蓋。字體管線astro.config.mjs 的 fonts 配置Webfont 在 astro.config.mjs 的fonts:數(shù)組中配置fonts: [ { provider: fontProviders.google(), name: Inter, cssVariable: --font-body, weights: [400, 500, 600, 700], fallbacks: [sans-serif], }, { provider: fontProviders.google(), name: JetBrains Mono, cssVariable: --font-mono, weights: [400, 500], fallbacks: [monospace], }, ],換正文襯線字體的操作是修改綁定cssVariable: --font-body的條目的name。CLAUDE.md 推薦的無襯線替代Geist、IBM Plex Sans、S?hne需授權(quán)、Public Sans如果想要襯線正文博客可換 Source Serif、Crimson Pro 或 Lora——但換襯線后要把--font-size-base提到1.0625rem以?？勺x性。若只想讓標(biāo)題用別的字體或改用系統(tǒng)字體而不碰字體管線直接在 theme.css 覆蓋--font-heading或--font-body即可。Base.astro 通過Font cssVariable--font-body preload /加載并預(yù)取字體。值得掌握的 CSS 變量完整列表見 tokens.css品牌與配色--color-brand、--color-brand-hover、--color-on-brand、--color-brand-ring頁面配色--color-bg、--color-bg-subtle、--color-surface、--color-text、--color-text-secondary、--color-muted、--color-border、--color-border-subtle字體--font-body、--font-heading、--font-mono字重--font-weight-heading600/--font-weight-display700——換襯線時可調(diào)低字距--tracking-tight/--tracking-snug/--tracking-wide/--tracking-wider用于標(biāo)題與元信息標(biāo)簽布局--content-width680px正文列、--wide-width1200px最大容器、--gutter-width200px文章頁右側(cè) TOC 欄、--meta-col-width180px文章頁左側(cè)元信息列頭像--avatar-size-{xs,sm,md,lg}對應(yīng)卡片、列表、精選、單篇文章等不同尺度的 byline 頭像。值得留意的是 tokens.css 中的全套字號階梯--font-size-xs到--font-size-5xl、行高--leading-tight到--leading-relaxed、間距--spacing-1到--spacing-24與陰影 token--shadow-sm/--shadow-lg它們共同支撐了整套版式的統(tǒng)一性。反向清單不要做什么CLAUDE.md 的 What not to do 是一份極具實操價值的邊界清單不要添加第二個強調(diào)色或彩色區(qū)塊背景——頁面應(yīng)該是黑、白、一種藍(lán)不要用展示型無襯線體Bebas、Anton 等替換 Inter——標(biāo)題層級靠字重而非新奇字體不要在桌面端折疊文章側(cè)欄——它是閱讀體驗的一部分不要用模板式博客文案Welcome to my blog、Stay tuned for more——寫一句真正說明這個博客是干什么的 tagline不要用三篇一模一樣的占位文章填充首頁——只有一篇真實文章就展示一篇不要在沒有審核計劃時開啟評論——模板默認(rèn)不附帶評論系統(tǒng)是有原因的。Agent 技能與文檔接入面向 AI 編碼工具CLAUDE.md 的 Skills 與 Documentation 兩節(jié)面向 AI Agent 場景但同樣值得人類開發(fā)者了解技能存放于.agents/skills/按任務(wù)加載building-emdash-site內(nèi)容查詢、Portable Text 渲染、Schema 設(shè)計、seed 文件、菜單/組件區(qū)/搜索/SEO/評論/byline 等站點特性建議從這里開始、creating-plugins用 hooks、storage、admin UI、API routes 與 Portable Text block 類型構(gòu)建插件、emdash-cli內(nèi)容管理、seed、類型生成與可視化編輯流程的 CLI 命令EmDash 文檔以 MCP server 形式提供模板自帶了.mcp.json、.cursor/mcp.json、.vscode/mcp.json使 Claude Code、Cursor、VS Code 能自動發(fā)現(xiàn)文檔服務(wù)器其他工具OpenCode、Windsurf 等需要一次性手動配置。延伸閱讀模板根說明templates/blog/README.md若存在Agent 模板約定templates/blog/AGENTS.md 與 templates/blog/AGENTS-template.md版本變更記錄templates/blog/CHANGELOG.md同系列云托管模板templates/blog-cloudflareCloudflare Workers 版本以及 marketing、portfolio、starter 等姊妹模板見 templates全倉庫技能庫skills/building-emdash-site/SKILL.md、skills/creating-plugins/SKILL.md、skills/emdash-cli/SKILL.md贊分享CMS后端前端插件系統(tǒng)【免費下載鏈接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress項目地址https://gitcode.com/gh_mirrors/emdas/emdash點擊查看免費下載相關(guān)推薦EmDash 博客模板深度指南基于 Astro 的全棧 CMS 站點搭建與定制EmDash 博客模板深度指南基于 Astro 的全棧 CMS 站點搭建與定制 EmDash 是一個基于 Astro 構(gòu)建的全棧 TypeScript CMSCMS后端前端插件系統(tǒng)EmDash 博客模板Cloudflare 版實戰(zhàn)指南基于 Astro D1 R2 的編輯器優(yōu)先 CMS 站點搭建EmDash 博客模板Cloudflare 版實戰(zhàn)指南基于 Astro D1 R2 的編輯器優(yōu)先 CMS 站點搭建 本指南圍繞 EmDash 官方CMS后端前端插件系統(tǒng)EmDash Blank 模板實戰(zhàn)基于 Astro 從零搭建無預(yù)設(shè) CMS 站點的最小基底EmDash Blank 模板實戰(zhàn)基于 Astro 從零搭建無預(yù)設(shè) CMS 站點的最小基底 導(dǎo)讀 templates/blank 是 EmDash一個構(gòu)建在CMS后端前端插件系統(tǒng)創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 EmDash 博客模板實戰(zhàn)指南：基于 Astro 的 CMS 站點結(jié)構(gòu)、內(nèi)容模型與主題定制
CMS后端前端插件系統(tǒng)【免費下載鏈接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress項目地址https://gitcode.com/gh_mirrors/emdas/emdash點擊查看免費下載EmDash 是一個基于 Astro 構(gòu)建的全棧 TypeScript CMS被項目描述為 WordPress 的精神續(xù)作而templates/blog正是官方為以寫作為核心產(chǎn)品的博客場景準(zhǔn)備的完整模板。本文以 templates/blog/CLAUDE.md 為骨架結(jié)合模板內(nèi)的源碼、配置與種子數(shù)據(jù)系統(tǒng)講解該模板的啟動命令、關(guān)鍵文件職責(zé)、內(nèi)容 Schema 設(shè)計、頁面路由實現(xiàn)、視覺系統(tǒng)與定制方法幫助你快速上手并二次開發(fā)一個屬于自己的 EmDash 博客站點。模板定位一個寫作即產(chǎn)品的博客根據(jù) CLAUDE.md 中的模板說明這是一個包含posts文章、pages頁面、categories分類、tags標(biāo)簽、全文搜索與 RSS的博客模板定位是個人寫作、技術(shù)寫作、獨立通訊indie newsletters以及任何以寫作為核心產(chǎn)品的場景。它的視覺基調(diào)是編輯部技術(shù)美學(xué)editorial-tech aesthetic自信的無襯線字體、克制的強調(diào)色、帶 bylines署名與閱讀時間reading time的真實文章結(jié)構(gòu)。整套模板由以下文件構(gòu)成位于 templates/blog文件/目錄用途astro.config.mjsAstro 配置包含emdash()集成、數(shù)據(jù)庫與存儲src/live.config.tsEmDash loader 注冊樣板代碼勿修改seed/seed.jsonSchema 定義 演示內(nèi)容collections、fields、taxonomies、menus、widgetsemdash-env.d.ts集合的生成類型dev server 啟動時自動重新生成src/layouts/Base.astro基礎(chǔ)布局承載 EmDash 接線菜單、搜索、頁面貢獻(xiàn)src/pages/Astro 頁面——全部服務(wù)端渲染快速啟動兩條命令跑起來CLAUDE.md 給出了最核心的兩條命令pnpm dev # 啟動 Astro 開發(fā)服務(wù)器 npx emdash types # 根據(jù)運行中的站點重新生成 TypeScript 類型配套腳本在 package.json 中定義完整devastro dev、buildastro build、previewastro preview、startnode ./dist/server/entry.mjs、typecheckastro check。其中start表明該模板構(gòu)建后以Node 獨立模式standalone運行。管理后臺Admin UI地址為http://localhost:4321/_emdash/admin。開發(fā)模式下啟動后即可在后臺登錄、寫文章、管理分類標(biāo)簽所有改動實時反映到前臺頁面。類型生成機制npx emdash types會基于運行中的站點即當(dāng)前 seed 的集合與字段定義重新生成 emdash-env.d.ts。這個文件的類型會在 dev server 啟動時自動重新生成因此當(dāng)你修改了 seed 中的字段后重啟開發(fā)服務(wù)器即可獲得帶完整類型提示的查詢 API 體驗。關(guān)鍵文件地圖CLAUDE.md 用一張表概括了核心文件職責(zé)理解它們就等于理解了模板的運行骨架astro.config.mjs— Astro 配置含emdash()集成、數(shù)據(jù)庫和存儲配置src/live.config.ts— EmDash loader 注冊屬于樣板代碼不要修改seed/seed.json— Schema 定義與演示內(nèi)容集合、字段、分類法、菜單、組件區(qū)emdash-env.d.ts— 集合的生成類型src/layouts/Base.astro— 基礎(chǔ)布局含 EmDash 接線菜單、搜索、頁面貢獻(xiàn)src/pages/— 全部服務(wù)端渲染的 Astro 頁面。架構(gòu)核心emdash()集成、數(shù)據(jù)庫與存儲astro.config.mjs 是整個模板的裝配中心import node from astrojs/node; import react from astrojs/react; import auditLog from emdash-cms/plugin-audit-log; import { defineConfig, fontProviders } from astro/config; import emdash, { local } from emdash/astro; import { sqlite } from emdash/db; export default defineConfig({ output: server, adapter: node({ mode: standalone, }), image: { layout: constrained, responsiveStyles: true, }, integrations: [ react(), emdash({ database: sqlite({ url: file:./data.db }), storage: local({ directory: ./uploads, baseUrl: /_emdash/api/media/file, }), plugins: [auditLog], }), ], fonts: [ /* 見下文字體管線 */ ], devToolbar: { enabled: false }, });要點解讀output: server Node adapter這呼應(yīng)了 CLAUDE.md 的硬性規(guī)則——所有內(nèi)容頁面必須服務(wù)端渲染禁止為 CMS 內(nèi)容使用getStaticPaths()emdash()集成接收三類配置database這里用sqlite({ url: file:./data.db })本地開發(fā)默認(rèn) SQLite 單文件數(shù)據(jù)庫storagelocal({ directory: ./uploads, baseUrl: /_emdash/api/media/file })媒體文件存儲在./uploads通過/_emdash/api/media/file對外提供plugins默認(rèn)掛載了emdash-cms/plugin-audit-log審計日志插件這是工作區(qū)內(nèi)的官方插件react()集成用于后臺管理 UI 與評論組件等 React 渲染部分devToolbar: { enabled: false }關(guān)閉了 Astro 默認(rèn)的 dev toolbar。內(nèi)容加載器live.config.tssrc/live.config.ts 定義了 EmDash 的 Live Content Collectionsimport { defineLiveCollection } from astro:content; import { emdashLoader } from emdash/runtime; export const collections { _emdash: defineLiveCollection({ loader: emdashLoader() }), };它建立了_emdash集合覆蓋數(shù)據(jù)庫中所有內(nèi)容類型。頁面中通過getEmDashCollection()與getEmDashEntry()按類型查詢具體內(nèi)容——這正是 CLAUDE.md 要求不要修改的原因它是模板與 EmDash 運行時之間的固定接線。內(nèi)容 Schemaseed.json 決定一切CLAUDE.md 中的 Schema 一節(jié)可以用 seed/seed.json 完整印證。整個文件以$schema聲明、version: 1開頭meta提供元信息然后依次定義settings站點設(shè)置settings: { title: My Blog, tagline: Thoughts on building for the web }CLAUDE.md 指出站點設(shè)置的title和tagline都會渲染在 header / footer 中。模板的 site-identity.ts 會讀取它們并解析出siteTitle、siteTagline、siteLogo。collections集合posts集合字段titlestring必填可搜索——文章標(biāo)題featured_imageimage——頭圖contentportableText可搜索——正文Portable Text 富文本excerpttext——摘要。posts的supports聲明為[drafts, revisions, search, seo]即支持草稿、修訂歷史、全文搜索與 SEO且commentsEnabled: true開啟了評論。pages集合字段titlestring必填可搜索contentportableText可搜索。用于/about等靜態(tài)頁面。taxonomies分類法{ name: category, label: Categories, hierarchical: true, collections: [posts], terms: [...] } { name: tag, label: Tags, hierarchical: false, collections: [posts], terms: [...] }注意name是查詢時使用的精確標(biāo)識如category而非categories——這是 CLAUDE.md 規(guī)則列表中的明確要求。分類是層級化的hierarchical: true標(biāo)簽則扁平。種子數(shù)據(jù)中分類含 development / design / notes標(biāo)簽含 webdev / opinion / tools / creativity。bylines署名bylines: [ { id: byline-editorial, slug: emdash-editorial, displayName: EmDash Editorial }, { id: byline-guest, slug: guest-contributor, displayName: Guest Contributor, isGuest: true } ]文章通過bylines關(guān)聯(lián)作者署名isGuest標(biāo)記客座作者。menus菜單單一的primary菜單默認(rèn)包含 Home、About、Posts 三個自定義鏈接項type: custom。此外 Base.astro 還會嘗試讀取可選的social菜單用于頁腳Connect欄——如果 seed 未定義該欄只顯示 RSS。widgetAreas組件區(qū)seed 定義了sidebar單篇文章頁右側(cè)欄與footer頁腳兩個組件區(qū)sidebar 掛載了core:search搜索、core:categories分類、core:tags標(biāo)簽、core:recent-posts最新文章count: 5、showDate: true、core:archives歸檔月度、limit: 6footer 掛載了一個content類型的小組件渲染一段 Portable Text 簡介。sections區(qū)塊與 content內(nèi)容newsletter-signup與about-author兩個 theme 區(qū)塊帶keywords便于檢索復(fù)用以及 7 篇演示文章 1 篇草稿status: draft草稿不會出現(xiàn)在公開列表和 1 個 About 頁面。演示文章使用$media語法引用外部圖片作為featured_image每篇均聲明了bylines與taxonomies歸屬。頁面與路由每個 URL 都對應(yīng)一個 Astro 文件CLAUDE.md 的 Pages 表列出了模板的完整路由在 src/pages 中一一對應(yīng)頁面路徑內(nèi)容首頁/精選文章 Hero大圖 摘要、最新文章網(wǎng)格全部文章/posts文章計數(shù)、帶摘要與標(biāo)簽徽章的文章列表文章詳情/posts/[slug]頭圖、標(biāo)題、正文、左側(cè)元信息列作者 日期、右側(cè) TOC 搜索 分類欄搜索/search全文搜索 UI頁面/pages/[slug]靜態(tài)頁面內(nèi)容Portable Text分類/category/[slug]按分類過濾的文章標(biāo)簽/tag/[slug]按標(biāo)簽過濾的文章RSS/rss.xml生成的 feed首頁的數(shù)據(jù)查詢模式src/pages/index.astro 是理解模板查詢約定的最佳范例用getEmDashCollection(posts, { orderBy: { published_at: desc }, limit: POSTS_PER_PAGE 1 })讓數(shù)據(jù)庫做切片POSTS_PER_PAGE 7多取 1 條用于判斷是否顯示View all而不是拉全量再在 JS 里裁剪自動挑選第一篇有featured_image的文章作為 Hero其余進(jìn)網(wǎng)格用getTermsForEntries(posts, ids, tag)一次性批量查詢多篇文章的標(biāo)簽避免逐篇調(diào)用getEntryTerms()造成 N1 查詢查完內(nèi)容后立即Astro.cache.set(cacheHint)。文章詳情頁的三欄閱讀布局src/pages/posts/[slug].astro 實現(xiàn)了 CLAUDE.md 強調(diào)的招牌三欄閱讀視圖左側(cè)元信息列--meta-col-width180pxsticky 定位展示 bylines 頭像與署名、發(fā)布時間、閱讀時間、標(biāo)簽中間正文列--content-width680pxPortableText value{post.data.content} /渲染富文本并用Image組件渲染頭圖右側(cè)欄--gutter-width200px客戶端腳本從正文的 h2/h3 構(gòu)建 TOC帶 IntersectionObserver 滾動高亮下方是WidgetArea namesidebar /渲染的側(cè)欄組件區(qū)底部還有Continue reading相關(guān)文章區(qū)塊與Comments/CommentForm評論系統(tǒng)seed 中commentsEnabled: true。頁面還展示了 SEO 的完整鏈路getSeoMeta(post, {...})生成標(biāo)題、描述、OG 圖、canonical、robots再通過getImageUrl()從圖片對象src或meta.storageKey推導(dǎo) OG 回退圖最后以createPublicPageContext()注入 Base 布局。搜索頁走 FTS 而不是 JS 過濾src/pages/search.astro 的注釋點明了設(shè)計意圖調(diào)用 EmDash 的search(query, { collections: [posts], limit: 30 })全文搜索 API由數(shù)據(jù)庫完成分詞、詞干化與排序而不是把全部文章拉到 JS 里過濾——后者在文章數(shù)超過幾百篇后會迅速不可用。返回結(jié)果中的snippet已包含mark高亮標(biāo)簽頁面用set:html渲染。六條硬性規(guī)則來自 CLAUDE.md所有內(nèi)容頁面必須服務(wù)端渲染output: serverCMS 內(nèi)容禁用getStaticPaths()圖片字段是對象{ src, alt }而非字符串必須用emdash/ui的Image image{...} /渲染entry.id是 slug用于 URLentry.data.id是數(shù)據(jù)庫 ULID用于getEntryTerms等 API 調(diào)用查詢內(nèi)容的頁面必須調(diào)用Astro.cache.set(cacheHint)設(shè)置緩存提示查詢中的分類法名稱必須與 seed 的name字段完全一致例如category而不是categories。這些規(guī)則在源碼中都能找到對應(yīng)實現(xiàn)所有頁面均帶cacheHint調(diào)用getTermsForEntries使用entry.data.id頁面跳轉(zhuǎn)鏈接使用p.idslug。視覺系統(tǒng)單字體、單強調(diào)色、三欄文章版式CLAUDE.md 的 Visual character 一節(jié)精確描述了模板的視覺 DNA源碼可在 src/styles/tokens.css 驗證單一字體族全站使用Inter綁定--font-body標(biāo)題默認(rèn)復(fù)用正文字體靠字重與字號建立層級--font-weight-heading600、--font-weight-display700 用于 h1/頁標(biāo)題h1/h2 收緊字距--tracking-tight/--tracking-snugJetBrains Mono綁定--font-mono用于行內(nèi)代碼與代碼塊品牌色#0066cc--color-brand用于鏈接、文章卡片標(biāo)題 hover 與搜索框 focus 光環(huán)另有--color-text-secondary與--color-muted用于次級文本與元信息。不要添加第二個強調(diào)色文章三欄版式是標(biāo)志性功能左欄元信息、中間 680px 正文、右欄搜索 TOC 分類。桌面端不要把它壓成一欄——這個布局在向讀者傳遞這是值得閱讀的內(nèi)容。深色模式與主題切換tokens.css 中所有顏色都用light-dark(light, dark)定義同一個 token 同時攜帶明暗兩套值無需維護(hù)單獨的暗色面板。Base.astro 的內(nèi)聯(lián)腳本會在頁面渲染前立即根據(jù)themecookie 應(yīng)用主題防止閃爍頁腳提供 light / dark / system 三個切換按鈕通過寫themecookie 與給html加 class 實現(xiàn)。此外還有針對不支持light-dark()的舊瀏覽器Safari 17.5、Chrome 123的純亮色回退塊。定制化token 覆蓋、字體管線與 CSS 變量清單設(shè)計 token 的分層覆蓋機制CLAUDE.md 明確指出設(shè)計 token 的默認(rèn)值全部在src/styles/tokens.css而重新?lián)Q膚應(yīng)該改src/styles/theme.css——因為 theme.css 中的聲明是**無分層unlayered**的永遠(yuǎn)壓過layer base的默認(rèn)值無需技巧性的選擇器優(yōu)先級對抗。不要為了視覺改動而去編輯tokens.css或Base.astro。theme.css 的注釋給出了示例:root { --color-brand: light-dark(#0f766e, #2dd4bf); --font-heading: Iowan Old Style, Georgia, serif; --radius: 8px; }覆蓋顏色的兩條規(guī)則用純色值覆蓋會同時改變明暗兩套模式想保持明暗區(qū)分就用light-dark(light, dark)覆蓋。字體管線astro.config.mjs 的 fonts 配置Webfont 在 astro.config.mjs 的fonts:數(shù)組中配置fonts: [ { provider: fontProviders.google(), name: Inter, cssVariable: --font-body, weights: [400, 500, 600, 700], fallbacks: [sans-serif], }, { provider: fontProviders.google(), name: JetBrains Mono, cssVariable: --font-mono, weights: [400, 500], fallbacks: [monospace], }, ],換正文襯線字體的操作是修改綁定cssVariable: --font-body的條目的name。CLAUDE.md 推薦的無襯線替代Geist、IBM Plex Sans、S?hne需授權(quán)、Public Sans如果想要襯線正文博客可換 Source Serif、Crimson Pro 或 Lora——但換襯線后要把--font-size-base提到1.0625rem以?？勺x性。若只想讓標(biāo)題用別的字體或改用系統(tǒng)字體而不碰字體管線直接在 theme.css 覆蓋--font-heading或--font-body即可。Base.astro 通過Font cssVariable--font-body preload /加載并預(yù)取字體。值得掌握的 CSS 變量完整列表見 tokens.css品牌與配色--color-brand、--color-brand-hover、--color-on-brand、--color-brand-ring頁面配色--color-bg、--color-bg-subtle、--color-surface、--color-text、--color-text-secondary、--color-muted、--color-border、--color-border-subtle字體--font-body、--font-heading、--font-mono字重--font-weight-heading600/--font-weight-display700——換襯線時可調(diào)低字距--tracking-tight/--tracking-snug/--tracking-wide/--tracking-wider用于標(biāo)題與元信息標(biāo)簽布局--content-width680px正文列、--wide-width1200px最大容器、--gutter-width200px文章頁右側(cè) TOC 欄、--meta-col-width180px文章頁左側(cè)元信息列頭像--avatar-size-{xs,sm,md,lg}對應(yīng)卡片、列表、精選、單篇文章等不同尺度的 byline 頭像。值得留意的是 tokens.css 中的全套字號階梯--font-size-xs到--font-size-5xl、行高--leading-tight到--leading-relaxed、間距--spacing-1到--spacing-24與陰影 token--shadow-sm/--shadow-lg它們共同支撐了整套版式的統(tǒng)一性。反向清單不要做什么CLAUDE.md 的 What not to do 是一份極具實操價值的邊界清單不要添加第二個強調(diào)色或彩色區(qū)塊背景——頁面應(yīng)該是黑、白、一種藍(lán)不要用展示型無襯線體Bebas、Anton 等替換 Inter——標(biāo)題層級靠字重而非新奇字體不要在桌面端折疊文章側(cè)欄——它是閱讀體驗的一部分不要用模板式博客文案Welcome to my blog、Stay tuned for more——寫一句真正說明這個博客是干什么的 tagline不要用三篇一模一樣的占位文章填充首頁——只有一篇真實文章就展示一篇不要在沒有審核計劃時開啟評論——模板默認(rèn)不附帶評論系統(tǒng)是有原因的。Agent 技能與文檔接入面向 AI 編碼工具CLAUDE.md 的 Skills 與 Documentation 兩節(jié)面向 AI Agent 場景但同樣值得人類開發(fā)者了解技能存放于.agents/skills/按任務(wù)加載building-emdash-site內(nèi)容查詢、Portable Text 渲染、Schema 設(shè)計、seed 文件、菜單/組件區(qū)/搜索/SEO/評論/byline 等站點特性建議從這里開始、creating-plugins用 hooks、storage、admin UI、API routes 與 Portable Text block 類型構(gòu)建插件、emdash-cli內(nèi)容管理、seed、類型生成與可視化編輯流程的 CLI 命令EmDash 文檔以 MCP server 形式提供模板自帶了.mcp.json、.cursor/mcp.json、.vscode/mcp.json使 Claude Code、Cursor、VS Code 能自動發(fā)現(xiàn)文檔服務(wù)器其他工具OpenCode、Windsurf 等需要一次性手動配置。延伸閱讀模板根說明templates/blog/README.md若存在Agent 模板約定templates/blog/AGENTS.md 與 templates/blog/AGENTS-template.md版本變更記錄templates/blog/CHANGELOG.md同系列云托管模板templates/blog-cloudflareCloudflare Workers 版本以及 marketing、portfolio、starter 等姊妹模板見 templates全倉庫技能庫skills/building-emdash-site/SKILL.md、skills/creating-plugins/SKILL.md、skills/emdash-cli/SKILL.md贊分享CMS后端前端插件系統(tǒng)【免費下載鏈接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress項目地址https://gitcode.com/gh_mirrors/emdas/emdash點擊查看免費下載相關(guān)推薦EmDash 博客模板深度指南基于 Astro 的全棧 CMS 站點搭建與定制EmDash 博客模板深度指南基于 Astro 的全棧 CMS 站點搭建與定制 EmDash 是一個基于 Astro 構(gòu)建的全棧 TypeScript CMSCMS后端前端插件系統(tǒng)EmDash 博客模板Cloudflare 版實戰(zhàn)指南基于 Astro D1 R2 的編輯器優(yōu)先 CMS 站點搭建EmDash 博客模板Cloudflare 版實戰(zhàn)指南基于 Astro D1 R2 的編輯器優(yōu)先 CMS 站點搭建 本指南圍繞 EmDash 官方CMS后端前端插件系統(tǒng)EmDash Blank 模板實戰(zhàn)基于 Astro 從零搭建無預(yù)設(shè) CMS 站點的最小基底EmDash Blank 模板實戰(zhàn)基于 Astro 從零搭建無預(yù)設(shè) CMS 站點的最小基底 導(dǎo)讀 templates/blank 是 EmDash一個構(gòu)建在CMS后端前端插件系統(tǒng)創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考