meowpress 0.1.1-alpha.0 → 0.2.0-alpha.0

package/README.md

@@ -1,19 +1,19 @@
 # Meowpress
 
-`meowpress` 提供静态站点的内容读取、页面渲染、主题和构建流程。
-消费者持有站点配置与内容，通过本包构建；本包不持有应用的文章或输出目录。
+`meowpress` provides content reading, page rendering, themes and the build pipeline for static sites.
+Consumers own the site configuration and content and build through this package; the package does not own the application's posts or output directory.
 
-当前准备 `0.1.1-alpha.0` 本地候选，尚未发布该版本。CSS 与 JSX 均为必需 peer，允许 `^0.1.0 || ^0.1.1-alpha.0`，保留稳定版兼容范围，并接受本轮 JSX/CSS alpha。宿主选定共享的 CSS/JSX 模块，本包不私装另一份 CSS；不依赖 Meowtail 或 MeowSlides。实际包外构建与主题身份验收绑定精确 tgz，不通过 override 绕过 peer 合同。发布仍需独立明确授权。
+Published history: `0.1.1-alpha.0` was accepted from the registry, followed by `0.1.1-alpha.1` with the English site and CLI defaults; `latest` remained `0.1.0`. The current workspace package is `0.2.0-alpha.0`, and its required CSS and JSX peer ranges accept `^0.2.0-alpha.0`. The host selects the shared CSS/JSX modules, and this package does not privately install another CSS copy; it does not depend on Meowtail or MeowSlides. Out-of-package builds and theme identity acceptance are bound to exact package archives, and peer contracts are not bypassed through overrides. Publishing requires separate explicit authorization.
 
-本包是独立内容发布库，源码位于 `packages/meowpress`，已有公开构建入口、独立测试与类型检查，
-不依赖 Assistant、WorkCell、Deno 或特定 Blog 的内容与运行状态。样式生成来自 `meowcss`，
-HTML 渲染来自 `meowjsx/web`，无需安装 MeowUI。
+This package is a standalone content publishing library with source in `packages/meowpress`; it already has a public build entry, independent tests and typechecking,
+and does not depend on Assistant, WorkCell, Deno or the content and runtime state of a specific Blog. Style generation comes from `meowcss`,
+and HTML rendering comes from `meowjsx/web`; MeowUI does not need to be installed.
 
-## 入口
+## Entries
 
-- `meowpress/build`：`meowSite()` 定义配置，`buildSite()` 执行构建；这是唯一对外 export。
-  内容读取、页面渲染、技能索引与主题是包内模块。
-- `meowpress --config ./site.config.ts`：Bun CLI，加载消费者提供的配置并构建。
+- `meowpress/build`: `meowSite()` defines configuration and `buildSite()` performs the build; this is the only public export.
+  Content reading, page rendering, skill indexing and themes are internal package modules.
+- `meowpress --config ./site.config.ts`: Bun CLI that loads the consumer-provided configuration and builds.
 
 ```ts
 import { meowSite } from "meowpress/build";
@@ -25,31 +25,62 @@ export default meowSite({
 });
 ```
 
-配置中的目录由应用明确提供；默认主题从本包解析，不依赖启动目录。
-可通过 `theme: defineTheme(...)` 替换整套主题；所有静态页面输出该主题的根属性和默认选项。
-构建将 `theme.cssText` 写入临时 CSS，再由 Bun 处理字体与其他资源，最终通过 stylesheet 链接交付，
-无需客户端 JavaScript 即可应用主题。默认字体 Geist 的文件随站点打包，不依赖外部字体服务。
-使用默认字体时，输出同时包含 `licenses/geist-OFL.txt`，保留字体的 SIL OFL 许可。
-默认插画使用包内矢量与 CSS，不要求业务图片。可用 `site.images` 的 `hero`、`feed`、`about`
-显式设置装饰图路径，例如 `images/cover.svg`；路径相对内容根的 `assets/`，库负责各页面深度，
-资源沿现有资产构建流程交付。未设置 About 图片时使用站点名首字母。
-内容源包含 `posts/`、`thoughts/` 和可选资源；以下划线开头的草稿不进入发布输出。
-站点有自己的主题，不隐式安装 MeowUI 的应用主题。
+## Pages a consumer owns
 
-## 验证与构建
+A consumer that supplies `pages` owns the whole site map. The provider receives the content that was
+already loaded and returns complete documents; the package writes them at their paths, adds them to
+the agent-facing indexes, and does not publish its own blog routes next to them. One site map, one
+owner.
 
-安装 `meowpress` 及其 `meowcss`、`meowjsx` 依赖后，在消费者目录运行：
+```ts
+import { meowSite, type SitePage } from "meowpress/build";
+
+export default meowSite({
+  content: [{ directory: "/path/to/content" }],
+  outputDirectory: "/path/to/dist",
+  themeStylesheet: "site-theme.css",
+  pages: ({ posts, theme }): SitePage[] =>
+    posts.map((post) => ({
+      path: post.slug,
+      title: post.title,
+      html: renderDocument(post, theme),
+    })),
+});
+```
+
+- `pages` is a provider of complete HTML documents. A path that resolves above the site root is
+  refused rather than clamped.
+- `mdxComponents` adds named components to the MDX content pages; the built-in `Callout` stays
+  available.
+- `themeStylesheet` names the theme stylesheet the build writes, so a consumer page can link it. It
+  applies to the built-in pages as well, so a renamed stylesheet never leaves a page linking a file
+  that was not written.
+
+Directories in the configuration are provided explicitly by the application; the default theme resolves from this package and does not depend on the startup directory.
+The whole theme can be replaced with `theme: defineTheme(...)`; all static pages output that theme's root attributes and default options.
+The build writes `theme.cssText` to a temporary CSS file, then lets Bun handle fonts and other assets, and finally delivers through a stylesheet link,
+so the theme applies without client-side JavaScript. Files for the default Geist font are bundled with the site and do not depend on an external font service.
+When the default font is used, the output also includes `licenses/geist-OFL.txt`, preserving the font's SIL OFL license.
+Default illustrations use in-package vectors and CSS and require no business images. The `hero`, `feed` and `about` keys of `site.images`
+can explicitly set decorative image paths, for example `images/cover.svg`; paths are relative to the content root's `assets/`, the library handles each page depth,
+and assets are delivered along the existing asset build flow. When no About image is set, the first letter of the site name is used.
+The content source contains `posts/`, `thoughts/` and optional assets; drafts whose names start with an underscore do not enter the published output.
+The site has its own theme and does not implicitly install MeowUI's application theme.
+
+## Verification and build
+
+After installing `meowpress` and its `meowcss` and `meowjsx` dependencies, run in the consumer directory:
 
 ```sh
 bunx --no-install meowpress --config ./site.config.ts
 ```
 
-CLI 需要 Bun，输出位置由 `outputDirectory` 决定。字体文件从本包的正式 Geist 依赖解析，
-不要求消费者复制源码、安装工作区根依赖或访问外部字体服务。
+The CLI requires Bun, and the output location is determined by `outputDirectory`. Font files resolve from this package's official Geist dependency,
+and consumers are not required to copy source, install workspace-root dependencies or access an external font service.
 
-## 独立验证
+## Independent verification
 
-仓库依赖就绪后运行 `bun run --cwd packages/meowpress test` 和
-`bun run --cwd packages/meowpress typecheck`。测试位于 `tests/unit/`；真实构建测试通过公开
-`meowpress/build` 入口创建临时内容、主题和图片，
-覆盖 Markdown、MDX、Thought 输出及草稿页面/资产排除，不读取 Blog 内容或调用 Blog 构建。
+Once repository dependencies are ready, run `bun run --cwd packages/meowpress test` and
+`bun run --cwd packages/meowpress typecheck`. Tests live in `tests/unit/`; real build tests create temporary content, themes and images through the public
+`meowpress/build` entry,
+covering Markdown, MDX, Thought output and draft page/asset exclusion, without reading Blog content or invoking the Blog build.

package/dist/src/build.d.ts

@@ -1,6 +1,10 @@
 import { type ThemeDefinition } from "meowcss";
 import { type SiteIdentity } from "./identity.js";
-import { type ContentSourceInput } from "./content.js";
+import { type ContentSourceInput, type MdxComponent } from "./content.js";
+import { type SitePageProvider } from "./pages.js";
+export type { SitePage, SitePageContext, SitePageProvider } from "./pages.js";
+export type { ContentItem } from "./content.js";
+export type { SiteIdentity } from "./identity.js";
 export interface SiteConfig {
     /** One or more roots containing `posts/`, `thoughts/`, and optional assets. */
     content: ContentSourceInput | readonly ContentSourceInput[];
@@ -14,6 +18,12 @@ export interface SiteConfig {
     projectRootDirectory?: string;
     /** Site name, description, repository links and About copy; unset fields use neutral defaults. */
     site?: Partial<SiteIdentity>;
+    /** Consumer-supplied pages; the site writes and indexes them next to its own. */
+    pages?: SitePageProvider;
+    /** Extra components available to MDX content pages. */
+    mdxComponents?: Record<string, MdxComponent>;
+    /** Stylesheet file name for the theme; defaults to "blog-theme.css". */
+    themeStylesheet?: string;
 }
 export interface ResolvedSiteConfig {
     content: readonly ContentSourceInput[];
@@ -22,6 +32,9 @@ export interface ResolvedSiteConfig {
     theme: ThemeDefinition;
     projectRootDirectory?: string;
     site: SiteIdentity;
+    pages?: SitePageProvider;
+    mdxComponents: Record<string, MdxComponent>;
+    themeStylesheet: string;
 }
 /** Define a site config in the app package without taking on the build pipeline. */
 export declare function meowSite(config: SiteConfig): ResolvedSiteConfig;

package/dist/src/build.js

@@ -1,11 +1,12 @@
 import { blogTheme } from "./theme.js";
 import { DEFAULT_SITE } from "./identity.js";
 import { mkdir, rm, writeFile, cp } from "node:fs/promises";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { collectContentAssets, isDraftAsset, loadSection, normalizeContentSources, } from "./content.js";
-import { aboutPage, agentMarkdown, homePage, listPage, llmText, postPage, skillPage, skillsIndexPage, thoughtPage, } from "./site.js";
+import { aboutPage, agentMarkdown, DEFAULT_THEME_STYLESHEET, homePage, listPage, llmText, postPage, skillPage, skillsIndexPage, thoughtPage, } from "./site.js";
 import { loadSkills } from "./skills.js";
+import { sitePageFile } from "./pages.js";
 /** Define a site config in the app package without taking on the build pipeline. */
 export function meowSite(config) {
     return {
@@ -17,6 +18,9 @@ export function meowSite(config) {
             ? resolve(config.projectRootDirectory)
             : undefined,
         site: { ...DEFAULT_SITE, ...config.site },
+        pages: config.pages,
+        mdxComponents: config.mdxComponents ?? {},
+        themeStylesheet: config.themeStylesheet ?? DEFAULT_THEME_STYLESHEET,
     };
 }
 async function writePage(generatedDirectory, pathname, html) {
@@ -58,13 +62,30 @@ async function buildStaticHtmlFromEntrypoints(entrypoints, generatedDirectory, o
         throw new Error("Unable to build site static HTML");
     }
 }
-async function writeContentPages(generatedDirectory, posts, thoughts, theme, site) {
+/** Consumer pages are written inside the generated directory and never above it. */
+function consumerPageFile(generatedDirectory, path) {
+    const file = sitePageFile(path);
+    const target = resolve(generatedDirectory, file);
+    const inside = relative(generatedDirectory, target);
+    if (!inside || inside.startsWith("..") || isAbsolute(inside)) {
+        throw new Error(`Site page path stays inside the site root: ${path}`);
+    }
+    return file;
+}
+async function writeConsumerPages(generatedDirectory, pages) {
+    const entrypoints = [];
+    for (const page of pages) {
+        entrypoints.push(await writePage(generatedDirectory, consumerPageFile(generatedDirectory, page.path), page.html));
+    }
+    return entrypoints;
+}
+async function writeContentPages(generatedDirectory, posts, thoughts, theme, site, stylesheet) {
     const entrypoints = [];
     for (const post of posts) {
-        entrypoints.push(await writePage(generatedDirectory, `posts/${post.slug}/index.html`, postPage(post, posts, thoughts, theme, site)));
+        entrypoints.push(await writePage(generatedDirectory, `posts/${post.slug}/index.html`, postPage(post, posts, thoughts, theme, site, stylesheet)));
     }
     for (const thought of thoughts) {
-        entrypoints.push(await writePage(generatedDirectory, `thoughts/${thought.slug}/index.html`, thoughtPage(thought, theme, site)));
+        entrypoints.push(await writePage(generatedDirectory, `thoughts/${thought.slug}/index.html`, thoughtPage(thought, theme, site, stylesheet)));
     }
     return entrypoints;
 }
@@ -72,30 +93,47 @@ export async function buildSite(input) {
     const config = meowSite(input);
     const generatedDirectory = resolve(config.outputDirectory, "../.generated");
     const [posts, thoughts, skills] = await Promise.all([
-        loadSection(config.content, "post"),
-        loadSection(config.content, "thought"),
-        loadSkills(config.skillsDirectory, {
-            projectRootDirectory: config.projectRootDirectory,
-        }),
+        loadSection(config.content, "post", { components: config.mdxComponents }),
+        loadSection(config.content, "thought", { components: config.mdxComponents }),
+        config.pages
+            ? Promise.resolve([])
+            : loadSkills(config.skillsDirectory, {
+                projectRootDirectory: config.projectRootDirectory,
+            }),
     ]);
     const timeline = [...posts, ...thoughts].sort((left, right) => (right.date?.getTime() ?? 0) - (left.date?.getTime() ?? 0));
     await rm(config.outputDirectory, { recursive: true, force: true });
     await rm(generatedDirectory, { recursive: true, force: true });
     await mkdir(config.outputDirectory, { recursive: true });
     await mkdir(generatedDirectory, { recursive: true });
-    const entrypoints = await Promise.all([
-        writePage(generatedDirectory, "index.html", homePage(timeline, config.theme, config.site)),
-        writePage(generatedDirectory, "about/index.html", aboutPage(config.theme, config.site)),
-        writePage(generatedDirectory, "posts/index.html", listPage("post", posts, config.theme, config.site)),
-        writePage(generatedDirectory, "thoughts/index.html", listPage("thought", thoughts, config.theme, config.site)),
-        writePage(generatedDirectory, "skills/index.html", skillsIndexPage(skills, config.theme, config.site)),
-    ]);
-    entrypoints.push(...(await writeContentPages(generatedDirectory, posts, thoughts, config.theme, config.site)));
-    for (const skill of skills) {
-        const skillPath = skill.scope === "public" ? `skills/${skill.slug}` : `skills/project/${skill.slug}`;
-        entrypoints.push(await writePage(generatedDirectory, `${skillPath}/index.html`, skillPage(skill, config.theme, config.site)));
+    // A consumer that supplies its own pages owns the whole site map; the package's
+    // own blog routes are not published alongside them.
+    const pages = config.pages
+        ? await config.pages({
+            posts,
+            thoughts,
+            site: config.site,
+            theme: config.theme,
+        })
+        : undefined;
+    const entrypoints = [];
+    if (pages) {
+        entrypoints.push(...(await writeConsumerPages(generatedDirectory, pages)));
+    }
+    else {
+        entrypoints.push(...(await Promise.all([
+            writePage(generatedDirectory, "index.html", homePage(timeline, config.theme, config.site, config.themeStylesheet)),
+            writePage(generatedDirectory, "about/index.html", aboutPage(config.theme, config.site, config.themeStylesheet)),
+            writePage(generatedDirectory, "posts/index.html", listPage("post", posts, config.theme, config.site, config.themeStylesheet)),
+            writePage(generatedDirectory, "thoughts/index.html", listPage("thought", thoughts, config.theme, config.site, config.themeStylesheet)),
+            writePage(generatedDirectory, "skills/index.html", skillsIndexPage(skills, config.theme, config.site, config.themeStylesheet)),
+        ])), ...(await writeContentPages(generatedDirectory, posts, thoughts, config.theme, config.site, config.themeStylesheet)));
+        for (const skill of skills) {
+            const skillPath = skill.scope === "public" ? `skills/${skill.slug}` : `skills/project/${skill.slug}`;
+            entrypoints.push(await writePage(generatedDirectory, `${skillPath}/index.html`, skillPage(skill, config.theme, config.site, config.themeStylesheet)));
+        }
     }
-    await writeFile(join(generatedDirectory, "blog-theme.css"), config.theme.cssText.replaceAll('"@fontsource-variable/geist"', JSON.stringify(fileURLToPath(import.meta.resolve("@fontsource-variable/geist")))), "utf8");
+    await writeFile(join(generatedDirectory, config.themeStylesheet), config.theme.cssText.replaceAll('"@fontsource-variable/geist"', JSON.stringify(fileURLToPath(import.meta.resolve("@fontsource-variable/geist")))), "utf8");
     await stageAssets(generatedDirectory, config.content);
     await buildStaticHtmlFromEntrypoints(entrypoints, generatedDirectory, config.outputDirectory);
     if (config.theme.cssText.includes('"@fontsource-variable/geist"')) {
@@ -105,10 +143,12 @@ export async function buildSite(input) {
     }
     await copyPostAssets(config.outputDirectory, config.content);
     await Promise.all([
-        writeFile(join(config.outputDirectory, "llm.txt"), llmText(posts, thoughts, config.site), "utf8"),
-        writeFile(join(config.outputDirectory, "llms.txt"), llmText(posts, thoughts, config.site), "utf8"),
-        writeFile(join(config.outputDirectory, "agents.md"), agentMarkdown(posts, thoughts, config.site), "utf8"),
+        writeFile(join(config.outputDirectory, "llm.txt"), llmText(posts, thoughts, config.site, pages), "utf8"),
+        writeFile(join(config.outputDirectory, "llms.txt"), llmText(posts, thoughts, config.site, pages), "utf8"),
+        writeFile(join(config.outputDirectory, "agents.md"), agentMarkdown(posts, thoughts, config.site, pages), "utf8"),
     ]);
     await rm(generatedDirectory, { recursive: true, force: true });
-    console.log(`Built ${posts.length} posts and ${thoughts.length} thoughts into site dist/.`);
+    console.log(pages
+        ? `Built ${posts.length} content items and ${pages.length} site pages into site dist/.`
+        : `Built ${posts.length} posts and ${thoughts.length} thoughts into site dist/.`);
 }

package/dist/src/content.d.ts

@@ -1,3 +1,4 @@
+import { type Child, type Props } from "meowjsx/runtime";
 export type ContentKind = "post" | "thought";
 export type Frontmatter = Record<string, unknown>;
 /** A content root containing `posts/`, `thoughts/`, and optional asset folders. */
@@ -11,7 +12,11 @@ export type DuplicateContentPolicy = "first-wins" | "error";
 export interface LoadSectionOptions {
     /** The first source wins by default, so the source order is an explicit overlay order. */
     duplicate?: DuplicateContentPolicy;
+    /** Extra components available to MDX content pages. */
+    components?: Record<string, MdxComponent>;
 }
+/** A component an MDX content page may use by name. */
+export type MdxComponent = (props: Props) => Child;
 export interface ContentItem {
     kind: ContentKind;
     slug: string;

package/dist/src/content.js

@@ -112,7 +112,7 @@ function Callout(props) {
 const MDX_COMPONENTS = {
     Callout,
 };
-async function renderMdx(source) {
+async function renderMdx(source, components) {
     const compiled = await compile({ value: source }, {
         outputFormat: "function-body",
         remarkPlugins: [remarkGfm],
@@ -123,15 +123,15 @@ async function renderMdx(source) {
         jsxs: h,
     });
     const component = module.default;
-    return renderToHtml(component({ components: MDX_COMPONENTS }));
+    return renderToHtml(component({ components: { ...MDX_COMPONENTS, ...components } }));
 }
-async function renderSource(source, sourcePath) {
+async function renderSource(source, sourcePath, components) {
     if (sourcePath.endsWith(".md")) {
         return Bun.markdown.html(source, {
             tagFilter: true,
         });
     }
-    return renderMdx(source);
+    return renderMdx(source, components);
 }
 async function collectFiles(directory) {
     const entries = await readdir(directory, { withFileTypes: true });
@@ -186,7 +186,7 @@ export function normalizeContentSources(input) {
 function duplicateContentError(kind, slug) {
     return new Error(`Duplicate ${kind} slug "${slug}" while merging content sources.`);
 }
-async function loadSectionFromSource(source, kind) {
+async function loadSectionFromSource(source, kind, options) {
     const sectionDirectory = resolve(source.directory, `${kind}s`);
     let sourceFiles;
     try {
@@ -217,7 +217,7 @@ async function loadSectionFromSource(source, kind) {
         const bodyWithoutLeadingHeading = document.body.replace(/^\s*#\s+.+?(?:\r?\n|$)+/, "");
         const plainText = stripMarkdown(bodyWithoutLeadingHeading);
         const title = asText(document.metadata.title) ?? titleFromBody(document.body, slug);
-        const html = withoutLeadingHeading(await renderSource(document.body, sourcePath));
+        const html = withoutLeadingHeading(await renderSource(document.body, sourcePath, options.components ?? {}));
         items.push({
             kind,
             slug,
@@ -241,7 +241,7 @@ export async function loadSection(sources, kind, options = {}) {
     const merged = new Map();
     const duplicatePolicy = options.duplicate ?? "first-wins";
     for (const source of normalizeContentSources(sources)) {
-        const items = await loadSectionFromSource(source, kind);
+        const items = await loadSectionFromSource(source, kind, options);
         for (const item of items) {
             if (merged.has(item.slug)) {
                 if (duplicatePolicy === "error")

package/dist/src/identity.js

@@ -1,6 +1,6 @@
 export const DEFAULT_SITE = {
     name: "Meowpress site",
     id: "meowpress",
-    description: "长文与碎片想法的混排时间线。",
+    description: "A mixed timeline of long-form posts and fragmentary thoughts.",
     contentDirectory: "content",
 };

package/dist/src/pages.d.ts

@@ -0,0 +1,28 @@
+import type { ThemeDefinition } from "meowcss";
+import type { ContentItem } from "./content.js";
+import type { SiteIdentity } from "./identity.js";
+/** A page supplied by the consumer of the site. */
+export interface SitePage {
+    /** Route path below the site root; "packages/meowtail" becomes /packages/meowtail/. */
+    path: string;
+    title: string;
+    /** A complete HTML document for the route. */
+    html: string;
+    description?: string;
+    /** Grouping used by the site index and the agent-facing indexes. */
+    group?: string;
+    order?: number;
+}
+/** What a page provider receives when the site is built. */
+export interface SitePageContext {
+    posts: readonly ContentItem[];
+    thoughts: readonly ContentItem[];
+    site: SiteIdentity;
+    theme: ThemeDefinition;
+}
+/** Supplies the consumer's own pages for the site. */
+export type SitePageProvider = (context: SitePageContext) => readonly SitePage[] | Promise<readonly SitePage[]>;
+/** The route a page is published under, with a leading and a trailing slash. */
+export declare function sitePageUrl(path: string): string;
+/** The output file a page is written to, relative to the site root. */
+export declare function sitePageFile(path: string): string;

package/dist/src/pages.js

@@ -0,0 +1,10 @@
+/** The route a page is published under, with a leading and a trailing slash. */
+export function sitePageUrl(path) {
+    const normalized = path.replace(/^\/+|\/+$/g, "");
+    return normalized ? `/${normalized}/` : "/";
+}
+/** The output file a page is written to, relative to the site root. */
+export function sitePageFile(path) {
+    const normalized = path.replace(/^\/+|\/+$/g, "");
+    return normalized ? `${normalized}/index.html` : "index.html";
+}

package/dist/src/site.d.ts

@@ -1,13 +1,16 @@
 import { type ThemeDefinition } from "meowcss";
 import { type ContentItem } from "./content.js";
 import { type SiteIdentity } from "./identity.js";
+import { type SitePage } from "./pages.js";
 import type { Skill } from "./skills.js";
-export declare function homePage(items: ContentItem[], theme?: ThemeDefinition, site?: SiteIdentity): string;
-export declare function listPage(kind: "post" | "thought", items: ContentItem[], theme?: ThemeDefinition, site?: SiteIdentity): string;
-export declare function postPage(item: ContentItem, posts: ContentItem[], thoughts: ContentItem[], theme?: ThemeDefinition, site?: SiteIdentity): string;
-export declare function thoughtPage(item: ContentItem, theme?: ThemeDefinition, site?: SiteIdentity): string;
-export declare function aboutPage(theme?: ThemeDefinition, site?: SiteIdentity): string;
-export declare function skillsIndexPage(skills: Skill[], theme?: ThemeDefinition, site?: SiteIdentity): string;
-export declare function skillPage(skill: Skill, theme?: ThemeDefinition, site?: SiteIdentity): string;
-export declare function agentMarkdown(posts: ContentItem[], thoughts: ContentItem[], site?: SiteIdentity): string;
-export declare function llmText(posts: ContentItem[], thoughts: ContentItem[], site?: SiteIdentity): string;
+/** The name of the theme stylesheet the package writes by default. */
+export declare const DEFAULT_THEME_STYLESHEET = "blog-theme.css";
+export declare function homePage(items: ContentItem[], theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
+export declare function listPage(kind: "post" | "thought", items: ContentItem[], theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
+export declare function postPage(item: ContentItem, posts: ContentItem[], thoughts: ContentItem[], theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
+export declare function thoughtPage(item: ContentItem, theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
+export declare function aboutPage(theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
+export declare function skillsIndexPage(skills: Skill[], theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
+export declare function skillPage(skill: Skill, theme?: ThemeDefinition, site?: SiteIdentity, stylesheet?: string): string;
+export declare function agentMarkdown(posts: ContentItem[], thoughts: ContentItem[], site?: SiteIdentity, pages?: readonly SitePage[]): string;
+export declare function llmText(posts: ContentItem[], thoughts: ContentItem[], site?: SiteIdentity, pages?: readonly SitePage[]): string;

package/dist/src/site.js

@@ -4,13 +4,24 @@ import { Fragment, h } from "meowjsx/runtime";
 import { renderToHtml } from "meowjsx/web";
 import { withoutLeadingHeading } from "./content.js";
 import { DEFAULT_SITE } from "./identity.js";
+import { sitePageUrl } from "./pages.js";
 import { layoutSkillGraph } from "./skill-graph.js";
+/** The name of the theme stylesheet the package writes by default. */
+export const DEFAULT_THEME_STYLESHEET = "blog-theme.css";
+/** The href of the theme stylesheet for a page at a given depth. */
+function styleHref(depth, stylesheet) {
+    return `${"../".repeat(depth)}${stylesheet}`;
+}
+/** The number of directories a slug puts a page below its section. */
+function slugDepth(slug) {
+    return slug.split("/").filter(Boolean).length;
+}
 function SiteHeader({ activePath, site }) {
     return (h("header", { className: "site" },
         h("a", { className: "site-name", href: "/" }, site.name),
-        h("nav", { className: "site-nav", "aria-label": "\u4E3B\u5BFC\u822A" },
+        h("nav", { className: "site-nav", "aria-label": "Primary navigation" },
             h("a", { className: activePath === "/skills/" ? "active" : "", href: "/skills/" }, "Skills"),
-            h("a", { className: activePath === "/about/" ? "active" : "", href: "/about/" }, "\u5173\u4E8E"))));
+            h("a", { className: activePath === "/about/" ? "active" : "", href: "/about/" }, "About"))));
 }
 function SiteFooter({ site }) {
     return (h("footer", { className: "site" },
@@ -26,7 +37,7 @@ function SiteFooter({ site }) {
 }
 function Document({ title, description, activePath, styleHref, children, theme, site, }) {
     const documentTitle = title === site.name ? site.name : `${title} · ${site.name}`;
-    return (h("html", { lang: "zh-CN", ...themeAttributes(theme) },
+    return (h("html", { lang: "en", ...themeAttributes(theme) },
         h("head", null,
             h("meta", { charSet: "UTF-8" }),
             h("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }),
@@ -46,15 +57,15 @@ function pageHtml(props) {
 }
 function dateLabel(dateKey) {
     if (dateKey === "undated")
-        return { date: "未标日期", weekday: "" };
+        return { date: "Undated", weekday: "" };
     const date = new Date(`${dateKey}T00:00:00+08:00`);
     return {
-        date: new Intl.DateTimeFormat("zh-CN", {
+        date: new Intl.DateTimeFormat("en-US", {
             timeZone: "Asia/Shanghai",
             month: "long",
             day: "numeric",
         }).format(date),
-        weekday: new Intl.DateTimeFormat("zh-CN", {
+        weekday: new Intl.DateTimeFormat("en-US", {
             timeZone: "Asia/Shanghai",
             weekday: "short",
             year: "numeric",
@@ -68,9 +79,9 @@ function Hero({ image }) {
     return (h("section", { className: "hero", "aria-labelledby": "hero-title" },
         h("div", { className: "hero-copy" },
             h("h1", { id: "hero-title" },
-                "\u4E00\u4E07\u5E74\u592A\u4E45\uFF0C",
+                "Ten thousand years is too long;",
                 h("br", null),
-                h("em", null, "\u53EA\u771F\u671D\u5915\u3002"))),
+                h("em", null, "only this day is true."))),
         h("div", { className: "hero-work", "aria-hidden": "true" },
             h("svg", { className: "hero-doodle", viewBox: "0 0 260 190" },
                 h("path", { className: "doodle-loop", d: "M24 96C20 45 58 18 122 20c72 2 116 33 114 84-2 48-48 70-113 68-65-2-96-27-99-76Z" }),
@@ -104,7 +115,7 @@ function ThoughtCard({ item, linked = false }) {
     const body = (h(Fragment, null,
         h("div", { className: "time" },
             h("span", { className: "t" }, item.timeLabel || item.dateKey),
-            " \u00B7 \u60F3\u6CD5"),
+            " \u00B7 Thought"),
         h("div", { className: "body", dangerouslySetInnerHTML: { __html: withoutLeadingHeading(item.html) } }),
         h(Tags, { item: item })));
     if (!linked)
@@ -113,18 +124,18 @@ function ThoughtCard({ item, linked = false }) {
         h("a", { className: "thought-link", href: itemUrl(item) }, body)));
 }
 function PostCard({ item }) {
-    const category = typeof item.metadata.category === "string" ? item.metadata.category : "文章";
+    const category = typeof item.metadata.category === "string" ? item.metadata.category : "Post";
     return (h("a", { className: "post-card", href: itemUrl(item), "data-kind": "post" },
         h("div", { className: "card-top" },
             h("span", { className: "kind" }, category),
             h("span", { className: "meta" },
-                "\u7EA6 ",
+                "About ",
                 item.readingMinutes,
-                " \u5206\u949F \u00B7 ",
+                " min \u00B7 ",
                 item.characterCount,
-                " \u5B57")),
+                " characters")),
         h("h3", null, item.title),
-        h("p", { className: "excerpt" }, item.excerpt || "这篇文章还没有摘要。"),
+        h("p", { className: "excerpt" }, item.excerpt || "This post has no summary yet."),
         h(Tags, { item: item })));
 }
 function groupByDate(items) {
@@ -168,7 +179,7 @@ function FeedDecor({ image }) {
 function Feed({ items, image }) {
     if (items.length === 0) {
         return (h("main", { className: "feed feed-empty" },
-            h("p", { className: "empty-state" }, "\u8FD8\u6CA1\u6709\u516C\u5F00\u5185\u5BB9\u3002"),
+            h("p", { className: "empty-state" }, "No public content yet."),
             h(FeedDecor, { image: image })));
     }
     return (h("main", { className: "feed" },
@@ -185,15 +196,15 @@ function Feed({ items, image }) {
 }
 function Filter({ posts, thoughts }) {
     const total = posts + thoughts;
-    return (h("div", { className: "tag-filter", "data-filter-group": "feed", role: "group", "aria-label": "\u7B5B\u9009\u9996\u9875\u5185\u5BB9" },
+    return (h("div", { className: "tag-filter", "data-filter-group": "feed", role: "group", "aria-label": "Filter home feed" },
         h("button", { type: "button", "data-filter": "all", className: "active", "aria-pressed": "true" },
-            "\u5168\u90E8",
+            "All",
             h("i", null, total)),
         h("button", { type: "button", "data-filter": "post", "aria-pressed": "false" },
-            "\u6587\u7AE0",
+            "Posts",
             h("i", null, posts)),
         h("button", { type: "button", "data-filter": "thought", "aria-pressed": "false" },
-            "\u60F3\u6CD5",
+            "Thoughts",
             h("i", null, thoughts))));
 }
 const FILTER_SCRIPT = `(() => {
@@ -240,12 +251,12 @@ const FILTER_SCRIPT = `(() => {
     }
   }));
 })();`;
-export function homePage(items, theme = blogTheme, site = DEFAULT_SITE) {
+export function homePage(items, theme = blogTheme, site = DEFAULT_SITE, stylesheet = DEFAULT_THEME_STYLESHEET) {
     return pageHtml({
         site,
         theme,
         title: site.name,
-        styleHref: "./blog-theme.css",
+        styleHref: styleHref(0, stylesheet),
         children: (h(Fragment, null,
             h(Hero, { image: site.images?.hero ? `./${site.images.hero}` : undefined }),
             h(Filter, { posts: items.filter((item) => item.kind === "post").length, thoughts: items.filter((item) => item.kind === "thought").length }),
@@ -253,53 +264,55 @@ export function homePage(items, theme = blogTheme, site = DEFAULT_SITE) {
             h("script", { dangerouslySetInnerHTML: { __html: FILTER_SCRIPT } }))),
     });
 }
-export function listPage(kind, items, theme = blogTheme, site = DEFAULT_SITE) {
+export function listPage(kind, items, theme = blogTheme, site = DEFAULT_SITE, stylesheet = DEFAULT_THEME_STYLESHEET) {
     const isPost = kind === "post";
     return pageHtml({
         site,
         theme,
-        title: isPost ? "文章" : "想法",
+        title: isPost ? "Posts" : "Thoughts",
         activePath: isPost ? "/posts/" : "/thoughts/",
-        styleHref: "../blog-theme.css",
+        styleHref: styleHref(1, stylesheet),
         children: (h("main", { className: "listing" },
             h("header", { className: "listing-head" },
                 h("span", { className: "kind" }, isPost ? "Posts" : "Thoughts"),
-                h("h1", null, isPost ? "文章" : "想法"),
-                h("p", null, isPost ? "从碎片里长出来的完整论述。" : "经过剪裁、可以直接展示的短想法。")),
-            h("div", { className: isPost ? "post-list" : "thought-list" }, items.length === 0 ? (h("p", { className: "empty-state" }, "\u8FD8\u6CA1\u6709\u516C\u5F00\u5185\u5BB9\u3002")) : (items.map((item) => isPost ? h(PostCard, { item: item }) : h(ThoughtCard, { item: item, linked: true })))))),
+                h("h1", null, isPost ? "Posts" : "Thoughts"),
+                h("p", null, isPost
+                    ? "Complete arguments grown from fragments."
+                    : "Short, trimmed thoughts ready to show as they are.")),
+            h("div", { className: isPost ? "post-list" : "thought-list" }, items.length === 0 ? (h("p", { className: "empty-state" }, "No public content yet.")) : (items.map((item) => isPost ? h(PostCard, { item: item }) : h(ThoughtCard, { item: item, linked: true })))))),
     });
 }
 function PostNavigation({ item, posts }) {
     const index = posts.findIndex((post) => post.slug === item.slug);
     const older = index >= 0 ? posts[index + 1] : undefined;
     const newer = index > 0 ? posts[index - 1] : undefined;
-    return (h("nav", { className: "post-nav", "aria-label": "\u6587\u7AE0\u5BFC\u822A" },
+    return (h("nav", { className: "post-nav", "aria-label": "Post navigation" },
         older ? (h("a", { href: itemUrl(older) },
-            h("span", { className: "label" }, "\u2190 \u4E0A\u4E00\u7BC7\uFF08\u66F4\u65E9\uFF09"),
+            h("span", { className: "label" }, "\u2190 Previous post (older)"),
             older.title)) : (h("span", null)),
         newer ? (h("a", { className: "next", href: itemUrl(newer) },
-            h("span", { className: "label" }, "\u4E0B\u4E00\u7BC7\uFF08\u66F4\u65B0\uFF09\u2192"),
+            h("span", { className: "label" }, "Next post (newer) \u2192"),
             newer.title)) : (h("span", { className: "next" },
-            h("span", { className: "label" }, "\u4E0B\u4E00\u7BC7\uFF08\u66F4\u65B0\uFF09\u2192"),
-            "\u6CA1\u6709\u4E86\uFF0C\u8FD9\u662F\u6700\u65B0\u7684\u4E00\u7BC7"))));
+            h("span", { className: "label" }, "Next post (newer) \u2192"),
+            "Nothing newer \u2014 this is the latest post."))));
 }
 function RelatedThoughts({ item, thoughts, }) {
     const related = thoughts.filter((thought) => thought.dateKey === item.dateKey).slice(0, 3);
     if (related.length === 0)
         return null;
     return (h("aside", { className: "related-thoughts" },
-        h("h2", null, "\u540C\u4E00\u5929\u7684\u60F3\u6CD5"),
+        h("h2", null, "Thoughts from the same day"),
         related.map((thought) => (h(ThoughtCard, { item: thought, linked: true })))));
 }
-export function postPage(item, posts, thoughts, theme = blogTheme, site = DEFAULT_SITE) {
-    const category = typeof item.metadata.category === "string" ? item.metadata.category : "文章";
+export function postPage(item, posts, thoughts, theme = blogTheme, site = DEFAULT_SITE, stylesheet = DEFAULT_THEME_STYLESHEET) {
+    const category = typeof item.metadata.category === "string" ? item.metadata.category : "Post";
     return pageHtml({
         site,
         theme,
         title: item.title,
         description: item.excerpt,
         activePath: "/posts/",
-        styleHref: "../../blog-theme.css",
+        styleHref: styleHref(1 + slugDepth(item.slug), stylesheet),
         children: (h("main", null,
             h("article", null,
                 h("header", { className: "post-head" },
@@ -307,28 +320,28 @@ export function postPage(item, posts, thoughts, theme = blogTheme, site = DEFAUL
                     h("h1", null, item.title),
                     h("div", { className: "meta" },
                         item.dateKey,
-                        " \u00B7 \u7EA6 ",
+                        " \u00B7 about ",
                         item.readingMinutes,
-                        " \u5206\u949F \u00B7 ",
+                        " min \u00B7 ",
                         item.characterCount,
-                        " \u5B57")),
+                        " characters")),
                 h("div", { className: "prose", dangerouslySetInnerHTML: { __html: item.html } }),
                 h(RelatedThoughts, { item: item, thoughts: thoughts }),
                 h(PostNavigation, { item: item, posts: posts })))),
     });
 }
-export function thoughtPage(item, theme = blogTheme, site = DEFAULT_SITE) {
+export function thoughtPage(item, theme = blogTheme, site = DEFAULT_SITE, stylesheet = DEFAULT_THEME_STYLESHEET) {
     return pageHtml({
         site,
         theme,
         title: item.title,
         description: item.excerpt,
         activePath: "/thoughts/",
-        styleHref: "../../blog-theme.css",
+        styleHref: styleHref(1 + slugDepth(item.slug), stylesheet),
         children: (h("main", null,
             h("article", null,
                 h("header", { className: "post-head" },
-                    h("span", { className: "kind" }, "\u60F3\u6CD5"),
+                    h("span", { className: "kind" }, "Thought"),
                     h("h1", null, item.title),
                     h("div", { className: "meta" },
                         item.dateKey,
@@ -336,21 +349,21 @@ export function thoughtPage(item, theme = blogTheme, site = DEFAULT_SITE) {
                 h("div", { className: "prose", dangerouslySetInnerHTML: { __html: item.html } })))),
     });
 }
-export function aboutPage(theme = blogTheme, site = DEFAULT_SITE) {
+export function aboutPage(theme = blogTheme, site = DEFAULT_SITE, stylesheet = DEFAULT_THEME_STYLESHEET) {
     const about = site.about;
     return pageHtml({
         site,
         theme,
-        title: "关于",
+        title: "About",
         activePath: "/about/",
-        styleHref: "../blog-theme.css",
+        styleHref: styleHref(1, stylesheet),
         children: (h("main", { className: "about" },
             h("div", { className: "avatar", "aria-hidden": "true" }, site.images?.about ? (h("img", { src: `../${site.images.about}`, alt: "", decoding: "async" })) : (h("span", { className: "avatar-initial" }, Array.from(site.name.trim())[0] ?? "M"))),
             about ? (h(Fragment, null,
                 h("h1", null, about.heading),
                 about.paragraphs.map((paragraph) => (h("p", null, paragraph))),
                 about.links && about.links.length > 0 ? (h(Fragment, null,
-                    h("h2", null, about.linksHeading ?? "找到我"),
+                    h("h2", null, about.linksHeading ?? "Find me"),
                     about.links.map((link) => (h("a", { className: "github-link", href: link.href, target: "_blank", rel: "me noopener noreferrer" },
                         h(DoodleGithubIcon, null),
                         h("span", { className: "github-copy" },
@@ -371,17 +384,17 @@ function SkillCard({ skill, site }) {
     return (h("a", { className: `skill-card${skill.scope === "project" ? " project-skill" : ""}`, href: skillUrl(skill) },
         h("span", { className: "skill-card-source" },
             h("span", { className: "skill-card-path" }, skill.scope === "public" ? skillInstallCommand(site, skill) : skill.sourceBasePath),
-            skill.scope === "project" ? h("span", { className: "skill-scope-badge" }, "\u9879\u76EE Skill") : null),
+            skill.scope === "project" ? (h("span", { className: "skill-scope-badge" }, "Project Skill")) : null),
         h("span", { className: "skill-card-main" },
             h("strong", null, skill.name),
             h("span", null, skill.description)),
         h("span", { className: "skill-card-foot" },
             h("span", null,
                 skill.files.length,
-                " \u4E2A Markdown \u00B7 ",
+                " Markdown files \u00B7 ",
                 skill.relations.length,
-                " \u6761\u5F15\u7528"),
-            h("span", { className: "skill-open" }, "\u6253\u5F00\u76EE\u5F55\u00A0 \u2192"))));
+                " references"),
+            h("span", { className: "skill-open" }, "Open directory\u00A0 \u2192"))));
 }
 function skillTree(files) {
     const root = { name: "", children: [] };
@@ -410,14 +423,14 @@ function SkillTreeNodes({ nodes, activePath, }) {
         h("button", { type: "button", className: node.path === activePath ? "active" : "", "data-skill-file": node.path, "aria-pressed": node.path === activePath ? "true" : "false" }, node.name))))));
 }
 function SkillFileTree({ skill, activePath }) {
-    return (h("nav", { className: "skill-files", "aria-label": `${skill.name} 文件目录` },
+    return (h("nav", { className: "skill-files", "aria-label": `${skill.name} file tree` },
         h("span", { className: "skill-files-label" }, "Files"),
         h(SkillTreeNodes, { nodes: skillTree(skill.files), activePath: activePath })));
 }
 function SkillGraphNodeView({ node }) {
     const width = node.width;
     const height = node.height;
-    return (h("a", { className: `skill-graph-node${node.external ? " external" : ""}${node.kind ? ` ${node.kind}` : ""}`, href: node.external ? "#relations" : `#${encodeURIComponent(node.path)}`, "data-map-path": node.path, "data-map-file": node.external ? undefined : node.path, "data-map-detail": node.detail, "aria-label": `${node.name}，${node.role}` },
+    return (h("a", { className: `skill-graph-node${node.external ? " external" : ""}${node.kind ? ` ${node.kind}` : ""}`, href: node.external ? "#relations" : `#${encodeURIComponent(node.path)}`, "data-map-path": node.path, "data-map-file": node.external ? undefined : node.path, "data-map-detail": node.detail, "aria-label": `${node.name}; ${node.role}` },
         h("rect", { x: node.x - width / 2, y: node.y - height / 2, width: width, height: height, rx: "9" }),
         h("text", { className: "skill-graph-node-name", x: node.x, y: node.y - 4 }, node.name),
         h("text", { className: "skill-graph-node-role", x: node.x, y: node.y + 17 }, node.role)));
@@ -425,7 +438,7 @@ function SkillGraphNodeView({ node }) {
 function SkillRelationGraph({ skill, direction }) {
     const graph = layoutSkillGraph(skill, direction);
     const markerId = `skill-arrow-${skill.slug}-${direction.toLowerCase()}`;
-    return (h("svg", { className: `skill-graph-svg skill-graph-${direction.toLowerCase()}`, viewBox: `0 0 ${graph.width} ${graph.height}`, "aria-label": `${skill.name} 文件引用关系` },
+    return (h("svg", { className: `skill-graph-svg skill-graph-${direction.toLowerCase()}`, viewBox: `0 0 ${graph.width} ${graph.height}`, "aria-label": `${skill.name} file reference graph` },
         h("defs", null,
             h("marker", { id: markerId, viewBox: "0 0 10 10", refX: "8", refY: "5", markerWidth: "5", markerHeight: "5", orient: "auto-start-reverse" },
                 h("path", { className: "skill-graph-arrow", d: "M 0 0 L 10 5 L 0 10 z" }))),
@@ -448,28 +461,28 @@ function SkillRelations({ skill }) {
     const hasRelations = skill.relations.length > 0;
     const compactGraph = skill.files.length + skill.externalNodes.length <= 3;
     return (h("section", { className: "skill-relations", "data-skill-view-panel": "relations", hidden: true },
-        h("div", { className: "skill-reading-summary", "aria-label": "\u9605\u8BFB\u7ED3\u6784\u6458\u8981" },
+        h("div", { className: "skill-reading-summary", "aria-label": "Reading structure summary" },
             h("span", null,
                 h("strong", null,
                     reachableFiles,
                     "/",
                     skill.files.length),
-                "\u53EF\u8FBE\u6587\u6863"),
+                "reachable docs"),
             h("span", null,
                 h("strong", null, skill.relations.length),
-                "\u5F15\u7528\u5173\u7CFB"),
+                " references"),
             h("span", null,
                 h("strong", null, maxDepth),
-                "\u6700\u6DF1\u5C42\u7EA7"),
+                " max depth"),
             h("span", { className: missingNodes.length > 0 ? "has-issue" : "" },
                 h("strong", null, missingNodes.length),
-                "\u7F3A\u5931\u76EE\u6807")),
+                " missing targets")),
         hasRelations ? (h(Fragment, null,
             h("div", { className: `skill-graph-canvas${compactGraph ? " compact" : ""}` },
                 h(SkillRelationGraph, { skill: skill, direction: "LR" }),
                 h(SkillRelationGraph, { skill: skill, direction: "TB" })),
             h("section", { className: "skill-reading-paths", "aria-labelledby": `${skill.slug}-paths` },
-                h("h3", { id: `${skill.slug}-paths` }, "\u5F15\u7528\u53D1\u751F\u5728\u54EA\u91CC"),
+                h("h3", { id: `${skill.slug}-paths` }, "Where references happen"),
                 h("ol", null, skill.relations.map((relation) => {
                     const sourceFile = skill.files.find((file) => file.path === relation.source);
                     return (h("li", { className: sourceFile?.reachable ? "" : "unreachable" },
@@ -479,27 +492,29 @@ function SkillRelations({ skill }) {
                             h("code", { title: relation.target }, relation.target)),
                         h("span", { className: "skill-reading-context" }, relation.contexts.map((context) => (h("span", null,
                             context.section,
-                            context.line ? ` · 第 ${context.line} 行` : "",
-                            context.linkText !== relation.label ? ` · “${context.linkText}”` : "",
-                            !sourceFile?.reachable ? " · 入口不可达" : ""))))));
+                            context.line ? ` · line ${context.line}` : "",
+                            context.linkText !== relation.label ? ` · "${context.linkText}"` : "",
+                            !sourceFile?.reachable ? " · entry unreachable" : ""))))));
                 }))))) : (h("div", { className: "skill-reading-empty" },
-            h("strong", null, "\u6CA1\u6709\u8DE8\u6587\u4EF6\u9605\u8BFB\u8DEF\u5F84"),
+            h("strong", null, "No cross-file reading paths"),
             h("p", null,
-                "Agent \u8FDB\u5165\u540E\u53EA\u4F1A\u8BFB\u53D6 ",
+                "Once the Agent enters, it only reads ",
                 h("code", null, "SKILL.md"),
-                "\u3002\u5982\u679C\u8FD8\u6709\u5FC5\u987B\u9605\u8BFB\u7684\u53C2\u8003\u6750\u6599\uFF0C\u9700\u8981\u4ECE\u76F8\u5173\u7AE0\u8282\u7528 Markdown \u94FE\u63A5\u660E\u786E\u5F15\u51FA\u3002"))),
-        unreferencedFiles.length > 0 || missingNodes.length > 0 ? (h("aside", { className: "skill-reading-issues", "aria-label": "\u4FE1\u606F\u7ED3\u6784\u95EE\u9898" },
-            h("strong", null, "\u9700\u8981\u7559\u610F"),
+                ". If other reference material must be read, link it explicitly from the relevant sections with Markdown links."))),
+        unreferencedFiles.length > 0 || missingNodes.length > 0 ? (h("aside", { className: "skill-reading-issues", "aria-label": "Information structure issues" },
+            h("strong", null, "Needs attention"),
             unreferencedFiles.length > 0 ? (h("p", null,
-                "\u5165\u53E3\u65E0\u6CD5\u5230\u8FBE\uFF1A",
+                "Unreachable from the entry:",
                 unreferencedFiles.map((file) => (h("code", null, file.path))))) : null,
             missingNodes.length > 0 ? (h("p", null,
-                "\u94FE\u63A5\u76EE\u6807\u4E0D\u5B58\u5728\uFF1A",
+                "Missing link targets:",
                 missingNodes.map((node) => (h("code", null, node.path))))) : null)) : null,
         hasRelations ? (h("div", { className: "skill-graph-status", "data-map-status": true, "aria-live": "polite" },
-            "\u70B9\u51FB\u56FE\u4E2D\u7684\u8282\u70B9\u67E5\u770B\u5B83\u5728\u9605\u8BFB\u94FE\u8DEF\u4E2D\u7684\u4F5C\u7528",
-            externalNodes.length > 0 ? `；当前有 ${externalNodes.length} 个 Skill 外部目标` : "",
-            "\u3002")) : null));
+            "Select a node in the graph to see its role in the reading chain",
+            externalNodes.length > 0
+                ? `; ${externalNodes.length} targets outside the Skill currently`
+                : "",
+            ".")) : null));
 }
 const SKILL_BROWSER_SCRIPT = `(() => {
   document.querySelectorAll('[data-skill-browser]').forEach((browser) => {
@@ -585,42 +600,42 @@ const SKILL_BROWSER_SCRIPT = `(() => {
       const command = copyButton.dataset.copyCommand;
       if (!command) return;
       await navigator.clipboard.writeText(command);
-      copyButton.textContent = '已复制';
-      window.setTimeout(() => { copyButton.textContent = '复制'; }, 1400);
+      copyButton.textContent = 'Copied';
+      window.setTimeout(() => { copyButton.textContent = 'Copy'; }, 1400);
     });
   });
 })();`;
-export function skillsIndexPage(skills, theme = blogTheme, site = DEFAULT_SITE) {
+export function skillsIndexPage(skills, theme = blogTheme, site = DEFAULT_SITE, stylesheet = DEFAULT_THEME_STYLESHEET) {
     const publicSkills = skills.filter((skill) => skill.scope === "public");
     const projectSkills = skills.filter((skill) => skill.scope === "project");
     return pageHtml({
         site,
         theme,
         title: "Skills",
-        description: "可以交给 Agent 使用的方法与工作约定。",
+        description: "Methods and working conventions that can be handed to an Agent.",
         activePath: "/skills/",
-        styleHref: "../blog-theme.css",
+        styleHref: styleHref(1, stylesheet),
         children: (h("main", { className: "skills-index" },
             h("header", { className: "skills-head" },
                 h("span", { className: "skill-path" }, "~/skills"),
                 h("h1", null, "Skills"),
-                h("p", null, "\u516C\u5F00\u5206\u4EAB\u3001\u53EF\u4EE5\u76F4\u63A5\u4EA4\u7ED9 Agent \u4F7F\u7528\u7684\u65B9\u6CD5\u3002")),
+                h("p", null, "Methods shared publicly and usable directly by an Agent.")),
             h("section", { className: "skill-group", "aria-labelledby": "public-skills-heading" },
                 h("header", { className: "skill-group-head" },
-                    h("h2", { id: "public-skills-heading" }, "\u516C\u5F00 Skills"),
-                    h("span", null, "\u516C\u5F00\u5185\u5BB9")),
-                publicSkills.length > 0 ? (h("div", { className: "skill-list" }, publicSkills.map((skill) => (h(SkillCard, { skill: skill, site: site }))))) : (h("p", { className: "skill-group-empty" }, "\u516C\u5F00 Skills \u76EE\u524D\u8FD8\u6CA1\u6709\u5185\u5BB9\u3002"))),
+                    h("h2", { id: "public-skills-heading" }, "Public Skills"),
+                    h("span", null, "Public content")),
+                publicSkills.length > 0 ? (h("div", { className: "skill-list" }, publicSkills.map((skill) => (h(SkillCard, { skill: skill, site: site }))))) : (h("p", { className: "skill-group-empty" }, "Public Skills have no content yet."))),
             projectSkills.length > 0 ? (h("section", { className: "skill-group project-skills", "aria-labelledby": "project-skills-heading" },
                 h("header", { className: "skill-group-head" },
                     h("div", null,
-                        h("h2", { id: "project-skills-heading" }, "\u9879\u76EE Skills"),
-                        h("small", null, "\u672C\u9879\u76EE\u5185\u90E8\u4F7F\u7528\u7684\u5F00\u53D1\u4E0E\u5185\u5BB9\u5DE5\u4F5C\u6D41")),
+                        h("h2", { id: "project-skills-heading" }, "Project Skills"),
+                        h("small", null, "Development and content workflows used inside this project")),
                     h("span", null, ".agents/skills/")),
                 h("div", { className: "skill-list" }, projectSkills.map((skill) => (h(SkillCard, { skill: skill, site: site })))))) : null,
-            h("p", { className: "skills-prototype-note" }, "\u5F15\u7528\u5173\u7CFB\u56FE\u4ECE SKILL.md \u51FA\u53D1\uFF0C\u6839\u636E Markdown \u94FE\u63A5\u5728\u6784\u5EFA\u65F6\u81EA\u52A8\u751F\u6210\u3002"))),
+            h("p", { className: "skills-prototype-note" }, "The reference graph starts from SKILL.md and is generated at build time from Markdown links."))),
     });
 }
-export function skillPage(skill, theme = blogTheme, site = DEFAULT_SITE) {
+export function skillPage(skill, theme = blogTheme, site = DEFAULT_SITE, stylesheet = DEFAULT_THEME_STYLESHEET) {
     const firstFile = skill.files[0];
     const command = skill.scope === "public" ? skillInstallCommand(site, skill) : skill.sourceBasePath;
     return pageHtml({
@@ -629,20 +644,22 @@ export function skillPage(skill, theme = blogTheme, site = DEFAULT_SITE) {
         title: skill.name,
         description: skill.description,
         activePath: "/skills/",
-        styleHref: skill.scope === "public" ? "../../blog-theme.css" : "../../../blog-theme.css",
+        styleHref: skill.scope === "public"
+            ? styleHref(1 + slugDepth(skill.slug), stylesheet)
+            : styleHref(2 + slugDepth(skill.slug), stylesheet),
         children: (h("main", { className: "skill-page" },
-            h("a", { className: "skill-back", href: "/skills/" }, "\u2190 \u6240\u6709 Skills"),
+            h("a", { className: "skill-back", href: "/skills/" }, "\u2190 All Skills"),
             h("header", { className: "skill-browser-head" },
                 h("span", { className: "skill-command" },
-                    skill.scope === "project" ? (h("span", { className: "skill-scope-badge" }, "\u9879\u76EE Skill \u00B7 \u5185\u90E8")) : null,
+                    skill.scope === "project" ? (h("span", { className: "skill-scope-badge" }, "Project Skill \u00B7 Internal")) : null,
                     h("code", null, command)),
                 h("span", { className: "skill-browser-actions" },
-                    h("button", { type: "button", "data-copy-command": command }, skill.scope === "public" ? "复制" : "复制路径"),
+                    h("button", { type: "button", "data-copy-command": command }, skill.scope === "public" ? "Copy" : "Copy path"),
                     site.repositorySourceUrl ? (h("a", { href: `${site.repositorySourceUrl}/${skill.sourceBasePath}`, target: "_blank", rel: "noopener noreferrer" }, "GitHub \u2197")) : null)),
             h("div", { className: "skill-stage", "data-skill-browser": true },
-                h("nav", { className: "skill-view-tabs", "aria-label": "Skill \u6D4F\u89C8\u65B9\u5F0F" },
-                    h("button", { type: "button", "data-skill-view": "files", "aria-pressed": "true" }, "\u6587\u4EF6\u6D4F\u89C8"),
-                    h("button", { type: "button", "data-skill-view": "relations", "aria-pressed": "false" }, "\u5F15\u7528\u5173\u7CFB\u56FE")),
+                h("nav", { className: "skill-view-tabs", "aria-label": "Skill view mode" },
+                    h("button", { type: "button", "data-skill-view": "files", "aria-pressed": "true" }, "File browser"),
+                    h("button", { type: "button", "data-skill-view": "relations", "aria-pressed": "false" }, "Reference graph")),
                 h("div", { className: "skill-browser", "data-skill-view-panel": "files" },
                     h(SkillFileTree, { skill: skill, activePath: firstFile.path }),
                     h("section", { className: "skill-viewer", "aria-live": "polite" },
@@ -656,64 +673,85 @@ export function skillPage(skill, theme = blogTheme, site = DEFAULT_SITE) {
             h("script", { dangerouslySetInnerHTML: { __html: SKILL_BROWSER_SCRIPT } }))),
     });
 }
-export function agentMarkdown(posts, thoughts, site = DEFAULT_SITE) {
+export function agentMarkdown(posts, thoughts, site = DEFAULT_SITE, pages) {
+    const siteMap = pages
+        ? pages.map((page) => `- [${page.title}](${sitePageUrl(page.path)})`)
+        : [
+            "- [Home](/)",
+            "- [Posts](/posts/)",
+            "- [Thoughts](/thoughts/)",
+            "- [Skills](/skills/) (browse files and the auto-generated Markdown reference graph)",
+            "- [About](/about/)",
+        ];
     const lines = [
         `# ${site.name}`,
         "",
-        "> 给 Agent 读取的站点索引与内容约定。",
+        "> Site index and content conventions for Agents to read.",
         "",
         "## Site map",
         "",
-        "- [首页](/)",
-        "- [文章](/posts/)",
-        "- [想法](/thoughts/)",
-        "- [Skills](/skills/)（可浏览文件与自动生成的 Markdown 引用关系）",
-        "- [关于](/about/)",
+        ...siteMap,
         "",
         "## Content model",
         "",
-        `- \`${site.contentDirectory}/thoughts/\` 保存经过剪裁、可直接展示的短想法。`,
-        `- \`${site.contentDirectory}/posts/\` 保存完整文章；文件名或路径组件以 \`_\` 开头的文件是 draft，不公开、不渲染。`,
-        "- 内容文件支持 `.md` 和 `.mdx`，开头可使用 YAML Frontmatter。",
-        "- 目前 Frontmatter 没有强制字段；`title`、`date`、`created_at`、`category`、`tags` 会被站点识别。",
-        "",
-        "## Public content",
-        "",
-        `公开文章：${posts.length} 篇。`,
-        `公开想法：${thoughts.length} 条。`,
-        "",
-        "### Posts",
-        "",
-        ...posts.map((post) => `- [${post.title}](${itemUrl(post)}) — ${post.dateKey}`),
-        "",
-        "### Thoughts",
-        "",
-        ...thoughts.map((thought) => `- [${thought.title}](${itemUrl(thought)}) — ${thought.dateKey}`),
+        `- \`${site.contentDirectory}/thoughts/\` stores trimmed, directly presentable short thoughts.`,
+        `- \`${site.contentDirectory}/posts/\` stores full posts; files whose name or path segment starts with \`_\` are drafts and are not published or rendered.`,
+        "- Content files support `.md` and `.mdx`, and may start with YAML frontmatter.",
+        "- Frontmatter currently has no required fields; `title`, `date`, `created_at`, `category` and `tags` are recognized by the site.",
         "",
+        // A consumer that owns the site map owns the routes of its content too.
+        ...(pages
+            ? []
+            : [
+                "## Public content",
+                "",
+                `Public posts: ${posts.length}.`,
+                `Public thoughts: ${thoughts.length}.`,
+                "",
+                "### Posts",
+                "",
+                ...posts.map((post) => `- [${post.title}](${itemUrl(post)}) — ${post.dateKey}`),
+                "",
+                "### Thoughts",
+                "",
+                ...thoughts.map((thought) => `- [${thought.title}](${itemUrl(thought)}) — ${thought.dateKey}`),
+                "",
+            ]),
     ];
     return lines.join("\n");
 }
-export function llmText(posts, thoughts, site = DEFAULT_SITE) {
+export function llmText(posts, thoughts, site = DEFAULT_SITE, pages) {
+    const routes = pages
+        ? pages.map((page) => `- ${page.title}: ${sitePageUrl(page.path)}`)
+        : [
+            "- Home: /",
+            "- Posts: /posts/",
+            "- Thoughts: /thoughts/",
+            "- Skills: /skills/",
+            "- About: /about/",
+        ];
     return [
         `# ${site.name}`,
         `> ${site.description}`,
         "",
         "## Pages",
-        "- 首页: /",
-        "- 文章: /posts/",
-        "- 想法: /thoughts/",
-        "- Skills: /skills/",
-        "- 关于: /about/",
+        ...routes,
         "- Agent Markdown: /agents.md",
         "",
-        "## Posts",
-        ...posts.map((post) => `- ${post.title}: ${itemUrl(post)}`),
-        "",
-        "## Thoughts",
-        ...thoughts.map((thought) => `- ${thought.title}: ${itemUrl(thought)}`),
-        "",
+        // A consumer that owns the site map owns the routes of its content too;
+        // listing the content under routes the site does not publish would be wrong.
+        ...(pages
+            ? []
+            : [
+                "## Posts",
+                ...posts.map((post) => `- ${post.title}: ${itemUrl(post)}`),
+                "",
+                "## Thoughts",
+                ...thoughts.map((thought) => `- ${thought.title}: ${itemUrl(thought)}`),
+                "",
+            ]),
         "## Rules",
-        "- 只把公开构建产物视为可展示内容。",
-        "- posts 中以 _ 开头的 draft 不公开、不渲染。",
+        "- Only the public build output is considered presentable content.",
+        "- Drafts whose names start with _ under posts are not published or rendered.",
     ].join("\n");
 }

package/dist/src/skills.js

@@ -44,7 +44,7 @@ function markdownLinks(source) {
         }
         if (url) {
             links.push({
-                label: nodeText(node).replaceAll(/\s+/g, " ").trim() || "打开",
+                label: nodeText(node).replaceAll(/\s+/g, " ").trim() || "Open",
                 url,
                 section,
                 line: node.position?.start?.line,
@@ -53,7 +53,7 @@ function markdownLinks(source) {
         }
         node.children?.forEach((child) => collectLinks(child, section));
     };
-    let section = "文档开头";
+    let section = "Beginning of document";
     for (const node of tree.children ?? []) {
         if (node.type === "heading") {
             section = nodeText(node).replaceAll(/\s+/g, " ").trim() || section;
@@ -79,7 +79,7 @@ function inferredDescription(body) {
         .split(/\r?\n\s*\r?\n/)
         .map(plainText)
         .find(Boolean);
-    return (paragraph ?? "一个可以交给 Agent 使用的 Skill。").slice(0, 180);
+    return (paragraph ?? "A skill that can be handed to an Agent.").slice(0, 180);
 }
 async function collectFiles(directory) {
     const entries = await readdir(directory, { withFileTypes: true });
@@ -107,16 +107,16 @@ function isExternalUrl(url) {
 function externalDetail(url) {
     try {
         const parsed = new URL(url);
-        return `Agent 会离开 Skill，继续读取 ${parsed.hostname}。`;
+        return `The Agent leaves the Skill and continues to ${parsed.hostname}.`;
     }
     catch {
-        return "指向 Skill 目录之外的输入或资料。";
+        return "Points to input or material outside the Skill directory.";
     }
 }
 function relationLabel(label, target) {
     const targetName = target.endsWith("/") ? target : (target.split("/").at(-1) ?? target);
     if (label === target || label === targetName)
-        return "引用";
+        return "Reference";
     return label.length > 16 ? `${label.slice(0, 15)}…` : label;
 }
 function compactGraphLabel(label) {
@@ -209,7 +209,7 @@ async function loadSkill(directory, sourceBasePath, scope) {
                 target = link.url;
                 externalNodes.set(target, {
                     path: target,
-                    role: "外部链接",
+                    role: "External link",
                     detail: externalDetail(target),
                     kind: "external",
                 });
@@ -223,15 +223,15 @@ async function loadSkill(directory, sourceBasePath, scope) {
                     externalNodes.set(target, {
                         path: target,
                         role: resolved.kind === "asset"
-                            ? "本地资源"
+                            ? "Local asset"
                             : resolved.kind === "outside"
-                                ? "Skill 外部"
-                                : "缺失引用",
+                                ? "Outside the Skill"
+                                : "Missing reference",
                         detail: resolved.kind === "asset"
-                            ? "Markdown 明确链接到这个非文本资源。"
+                            ? "The Markdown explicitly links to this non-text asset."
                             : resolved.kind === "outside"
-                                ? "链接指向 Skill 目录之外，Agent 会离开当前 Skill 继续读取。"
-                                : "Markdown 中存在此链接，但 Skill 目录内没有对应文件。",
+                                ? "The link points outside the Skill directory; the Agent leaves the current Skill and continues reading."
+                                : "The link exists in the Markdown, but there is no corresponding file in the Skill directory.",
                         kind: resolved.kind === "outside" ? "external" : resolved.kind,
                     });
                 }
@@ -253,7 +253,7 @@ async function loadSkill(directory, sourceBasePath, scope) {
         return {
             source,
             target,
-            label: compactGraphLabel(sections[0] === "文档开头" ? labels.join(" / ") : sections.join(" / ")),
+            label: compactGraphLabel(sections[0] === "Beginning of document" ? labels.join(" / ") : sections.join(" / ")),
             contexts,
         };
     });
@@ -272,12 +272,12 @@ async function loadSkill(directory, sourceBasePath, scope) {
             const reachable = depth !== undefined;
             return {
                 path,
-                role: path === "SKILL.md" ? "入口" : reachable ? `${depth} 级引用` : "未被引用",
+                role: path === "SKILL.md" ? "Entry" : reachable ? `${depth}-level reference` : "Not referenced",
                 detail: path === "SKILL.md"
-                    ? "Agent 从这里开始读取这个 Skill。"
+                    ? "The Agent starts reading this Skill here."
                     : reachable
-                        ? `从 SKILL.md 经过 ${depth} 次链接可以读到这里。`
-                        : "不在从 SKILL.md 出发的链接链路中，Agent 不会自然读到这里。",
+                        ? `Reachable from SKILL.md through ${depth} links.`
+                        : "Not on the link chain from SKILL.md, so the Agent will not naturally read this.",
                 content: documents.get(path).body,
                 reachable,
                 depth,

package/dist/src/theme.js

@@ -71,7 +71,7 @@ const styles = css `
     text-rendering: optimizeLegibility;
   }
 
-  /* 顶栏：保留秩序，但不再像刊头。 */
+  /* Top bar: keep the order, but stop looking like a masthead. */
   header.site {
     display: flex;
     align-items: center;
@@ -255,7 +255,7 @@ const styles = css `
     pointer-events: none;
   }
 
-  /* 首页内容流：日期只是呼吸点，不再承担机械时间轴。 */
+  /* Home feed: dates are breathing points, not a mechanical timeline. */
   .feed {
     position: relative;
     padding: 8px 0 48px;
@@ -385,7 +385,7 @@ const styles = css `
     letter-spacing: 0.06em;
   }
 
-  /* 两类内容都像桌上的纸，但保留各自的重量。 */
+  /* Both content kinds look like paper on a desk, but keep their own weight. */
   .post-card,
   .thought {
     background-color: ${blogTokens.card};
@@ -548,7 +548,7 @@ const styles = css `
     outline: none;
   }
 
-  /* 过滤器是轻量控制，不再像出版物图例。 */
+  /* Filters are lightweight controls, not publication legends. */
   .tag-filter {
     display: flex;
     flex-wrap: wrap;
@@ -598,7 +598,7 @@ const styles = css `
     transform: translateY(1px);
   }
 
-  /* 文章与想法详情。 */
+  /* Post and thought detail. */
   .post-head {
     padding: 68px 0 37px;
     border-bottom: 1px solid ${blogTokens.line};
@@ -892,7 +892,7 @@ const styles = css `
     text-align: right;
   }
 
-  /* 索引页与关于页。 */
+  /* Index and about pages. */
   .listing,
   .about,
   .skills-index,
@@ -1009,7 +1009,7 @@ const styles = css `
     letter-spacing: 0.06em;
   }
 
-  /* Skills：用目录和文档的语义区分内容，不把它做成产品陈列。 */
+  /* Skills: separate content by catalog and document semantics instead of displaying it as a product. */
   .skills-head {
     margin-bottom: 33px;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "meowpress",
-  "version": "0.1.1-alpha.0",
+  "version": "0.2.0-alpha.0",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -37,11 +37,11 @@
     "yaml": "^2.9.0"
   },
   "peerDependencies": {
-    "meowcss": "^0.1.0 || ^0.1.1-alpha.0",
-    "meowjsx": "^0.1.0 || ^0.1.1-alpha.0"
+    "meowcss": "^0.2.0-alpha.0",
+    "meowjsx": "^0.2.0-alpha.0"
   },
   "devDependencies": {
-    "meowjsx": "0.1.1-alpha.0",
-    "meowcss": "0.1.1-alpha.0"
+    "meowjsx": "0.2.0-alpha.0",
+    "meowcss": "0.2.0-alpha.0"
   }
 }