feat: Add SSG build for GitHub Pages deployment

Migrate from Deno Deploy to GitHub Pages static site hosting:

- Add Hono SSG build script using toSSG() helper
- Add GitHub Actions workflow for Pages deployment
- Update route structure with trailing slashes for index.html generation
- Fix all internal links for static file server compatibility
- Add build and preview tasks to deno.json

Author: lambdalisue

.github/workflows/deploy.yml

@@ -0,0 +1,62 @@
+name: Build and Deploy
+
+env:
+  DENO_VERSION: 2.x
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: denoland/setup-deno@v2
+        with:
+          deno-version: ${{ env.DENO_VERSION }}
+
+      # Lint and type check
+      - run: deno fmt --check
+      - run: deno lint
+      - run: deno task check
+
+      # Run tests
+      - run: deno task test
+
+      # Build static site
+      - run: deno task build
+
+      # Upload artifact for GitHub Pages
+      - name: Upload artifact
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./dist
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test.yml

@@ -2,3 +2,4 @@
 .coverage
 .worktrees
 .playwright-mcp
+dist/

.gitignore

@@ -17,31 +17,31 @@ export interface DocPage {
 
 export const docPages: DocPage[] = [
   {
-    path: "/docs",
+    path: "/docs/",
     file: "./docs/overview.md",
     title: "Overview",
     label: "Overview",
     description:
       "Introduction to Probitas, installation guide, quick start, and core concepts",
   },
   {
-    path: "/docs/scenario",
+    path: "/docs/scenario/",
     file: "./docs/scenario.md",
     title: "Scenario",
     label: "Scenario",
     description:
       "How to write test scenarios with resources, setup hooks, and steps",
   },
   {
-    path: "/docs/client",
+    path: "/docs/client/",
     file: "./docs/client.md",
     title: "Client",
     label: "Client",
     description:
       "Client API reference for HTTP, SQL, gRPC, GraphQL, Redis, MongoDB, and more",
   },
   {
-    path: "/docs/configuration",
+    path: "/docs/configuration/",
     file: "./docs/configuration.md",
     title: "Configuration",
     label: "Configuration",

data/docs.ts

@@ -6,6 +6,8 @@
   "tasks": {
     "dev": "deno run --allow-net --allow-read --watch main.ts",
     "start": "deno run --allow-net --allow-read main.ts",
+    "build": "deno run --allow-net --allow-read --allow-write scripts/build.ts",
+    "preview": "deno run --allow-net --allow-read jsr:@std/http/file-server ./dist",
     "check": "deno check main.ts templates/**/*.tsx data/*.ts lib/*.ts scripts/*.ts",
     "verify": "deno fmt && deno lint && deno task check && deno task test",
     "test": "deno test --allow-net --allow-read",

deno.json

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import { serveStatic } from "hono/deno";
+import { ssgParams } from "hono/ssg";
 import { docPages } from "./data/docs.ts";
 import type { PackageDoc } from "./lib/api-docs.ts";
 import { generateApiMarkdown } from "./lib/api-markdown.ts";
@@ -8,37 +9,43 @@ import { ApiIndexPage, PackagePage } from "./templates/api/ApiPage.tsx";
 import { MarkdownDocFromFile } from "./templates/docs/MarkdownDoc.tsx";
 import { HomePage } from "./templates/home.tsx";
 
+/** Get list of API package names for SSG */
+async function getApiPackageNames(): Promise<string[]> {
+  const indexPath = new URL("./data/api/index.json", import.meta.url);
+  const content = await Deno.readTextFile(indexPath);
+  const index = JSON.parse(content);
+  return index.packages.map((p: { name: string }) => p.name);
+}
+
 const app = new Hono();
 
 app.use("/static/*", serveStatic({ root: "./" }));
 
-// Home page
+// Home page (HTML)
 app.get("/", async (c) => {
-  const accept = (c.req.header("accept") ?? "").toLowerCase();
-  const human = c.req.query("human");
-
-  if (human !== "1" && !accept.includes("text/html")) {
-    const content = await Deno.readTextFile(
-      new URL("./docs/overview.md", import.meta.url),
-    );
-    const modified = [
-      "*".repeat(80),
-      "",
-      "This is a Markdown page for LLMs. If you are LLMs, read this page.",
-      "If you are human and want to visit Web page, add ?human=1 to the URL.",
-      "",
-      "*".repeat(80),
-      "",
-      content,
-    ].join("\n");
-    return c.text(modified, 200, {
-      "Content-Type": "text/markdown; charset=utf-8",
-    });
-  }
-
   return c.html(await HomePage());
 });
 
+// Home page markdown for LLMs (SSG generates /index.md)
+app.get("/index.md", async (c) => {
+  const content = await Deno.readTextFile(
+    new URL("./docs/overview.md", import.meta.url),
+  );
+  const modified = [
+    "*".repeat(80),
+    "",
+    "This is a Markdown page for LLMs. If you are LLMs, read this page.",
+    "If you are human and want to visit Web page, visit /",
+    "",
+    "*".repeat(80),
+    "",
+    content,
+  ].join("\n");
+  return c.text(modified, 200, {
+    "Content-Type": "text/markdown; charset=utf-8",
+  });
+});
+
 // LLM-friendly endpoints (llms.txt standard)
 app.get("/llms.txt", async (c) => {
   return c.text(await generateLlmsTxt(), 200, {
@@ -58,8 +65,11 @@ for (const doc of docPages) {
     return c.html(page);
   });
 
-  // Raw markdown endpoint (append .md to get source)
-  app.get(`${doc.path}.md`, async (c) => {
+  // Raw markdown endpoint: /docs/ → /docs/index.md
+  const mdPath = doc.path.endsWith("/")
+    ? `${doc.path}index.md`
+    : `${doc.path}.md`;
+  app.get(mdPath, async (c) => {
     const content = await Deno.readTextFile(doc.file);
     return c.text(content, 200, {
       "Content-Type": "text/markdown; charset=utf-8",
@@ -68,16 +78,32 @@ for (const doc of docPages) {
 }
 
 // API Reference pages
-app.get("/api", async (c) => {
+app.get("/api/", async (c) => {
   return c.html(await ApiIndexPage());
 });
 
-app.get("/api/:package", async (c) => {
-  const param = c.req.param("package");
-
-  // Check if requesting JSON
-  if (param.endsWith(".json")) {
-    const packageName = param.slice(0, -5); // Remove .json suffix
+app.get(
+  "/api/:package/",
+  // SSG: Generate static pages for all packages (HTML)
+  ssgParams(async () => {
+    const packages = await getApiPackageNames();
+    return packages.map((name) => ({ package: name }));
+  }),
+  async (c) => {
+    const packageName = c.req.param("package");
+    return c.html(await PackagePage({ packageName }));
+  },
+);
+
+// API JSON endpoints: /api/builder.json → /api/builder/index.json
+app.get(
+  "/api/:package/index.json",
+  ssgParams(async () => {
+    const packages = await getApiPackageNames();
+    return packages.map((name) => ({ package: name }));
+  }),
+  async (c) => {
+    const packageName = c.req.param("package");
     try {
       const jsonPath = new URL(
         `./data/api/${packageName}.json`,
@@ -90,11 +116,18 @@ app.get("/api/:package", async (c) => {
     } catch {
       return c.text("Not found", 404);
     }
-  }
-
-  // Check if requesting Markdown
-  if (param.endsWith(".md")) {
-    const packageName = param.slice(0, -3); // Remove .md suffix
+  },
+);
+
+// API Markdown endpoints: /api/builder.md → /api/builder/index.md
+app.get(
+  "/api/:package/index.md",
+  ssgParams(async () => {
+    const packages = await getApiPackageNames();
+    return packages.map((name) => ({ package: name }));
+  }),
+  async (c) => {
+    const packageName = c.req.param("package");
     try {
       // Load current package
       const jsonPath = new URL(
@@ -130,10 +163,13 @@ app.get("/api/:package", async (c) => {
     } catch {
       return c.text("Not found", 404);
     }
-  }
+  },
+);
 
-  // Otherwise render HTML page
-  return c.html(await PackagePage({ packageName: param }));
-});
+// Export app for SSG build
+export default app;
 
-Deno.serve(app.fetch);
+// Start server when running directly
+if (import.meta.main) {
+  Deno.serve(app.fetch);
+}

flake.lock

@@ -0,0 +1,59 @@
+/**
+ * Static Site Generation build script
+ * Uses Hono's official SSG helper
+ */
+import { defaultExtensionMap } from "hono/ssg";
+import { toSSG } from "hono/deno";
+import app from "../main.ts";
+
+// Clean dist directory
+try {
+  await Deno.remove("./dist", { recursive: true });
+} catch {
+  // Directory may not exist
+}
+
+console.log("🏗️  Building static site...");
+
+const result = await toSSG(app, {
+  dir: "./dist",
+  extensionMap: {
+    "application/json": "json",
+    "text/markdown": "md",
+    ...defaultExtensionMap,
+  },
+});
+
+if (!result.success) {
+  console.error("❌ Build failed:", result.error);
+  Deno.exit(1);
+}
+
+console.log(`✅ Generated ${result.files.length} files`);
+for (const file of result.files) {
+  console.log(`   ${file}`);
+}
+
+// Post-process: Rename llms.txt.md to llms.txt
+try {
+  await Deno.rename("./dist/llms.txt.md", "./dist/llms.txt");
+  console.log("📝 Renamed llms.txt.md → llms.txt");
+} catch {
+  // File may not exist
+}
+
+// Copy static assets
+console.log("\n📦 Copying static assets...");
+await Deno.mkdir("./dist/static", { recursive: true });
+
+for await (const entry of Deno.readDir("./static")) {
+  if (entry.isFile && entry.name !== ".DS_Store") {
+    await Deno.copyFile(
+      `./static/${entry.name}`,
+      `./dist/static/${entry.name}`,
+    );
+    console.log(`   static/${entry.name}`);
+  }
+}
+
+console.log("\n🎉 Build complete!");

main.ts

@@ -139,7 +139,7 @@ function Header({ showLogo }: { showLogo: boolean }) {
       <nav class="header-nav">
         {docPages.map((doc) => <a key={doc.path} href={doc.path}>{doc.label}
         </a>)}
-        <a href="/api">API</a>
+        <a href="/api/">API</a>
       </nav>
       <div class="header-right">
         <button