PureStack：TypeScript 原生的前端静态站点框架

你的内容。你的组件。一条流水线。

PureStack 将内容目录转换为静态网站。用 Markdown 或 Regor MDX 编写页面，在有用之处使用内置组件，仅在页面需要行为时添加浏览器端 TypeScript。CLI 负责路由、样式、资源、开发预览和发布构建。

PureStack 实践： purestack.studio 由本仓库中的前端源码构建而成。

为什么连贯的源码很重要

生成第一个页面只是开始。产品会不断变化：新内容、新组件、新行为，以及新加入的人。

PureStack 的架构赌注是：显式、带类型的源码能让这种持续的工作更容易被人类和 AI 工具检查和推理。内容保留在 Markdown 中；组件、样式构建器和脚本位于 TypeScript 中。目标是建立一个随着产品成长仍保持可理解的源码模型。

.mdx 和 .rmdx 页面使用 Regor 组件和表达式。纯 .md 文件适用于散文页面。有关标记和浏览器应用模型，请参阅 Regor 指南。

让你的第一个页面运行起来

1. 创建项目

mkdir my-site
cd my-site
npm init -y
npm install purestack
mkdir content

2. 添加配置和页面

你的起点只有两个文件：

my-site/
└── content/
    ├── siteConfig.json
    └── index.mdx

content/siteConfig.json

{
  "siteTitle": "My Site",
  "logo": { "brand": "My Site", "href": "/" },
  "outDir": "../dist/site",
  "publishDir": "../dist/publish"
}

content/index.mdx

---
title: Welcome
description: My first PureStack site.
template: doc
---

# Make something worth reading.

Start with Markdown. Add components when your page needs more.

<Panel tone="info" variant="surface">
  <p>Your first PureStack page, ready to make your own.</p>
</Panel>

3. 预览

npx purestack serve --content ./content

打开 http://127.0.0.1:4173/。添加 content/about.mdx 以创建 /about/。服务器会监视你的文件，并在你编辑时重新加载浏览器。

4. 为你的主机构建

npx purestack build --content ./content
npx purestack publish --content ./content

build 写入 dist/site。publish 在 dist/publish 中创建一个干净、压缩的产物；它准备部署文件但不会上传它们。两条路径都来自 siteConfig.json，并相对于 content 解析。

对于浏览器行为，在页面旁边添加一个 TypeScript 文件，并用 <PageScript src="./example.ts" /> 加载它。purestack 包 README 有一个完整的示例。

选择你的下一步

PureStack 如何协同工作

CLI 指南 涵盖命令和选项。站点配置 涵盖导航、主题、搜索、站点地图、本地化和输出路径。

仓库地图

工作区包含 CLI、站点生成器、UI 组件、带类型的 HTML/CSS 构建器、浏览器脚本、图标提供程序和私有 VS Code 扩展。

探索包和源码目录

其余工作区包提供共享类型、工具函数、渲染和 DOM 支持。

开发此仓库

有关分支、拉取请求、CI 和发布工作流，请参阅 Contributing。

使用 Node.js 24 以及 package.json 中固定的 Yarn 版本。 从仓库根目录运行命令：

corepack enable
yarn install --immutable
yarn build
yarn dev

yarn dev 用于提供包含的示例站点。若要开发 PureStack 网站， 请运行 yarn frontend；其开发服务器在 http://127.0.0.1:4700/ 打开。有关站点特定的工作流，请参阅 前端 README。