rspress-plugin-typst 0.0.0-stage → 0.0.2-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Glimverge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# rspress-plugin-typst
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use [Typst](https://github.com/typst/typst) `.typ` files as [Rspress](https://rspress.rs/) documentation pages.
+
+**Docs:** https://glimverge.github.io/rspress-plugin-typst/
+
+Typst's experimental HTML export is compiled through [`@myriaddreamin/typst-ts-node-compiler`](https://www.npmjs.com/package/@myriaddreamin/typst-ts-node-compiler), then rendered inside the Rspress theme.
+
+> Typst HTML export is still experimental (`--features html`). Behavior may change; do not rely on it for production-critical publishing yet.
+
+## Install
+
+```bash
+pnpm add rspress-plugin-typst
+```
+
+## Usage
+
+```ts
+// rspress.config.ts
+import { defineConfig } from '@rspress/core';
+import { pluginTypst } from 'rspress-plugin-typst';
+
+export default defineConfig({
+  root: 'docs',
+  plugins: [pluginTypst()],
+});
+```
+
+Add Typst pages next to your Markdown docs:
+
+```text
+docs/
+  index.mdx
+  guide/
+    hello.typ   →  /guide/hello
+    math.typ    →  /guide/math
+```
+
+### Frontmatter
+
+Prefer Typst document metadata:
+
+```typ
+#set document(
+  title: "Hello Typst",
+  description: "Rendered by rspress-plugin-typst",
+)
+```
+
+Optional Rspress-oriented frontmatter via a labeled metadata block:
+
+```typ
+#metadata((
+  title: "Hello Typst",
+  description: "Rendered by rspress-plugin-typst",
+  outline: true,
+)) <frontmatter>
+```
+
+## Options
+
+```ts
+pluginTypst({
+  extensions: ['.typ'],
+  include: ['**/*.typ'],
+  exclude: ['**/_*', '**/_*/**'],
+  fontPaths: ['assets/fonts'],
+  inputs: { site: 'My Docs' }, // → sys.inputs.site
+  workspace: undefined, // defaults to docs root
+  className: 'rspress-typst',
+  routeExtensions: true,
+})
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `extensions` | `['.typ']` | File extensions treated as Typst docs |
+| `include` | all `.typ` under docs root | Globs relative to the docs root |
+| `exclude` | underscore-prefixed files/dirs | Ignore patterns |
+| `fontPaths` | `undefined` | Extra font directories for the compiler |
+| `inputs` | `undefined` | Extra `sys.inputs` string pairs |
+| `workspace` | docs root | Typst workspace / package root |
+| `className` | `'rspress-typst'` | Wrapper class on the rendered body |
+| `routeExtensions` | `true` | Register extensions on `route.extensions` |
+
+## How it works
+
+1. **`config`** — registers `.typ` on Rspress `route.extensions`.
+2. **`beforeBuild`** — compiles every Typst page once so titles, TOC, and search text are available to `extendPageData` / `modifySearchIndexData`.
+3. **Rspack loader** — transforms each `.typ` route module into a React page that renders the HTML body through `TypstDoc`.
+4. **Compiler** — `@myriaddreamin/typst-ts-node-compiler` embeds Typst via N-API.
+
+```text
+.typ  →  (Typst HTML via N-API)  →  React page  →  Rspress route
+```
+
+## Documentation site
+
+The `playground/` package is this project's docs site (Rspress + Typst examples). It deploys to GitHub Pages on every push to `main` via [`.github/workflows/deploy.yml`](.github/workflows/deploy.yml).
+
+Local preview:
+
+```bash
+pnpm install
+pnpm build
+pnpm playground:dev
+# with production base path:
+pnpm playground:build && pnpm --filter playground preview
+# then open http://localhost:4173/rspress-plugin-typst/
+```
+
+### Enable GitHub Pages (one-time)
+
+In the repository settings:
+
+1. **Settings → Pages**
+2. **Build and deployment → Source**: GitHub Actions
+
+After the first successful `Deploy docs to GitHub Pages` workflow on `main`, the site is available at:
+
+https://glimverge.github.io/rspress-plugin-typst/
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+```
+
+## Publishing
+
+The [Release](.github/workflows/release.yml) workflow follows the
+[`sxzz/workflows`](https://github.com/sxzz/workflows) publish flow (checkout →
+install → changelogithub → build → `pnpm publish`), inlined so every action can
+stay SHA-pinned under this repo’s policy.
+
+1. Configure npm trusted publishing for this GitHub repo (OIDC).
+2. Bump `package.json` version, then push a tag:
+
+```bash
+git tag v0.0.2-alpha.0
+git push origin v0.0.2-alpha.0
+```
+
+Prereleases currently publish with npm dist-tag `alpha`:
+
+```bash
+pnpm add rspress-plugin-typst@alpha
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+import type { RspressPlugin } from '@rspress/core';
+
+declare interface CompilerContext {
+    workspace: string;
+    fontPaths?: string[];
+    inputs?: Record<string, string>;
+}
+
+export declare function compileTypstFile(filepath: string, routePath: string, ctx: CompilerContext): TypstCompileResult;
+
+export declare function createCompilerContext(docsRoot: string, options: TypstPluginOptions): CompilerContext;
+
+/** Extract heading TOC from Typst HTML body. */
+export declare function extractToc(html: string): TypstTocItem[];
+
+/**
+ * Convert a docs-relative file path to a Rspress route path.
+ * Mirrors conventional routing: `guide/index.typ` → `/guide/`, `a.typ` → `/a`.
+ */
+export declare function filePathToRoutePath(relativePath: string, extensions: string[]): string;
+
+/** Strip tags and collapse whitespace for search / plain text. */
+export declare function htmlToPlainText(html: string): string;
+
+/**
+ * Typst's HTML export currently maps `#=` to `<h2>`. Remap depths so Rspress
+ * TOC treats the first content heading level as depth 2 (matching MDX).
+ */
+export declare function normalizeTocDepths(toc: TypstTocItem[]): TypstTocItem[];
+
+/**
+ * Use Typst (`.typ`) files as Rspress documentation pages.
+ *
+ * Compilation uses Typst's experimental HTML export through the Rust-powered
+ * `@myriaddreamin/typst-ts-node-compiler` Node-API binding.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from '@rspress/core';
+ * import { pluginTypst } from 'rspress-plugin-typst';
+ *
+ * export default defineConfig({
+ *   root: 'docs',
+ *   plugins: [pluginTypst()],
+ * });
+ * ```
+ */
+declare function pluginTypst(options?: TypstPluginOptions): RspressPlugin;
+export default pluginTypst;
+export { pluginTypst }
+
+declare interface ScannedTypstPage {
+    absolutePath: string;
+    relativePath: string;
+    routePath: string;
+}
+
+export declare function scanTypstPages(docsRoot: string, options: TypstPluginOptions): Promise<ScannedTypstPage[]>;
+
+export declare interface TypstCompileResult {
+    filepath: string;
+    routePath: string;
+    title: string;
+    description?: string;
+    body: string;
+    html: string;
+    frontmatter: TypstFrontmatter;
+    /** Plain text used for search indexing. */
+    textContent: string;
+    /** Table of contents extracted from HTML headings. */
+    toc: TypstTocItem[];
+}
+
+export declare interface TypstFrontmatter {
+    title?: string;
+    description?: string;
+    [key: string]: unknown;
+}
+
+export declare interface TypstPluginOptions {
+    /**
+     * File extensions treated as Typst documents.
+     * @default ['.typ']
+     */
+    extensions?: string[];
+    /**
+     * Glob patterns (relative to the docs root) to include.
+     * @default all `.typ` files under the docs root
+     */
+    include?: string[];
+    /**
+     * Glob patterns (relative to the docs root) to exclude.
+     * @default underscore-prefixed files and directories
+     */
+    exclude?: string[];
+    /**
+     * Extra font directories passed to the Typst compiler.
+     */
+    fontPaths?: string[];
+    /**
+     * Extra `sys.inputs` string pairs for Typst compilation.
+     */
+    inputs?: Record<string, string>;
+    /**
+     * Typst workspace root. Defaults to the Rspress docs root.
+     */
+    workspace?: string;
+    /**
+     * CSS class applied to the rendered Typst body wrapper.
+     * @default 'rspress-typst'
+     */
+    className?: string;
+    /**
+     * When true, also register `.typ` on `route.extensions` so conventional
+     * routing discovers pages without `addPages`.
+     * Prefer leaving this enabled.
+     * @default true
+     */
+    routeExtensions?: boolean;
+}
+
+export declare interface TypstTocItem {
+    id: string;
+    text: string;
+    depth: number;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,341 @@
+import node_path from "node:path";
+import { fileURLToPath } from "node:url";
+import node_fs from "node:fs";
+import { NodeCompiler } from "@myriaddreamin/typst-ts-node-compiler";
+import fast_glob from "fast-glob";
+function defaultCachePath(docsRoot) {
+    return node_path.join(docsRoot, '.rspress', 'typst-page-cache.json');
+}
+function writePageCache(cachePath, cache) {
+    node_fs.mkdirSync(node_path.dirname(cachePath), {
+        recursive: true
+    });
+    node_fs.writeFileSync(cachePath, `${JSON.stringify(cache, null, 2)}\n`, 'utf8');
+}
+function readPageCache(cachePath) {
+    try {
+        if (!node_fs.existsSync(cachePath)) return {};
+        return JSON.parse(node_fs.readFileSync(cachePath, 'utf8'));
+    } catch  {
+        return {};
+    }
+}
+function cacheKey(filepath) {
+    return node_path.resolve(filepath);
+}
+const TAG_RE = /<[^>]+>/g;
+const HEADING_RE = /<h([1-6])(\s[^>]*)?>([\s\S]*?)<\/h\1>/gi;
+const ID_RE = /\bid\s*=\s*["']([^"']+)["']/i;
+function htmlToPlainText(html) {
+    return html.replace(/<script[\s\S]*?<\/script>/gi, ' ').replace(/<style[\s\S]*?<\/style>/gi, ' ').replace(TAG_RE, ' ').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/\s+/g, ' ').trim();
+}
+function slugify(text) {
+    return text.toLowerCase().trim().replace(/[^\p{L}\p{N}\s-]/gu, '').replace(/\s+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+}
+function enhanceHeadings(html) {
+    const toc = [];
+    const seen = new Map();
+    const nextHtml = html.replace(HEADING_RE, (full, depthRaw, attrsRaw, inner)=>{
+        const depth = Number(depthRaw);
+        const attrs = attrsRaw ?? '';
+        const text = htmlToPlainText(inner);
+        if (!text) return full;
+        let id = attrs.match(ID_RE)?.[1];
+        if (!id) {
+            const base = slugify(text) || `heading-${toc.length}`;
+            const count = seen.get(base) ?? 0;
+            seen.set(base, count + 1);
+            id = 0 === count ? base : `${base}-${count}`;
+        }
+        toc.push({
+            id,
+            text,
+            depth
+        });
+        if (ID_RE.test(attrs)) return full;
+        const spacer = attrs.length > 0 ? attrs : '';
+        return `<h${depth}${spacer} id="${id}">${inner}</h${depth}>`;
+    });
+    return {
+        html: nextHtml,
+        toc: normalizeTocDepths(toc)
+    };
+}
+function extractToc(html) {
+    return enhanceHeadings(html).toc;
+}
+function normalizeTocDepths(toc) {
+    if (0 === toc.length) return toc;
+    const min = Math.min(...toc.map((item)=>item.depth));
+    const shift = 2 - min;
+    if (0 === shift) return toc;
+    return toc.map((item)=>({
+            ...item,
+            depth: Math.min(6, Math.max(1, item.depth + shift))
+        }));
+}
+let sharedCompiler = null;
+let sharedKey = '';
+function compilerKey(ctx) {
+    return JSON.stringify({
+        workspace: ctx.workspace,
+        fontPaths: ctx.fontPaths ?? [],
+        inputs: ctx.inputs ?? {}
+    });
+}
+function getCompiler(ctx) {
+    const key = compilerKey(ctx);
+    if (!sharedCompiler || sharedKey !== key) {
+        sharedCompiler = NodeCompiler.create({
+            workspace: ctx.workspace,
+            fontArgs: ctx.fontPaths?.length ? [
+                {
+                    fontPaths: ctx.fontPaths
+                }
+            ] : void 0,
+            inputs: ctx.inputs
+        });
+        sharedKey = key;
+    }
+    return sharedCompiler;
+}
+function asFrontmatter(value) {
+    if (!value || 'object' != typeof value || Array.isArray(value)) return {};
+    return value;
+}
+function queryFrontmatter(compiler, mainFilePath) {
+    try {
+        const result = compiler.query({
+            mainFilePath
+        }, {
+            selector: '<frontmatter>',
+            field: 'value'
+        });
+        if (Array.isArray(result) && result.length > 0) return asFrontmatter(result[0]);
+    } catch  {}
+    return {};
+}
+function compileTypstFile(filepath, routePath, ctx) {
+    const compiler = getCompiler(ctx);
+    const mainFilePath = node_path.resolve(filepath);
+    const exec = compiler.tryHtml({
+        mainFilePath
+    });
+    if (exec.hasError()) {
+        exec.printDiagnostics();
+        throw new Error(`[rspress-plugin-typst] Failed to compile Typst document: ${mainFilePath}`);
+    }
+    const output = exec.result;
+    if (!output) throw new Error(`[rspress-plugin-typst] Empty HTML output for ${mainFilePath}`);
+    const frontmatter = queryFrontmatter(compiler, mainFilePath);
+    const { html: body, toc } = enhanceHeadings(output.body());
+    const html = output.html();
+    const title = 'string' == typeof frontmatter.title && frontmatter.title || output.title() || node_path.basename(filepath, node_path.extname(filepath));
+    const description = 'string' == typeof frontmatter.description && frontmatter.description || output.description() || void 0;
+    const textContent = htmlToPlainText(body);
+    compiler.evictCache(10);
+    return {
+        filepath: mainFilePath,
+        routePath,
+        title,
+        description,
+        body,
+        html,
+        frontmatter: {
+            ...frontmatter,
+            title,
+            ...description ? {
+                description
+            } : {}
+        },
+        textContent,
+        toc
+    };
+}
+function createCompilerContext(docsRoot, options) {
+    return {
+        workspace: options.workspace ? node_path.resolve(options.workspace) : node_path.resolve(docsRoot),
+        fontPaths: options.fontPaths,
+        inputs: options.inputs
+    };
+}
+const DEFAULT_INCLUDE = [
+    '**/*.typ'
+];
+const DEFAULT_EXCLUDE = [
+    '**/_*',
+    '**/_*/**'
+];
+function toPosix(input) {
+    return input.split(node_path.sep).join('/');
+}
+function stripExtension(filePath, extensions) {
+    const lower = filePath.toLowerCase();
+    for (const ext of extensions)if (lower.endsWith(ext.toLowerCase())) return filePath.slice(0, -ext.length);
+    return filePath;
+}
+function filePathToRoutePath(relativePath, extensions) {
+    let route = toPosix(stripExtension(relativePath, extensions));
+    if ('index' === route || route.endsWith('/index')) route = route.replace(/\/?index$/, '') || '';
+    if (!route.startsWith('/')) route = `/${route}`;
+    if ('/' !== route && route.endsWith('/')) route = route.slice(0, -1);
+    return route || '/';
+}
+async function scanTypstPages(docsRoot, options) {
+    const extensions = options.extensions ?? [
+        '.typ'
+    ];
+    const include = options.include ?? DEFAULT_INCLUDE;
+    const exclude = options.exclude ?? DEFAULT_EXCLUDE;
+    const files = await fast_glob(include, {
+        cwd: docsRoot,
+        absolute: true,
+        onlyFiles: true,
+        ignore: exclude,
+        dot: false
+    });
+    const extSet = new Set(extensions.map((e)=>e.toLowerCase()));
+    return files.filter((file)=>extSet.has(node_path.extname(file).toLowerCase())).map((absolutePath)=>{
+        const relativePath = toPosix(node_path.relative(docsRoot, absolutePath));
+        return {
+            absolutePath,
+            relativePath,
+            routePath: filePathToRoutePath(relativePath, extensions)
+        };
+    }).sort((a, b)=>a.relativePath.localeCompare(b.relativePath));
+}
+const src_dirname = node_path.dirname(fileURLToPath(import.meta.url));
+function uniqExtensions(current, extra) {
+    const base = current ?? [
+        '.md',
+        '.mdx',
+        '.js',
+        '.jsx',
+        '.ts',
+        '.tsx'
+    ];
+    return [
+        ...new Set([
+            ...base,
+            ...extra
+        ])
+    ];
+}
+function pluginTypst(options = {}) {
+    const extensions = options.extensions ?? [
+        '.typ'
+    ];
+    const className = options.className ?? 'rspress-typst';
+    const enableRouteExtensions = false !== options.routeExtensions;
+    let docsRoot = '';
+    let cachePath = '';
+    let pageCache = {};
+    return {
+        name: 'rspress-plugin-typst',
+        globalStyles: node_path.join(src_dirname, 'runtime/typst.css'),
+        config (config) {
+            docsRoot = node_path.resolve(config.root ?? 'docs');
+            cachePath = defaultCachePath(docsRoot);
+            const next = {
+                ...config
+            };
+            if (enableRouteExtensions) next.route = {
+                ...next.route,
+                extensions: uniqExtensions(next.route?.extensions, extensions)
+            };
+            return next;
+        },
+        async beforeBuild (config) {
+            docsRoot = node_path.resolve(config.root ?? (docsRoot || 'docs'));
+            cachePath = defaultCachePath(docsRoot);
+            const ctx = createCompilerContext(docsRoot, options);
+            const pages = await scanTypstPages(docsRoot, options);
+            const nextCache = {};
+            for (const page of pages){
+                const result = compileTypstFile(page.absolutePath, page.routePath, ctx);
+                nextCache[cacheKey(page.absolutePath)] = {
+                    title: result.title,
+                    description: result.description,
+                    textContent: result.textContent,
+                    toc: result.toc,
+                    frontmatter: result.frontmatter,
+                    routePath: result.routePath,
+                    filepath: result.filepath
+                };
+            }
+            pageCache = nextCache;
+            writePageCache(cachePath, pageCache);
+        },
+        async extendPageData (pageData) {
+            const filepath = pageData._filepath;
+            if (!filepath || !extensions.some((ext)=>filepath.endsWith(ext))) return;
+            if (!Object.keys(pageCache).length && cachePath) pageCache = readPageCache(cachePath);
+            const cached = pageCache[cacheKey(filepath)];
+            if (!cached) return;
+            pageData.title = cached.title;
+            if (cached.description) pageData.description = cached.description;
+            pageData.toc = cached.toc.map((item)=>({
+                    id: item.id,
+                    text: item.text,
+                    depth: item.depth,
+                    charIndex: 0
+                }));
+            pageData.content = cached.textContent;
+            pageData.frontmatter = {
+                ...pageData.frontmatter,
+                ...cached.frontmatter,
+                title: cached.title,
+                ...cached.description ? {
+                    description: cached.description
+                } : {}
+            };
+        },
+        async modifySearchIndexData (pages) {
+            if (!Object.keys(pageCache).length && cachePath) pageCache = readPageCache(cachePath);
+            for (const page of pages){
+                const filepath = page._filepath;
+                if (!filepath) continue;
+                const cached = pageCache[cacheKey(filepath)];
+                if (cached) {
+                    page.title = cached.title;
+                    page.content = cached.textContent;
+                    if (cached.description) page.description = cached.description;
+                }
+            }
+        },
+        builderConfig: {
+            tools: {
+                rspack (config) {
+                    config.resolve ??= {};
+                    config.resolve.extensions = uniqExtensions(config.resolve.extensions, extensions);
+                    config.module ??= {};
+                    config.module.rules ??= [];
+                    config.module.rules.unshift({
+                        test: /\.typ$/,
+                        type: "javascript/auto",
+                        use: [
+                            {
+                                loader: node_path.join(src_dirname, 'loader.js'),
+                                options: {
+                                    workspace: null != options.workspace ? node_path.resolve(options.workspace) : docsRoot || node_path.resolve('docs'),
+                                    fontPaths: options.fontPaths,
+                                    inputs: options.inputs,
+                                    className,
+                                    cachePath: cachePath || defaultCachePath(docsRoot || 'docs')
+                                }
+                            }
+                        ]
+                    });
+                }
+            },
+            source: {
+                include: [
+                    /rspress-plugin-typst/
+                ]
+            }
+        }
+    };
+}
+const src = pluginTypst;
+export default src;
+export { compileTypstFile, createCompilerContext, extractToc, filePathToRoutePath, htmlToPlainText, normalizeTocDepths, pluginTypst, scanTypstPages };

package/dist/loader.js

@@ -0,0 +1,244 @@
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { NodeCompiler } from "@myriaddreamin/typst-ts-node-compiler";
+import "fast-glob";
+function writePageCache(cachePath, cache) {
+    node_fs.mkdirSync(node_path.dirname(cachePath), {
+        recursive: true
+    });
+    node_fs.writeFileSync(cachePath, `${JSON.stringify(cache, null, 2)}\n`, 'utf8');
+}
+function readPageCache(cachePath) {
+    try {
+        if (!node_fs.existsSync(cachePath)) return {};
+        return JSON.parse(node_fs.readFileSync(cachePath, 'utf8'));
+    } catch  {
+        return {};
+    }
+}
+function cacheKey(filepath) {
+    return node_path.resolve(filepath);
+}
+function generateTypstPageModule(result, className) {
+    const frontmatter = {
+        ...result.frontmatter,
+        title: result.title,
+        ...result.description ? {
+            description: result.description
+        } : {}
+    };
+    const metaKey = node_path.basename(result.filepath);
+    const pageMeta = {
+        toc: result.toc,
+        title: result.title,
+        headingTitle: result.title,
+        description: result.description,
+        frontmatter
+    };
+    return `/* Auto-generated by rspress-plugin-typst — do not edit */
+import { jsx as _jsx } from 'react/jsx-runtime';
+import { TypstDoc } from 'rspress-plugin-typst/runtime';
+
+export const frontmatter = ${JSON.stringify(frontmatter, null, 2)};
+
+const __typstBody = ${JSON.stringify(result.body)};
+const __typstToc = ${JSON.stringify(result.toc)};
+const __typstPageMeta = ${JSON.stringify(pageMeta, null, 2)};
+
+export default function TypstPage() {
+  return _jsx(TypstDoc, {
+    html: __typstBody,
+    className: ${JSON.stringify(className)},
+    toc: __typstToc,
+  });
+}
+
+TypstPage.__RSPRESS_PAGE_META = {};
+TypstPage.__RSPRESS_PAGE_META[${JSON.stringify(metaKey)}] = __typstPageMeta;
+`;
+}
+const TAG_RE = /<[^>]+>/g;
+const HEADING_RE = /<h([1-6])(\s[^>]*)?>([\s\S]*?)<\/h\1>/gi;
+const ID_RE = /\bid\s*=\s*["']([^"']+)["']/i;
+function htmlToPlainText(html) {
+    return html.replace(/<script[\s\S]*?<\/script>/gi, ' ').replace(/<style[\s\S]*?<\/style>/gi, ' ').replace(TAG_RE, ' ').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/\s+/g, ' ').trim();
+}
+function slugify(text) {
+    return text.toLowerCase().trim().replace(/[^\p{L}\p{N}\s-]/gu, '').replace(/\s+/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+}
+function enhanceHeadings(html) {
+    const toc = [];
+    const seen = new Map();
+    const nextHtml = html.replace(HEADING_RE, (full, depthRaw, attrsRaw, inner)=>{
+        const depth = Number(depthRaw);
+        const attrs = attrsRaw ?? '';
+        const text = htmlToPlainText(inner);
+        if (!text) return full;
+        let id = attrs.match(ID_RE)?.[1];
+        if (!id) {
+            const base = slugify(text) || `heading-${toc.length}`;
+            const count = seen.get(base) ?? 0;
+            seen.set(base, count + 1);
+            id = 0 === count ? base : `${base}-${count}`;
+        }
+        toc.push({
+            id,
+            text,
+            depth
+        });
+        if (ID_RE.test(attrs)) return full;
+        const spacer = attrs.length > 0 ? attrs : '';
+        return `<h${depth}${spacer} id="${id}">${inner}</h${depth}>`;
+    });
+    return {
+        html: nextHtml,
+        toc: normalizeTocDepths(toc)
+    };
+}
+function normalizeTocDepths(toc) {
+    if (0 === toc.length) return toc;
+    const min = Math.min(...toc.map((item)=>item.depth));
+    const shift = 2 - min;
+    if (0 === shift) return toc;
+    return toc.map((item)=>({
+            ...item,
+            depth: Math.min(6, Math.max(1, item.depth + shift))
+        }));
+}
+let sharedCompiler = null;
+let sharedKey = '';
+function compilerKey(ctx) {
+    return JSON.stringify({
+        workspace: ctx.workspace,
+        fontPaths: ctx.fontPaths ?? [],
+        inputs: ctx.inputs ?? {}
+    });
+}
+function getCompiler(ctx) {
+    const key = compilerKey(ctx);
+    if (!sharedCompiler || sharedKey !== key) {
+        sharedCompiler = NodeCompiler.create({
+            workspace: ctx.workspace,
+            fontArgs: ctx.fontPaths?.length ? [
+                {
+                    fontPaths: ctx.fontPaths
+                }
+            ] : void 0,
+            inputs: ctx.inputs
+        });
+        sharedKey = key;
+    }
+    return sharedCompiler;
+}
+function asFrontmatter(value) {
+    if (!value || 'object' != typeof value || Array.isArray(value)) return {};
+    return value;
+}
+function queryFrontmatter(compiler, mainFilePath) {
+    try {
+        const result = compiler.query({
+            mainFilePath
+        }, {
+            selector: '<frontmatter>',
+            field: 'value'
+        });
+        if (Array.isArray(result) && result.length > 0) return asFrontmatter(result[0]);
+    } catch  {}
+    return {};
+}
+function compileTypstFile(filepath, routePath, ctx) {
+    const compiler = getCompiler(ctx);
+    const mainFilePath = node_path.resolve(filepath);
+    const exec = compiler.tryHtml({
+        mainFilePath
+    });
+    if (exec.hasError()) {
+        exec.printDiagnostics();
+        throw new Error(`[rspress-plugin-typst] Failed to compile Typst document: ${mainFilePath}`);
+    }
+    const output = exec.result;
+    if (!output) throw new Error(`[rspress-plugin-typst] Empty HTML output for ${mainFilePath}`);
+    const frontmatter = queryFrontmatter(compiler, mainFilePath);
+    const { html: body, toc } = enhanceHeadings(output.body());
+    const html = output.html();
+    const title = 'string' == typeof frontmatter.title && frontmatter.title || output.title() || node_path.basename(filepath, node_path.extname(filepath));
+    const description = 'string' == typeof frontmatter.description && frontmatter.description || output.description() || void 0;
+    const textContent = htmlToPlainText(body);
+    compiler.evictCache(10);
+    return {
+        filepath: mainFilePath,
+        routePath,
+        title,
+        description,
+        body,
+        html,
+        frontmatter: {
+            ...frontmatter,
+            title,
+            ...description ? {
+                description
+            } : {}
+        },
+        textContent,
+        toc
+    };
+}
+function createCompilerContext(docsRoot, options) {
+    return {
+        workspace: options.workspace ? node_path.resolve(options.workspace) : node_path.resolve(docsRoot),
+        fontPaths: options.fontPaths,
+        inputs: options.inputs
+    };
+}
+function toPosix(input) {
+    return input.split(node_path.sep).join('/');
+}
+function stripExtension(filePath, extensions) {
+    const lower = filePath.toLowerCase();
+    for (const ext of extensions)if (lower.endsWith(ext.toLowerCase())) return filePath.slice(0, -ext.length);
+    return filePath;
+}
+function filePathToRoutePath(relativePath, extensions) {
+    let route = toPosix(stripExtension(relativePath, extensions));
+    if ('index' === route || route.endsWith('/index')) route = route.replace(/\/?index$/, '') || '';
+    if (!route.startsWith('/')) route = `/${route}`;
+    if ('/' !== route && route.endsWith('/')) route = route.slice(0, -1);
+    return route || '/';
+}
+function updateCache(cachePath, filepath, entry) {
+    const cache = readPageCache(cachePath);
+    cache[cacheKey(filepath)] = entry;
+    writePageCache(cachePath, cache);
+}
+function typstLoader() {
+    this.cacheable(true);
+    const callback = this.async();
+    const options = this.getOptions();
+    const filepath = this.resourcePath;
+    try {
+        const ctx = createCompilerContext(options.workspace, {
+            workspace: options.workspace,
+            fontPaths: options.fontPaths,
+            inputs: options.inputs
+        });
+        const relative = filepath.startsWith(options.workspace) ? filepath.slice(options.workspace.length).replace(/^[/\\]/, '') : filepath;
+        const routePath = filePathToRoutePath(relative, [
+            '.typ'
+        ]);
+        const result = compileTypstFile(filepath, routePath, ctx);
+        updateCache(options.cachePath, filepath, {
+            title: result.title,
+            description: result.description,
+            textContent: result.textContent,
+            toc: result.toc,
+            frontmatter: result.frontmatter,
+            routePath: result.routePath,
+            filepath: result.filepath
+        });
+        const code = generateTypstPageModule(result, options.className);
+        callback(null, code);
+    } catch (error) {
+        callback(error instanceof Error ? error : new Error(String(error)));
+    }
+}
+export default typstLoader;

package/dist/runtime/index.d.ts

@@ -0,0 +1,21 @@
+import type { ReactElement } from 'react';
+
+/**
+ * Renders Typst experimental HTML export inside the Rspress doc shell.
+ */
+declare function TypstDoc({ html, className, }: TypstDocProps): ReactElement;
+export { TypstDoc }
+export default TypstDoc;
+
+export declare interface TypstDocProps {
+    html: string;
+    className?: string;
+    /** Reserved for future client-side TOC enhancements. */
+    toc?: Array<{
+        id: string;
+        text: string;
+        depth: number;
+    }>;
+}
+
+export { }

package/dist/runtime/index.js

@@ -0,0 +1,12 @@
+import { jsx } from "react/jsx-runtime";
+function TypstDoc({ html, className = 'rspress-typst' }) {
+    return /*#__PURE__*/ jsx("div", {
+        className: `rp-doc ${className}`,
+        dangerouslySetInnerHTML: {
+            __html: html
+        }
+    });
+}
+const runtime_TypstDoc = TypstDoc;
+export default runtime_TypstDoc;
+export { TypstDoc };

package/dist/runtime/typst.css

@@ -0,0 +1,43 @@
+/* Minimal polish for Typst experimental HTML inside Rspress docs. */
+.rspress-typst {
+  min-width: 0;
+}
+
+.rspress-typst > div {
+  display: contents;
+}
+
+.rspress-typst :where(h1, h2, h3, h4, h5, h6) {
+  scroll-margin-top: 5rem;
+}
+
+.rspress-typst :where(pre, code) {
+  font-family: var(
+    --rp-font-family-mono,
+    ui-monospace,
+    SFMono-Regular,
+    Menlo,
+    Monaco,
+    Consolas,
+    'Liberation Mono',
+    'Courier New',
+    monospace
+  );
+}
+
+.rspress-typst :where(table) {
+  display: block;
+  width: 100%;
+  overflow-x: auto;
+  border-collapse: collapse;
+}
+
+.rspress-typst :where(th, td) {
+  border: 1px solid var(--rp-c-divider, #e2e8f0);
+  padding: 0.5rem 0.75rem;
+}
+
+.rspress-typst :where(img, svg) {
+  max-width: 100%;
+  height: auto;
+}

package/package.json

@@ -1,6 +1,84 @@
 {
   "name": "rspress-plugin-typst",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2-alpha.1",
+  "description": "Rspress plugin that treats Typst (.typ) files as documentation pages via experimental HTML export.",
+  "keywords": [
+    "rspress",
+    "rspress-plugin",
+    "typst",
+    "documentation",
+    "html"
+  ],
+  "homepage": "https://glimverge.github.io/rspress-plugin-typst/",
+  "bugs": {
+    "url": "https://github.com/glimverge/rspress-plugin-typst/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/glimverge/rspress-plugin-typst.git"
+  },
+  "license": "MIT",
+  "author": "Glimverge",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js",
+      "default": "./dist/runtime/index.js"
+    },
+    "./loader": {
+      "types": "./dist/loader.d.ts",
+      "import": "./dist/loader.js",
+      "default": "./dist/loader.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@myriaddreamin/typst-ts-node-compiler": "^0.7.0",
+    "fast-glob": "^3.3.3"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.59.4",
+    "@rsbuild/plugin-react": "^1.4.0",
+    "@rslib/core": "^1.0.3",
+    "@rspress/core": "^2.0.23",
+    "@types/node": "^22.13.10",
+    "@types/react": "^19.0.12",
+    "react": "^19.0.0",
+    "typescript": "^5.8.2"
+  },
+  "peerDependencies": {
+    "@rspress/core": "^1.40.0 || ^2.0.0",
+    "react": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib build --watch",
+    "test": "pnpm build && node --experimental-strip-types --test tests/**/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "playground:dev": "pnpm --filter playground dev",
+    "playground:build": "pnpm --filter playground build"
+  }
 }