Siteforge 文档

Get started

先跑通站点，再进入主题

Siteforge 的使用路径和主流文档站类似：先确认站点级配置和内容目录，再按页面类型进入主题层。这样普通内容维护者只需要理解 Markdown 和 YAML，开发者则可以在主题边界内完成产品介绍页、文档页和交互组件。

config.yml content/ themes/<name> dist

Direct use

直接使用

只写博客或维护普通内容站时，不需要先理解主题开发。按这个路径走：

克隆项目。git clone https://github.com/jsw-teams/siteforge.git
进入目录。cd siteforge
安装依赖。npm install
先做检查。npm run check 用来确认当前输出、主题资源和发现入口是健康的。
生成静态文件。npm run generate 类似 hexo generate / hexo g。
本地预览。npm run server 类似 hexo server / hexo s，默认地址是 http://127.0.0.1:4173/。

git clone https://github.com/jsw-teams/siteforge.git

cd siteforge

npm install

npm run check

npm run generate

npm run server

改 config.yml：站点名、描述、作者、语言、导航、页脚、robots、llms、feed、插件开关和 discovery 信息都放这里。

改 content/posts/：新增或编辑文章。

改 content/pages/：调整首页、关于页、归档页、分类页、标签页、搜索页或其他普通页面。

本地预览每 10 秒监听 content/、themes/、src/、static/、config.yml 和 astro.config.mjs，构建出错时预览进程不会退出。

npm run check 检查 dist/、主题资源、sitemap、feed、Agent discovery 和 WebMCP bootstrap。PowerShell 执行策略阻止 npm.ps1 时，改用 npm.cmd run server、npm.cmd run generate 和 npm.cmd run check。

你会改哪些文件

先从 config.yml 开始：站点名、多语言、导航、robots、llms、feed、discovery 和第三方脚本都可以在这里变成结构化输入。

内容放进 content/：普通页面用 content/pages，多篇产品文档用 content/docs，文章或镜像内容继续放在对应内容目录。

主题放进 themes/<name>：产品介绍页的视觉、文档页的左侧导航、搜索页样式、consent、lightbox、轮播和页脚都应该先在主题层解决。

Documentation

按阶段阅读文档

开始使用 Siteforge 文档 从站点配置、内容目录、主题扩展到 Agent discovery 的 Siteforge 入门路径。基本操作 页面与动态 slot 用 content/pages 和 Siteforge slot 低成本定制首页、搜索页和其他特殊页面。部署 部署与发布 生成静态文件，检查 dist 输出，并确认部署前的站务资源。自定义 自定义默认主题 默认主题可直接使用；需要品牌化时先替换内容与 source-assets。二次开发 主题开发边界 按 Siteforge 的 theme-first workflow 开发产品介绍与文档站主题。其他 疑难杂症 预留给常见问题、异常排查和使用边界。

Quality baseline

从默认主题开始，不从空白页开始

README 附带了可复核的 PageSpeed 与 Agent 检查结果：桌面端性能、无障碍、最佳做法、SEO 全 100，移动端性能 98，Cloudflare Agent 检查通过。二次开发时可以把这些报告当作主题改造后的回归基线。