Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
6404daf
feat(apidocs): add the apidocs/1 renderer core, samples and dev loop
sgammon Nov 21, 2026
6293048
fix(apidocs): allowlist raw HTML and reject unsafe link URLs
sgammon Nov 21, 2026
2b29f9f
fix(apidocs): decode URLs to a fixed point; encode Markdown destinations
sgammon Nov 21, 2026
6c18339
feat(apidocs): add the redesigned page layout, and test it
sgammon Nov 21, 2026
2163e04
feat(apidocs): name the JPMS module in element-list; let the runner s…
sgammon Nov 21, 2026
d57696c
test(apidocs): check only script code for fetch and import()
sgammon Nov 21, 2026
1e95978
feat(apidocs): system text with mono code, page formats control, lang…
sgammon Nov 21, 2026
16d4ebd
feat(apidocs): add guides, section links and admonitions to apidocs/1
sgammon Nov 21, 2026
5915920
feat(apidocs): add guides to both samples
sgammon Nov 21, 2026
4150df9
feat(apidocs): show guides in the navigator, the overview and search,…
sgammon Nov 21, 2026
b7e7f19
feat(apidocs): add local Lighthouse, agent-readiness and good-css audits
sgammon Nov 21, 2026
2b32e49
feat(apidocs): symbols and location lines in Markdown; formatter-styl…
sgammon Nov 21, 2026
904124d
test(apidocs): cover guides, and read tag attributes outside quoted v…
sgammon Nov 21, 2026
0667e18
feat(apidocs): add package, all-types, A-Z and deprecated index pages
sgammon Nov 21, 2026
ef59d0a
feat(apidocs): fold members into rows that find-in-page and links open
sgammon Nov 21, 2026
5f79f71
feat(apidocs): link the index pages from the top bar and style them
sgammon Nov 21, 2026
c7a7689
refactor(apidocs): split the page shell into parts both renderers can…
sgammon Nov 21, 2026
fa7276c
feat(apidocs): render guides-only sites, images, strikethrough and ta…
sgammon Nov 21, 2026
d479af8
feat(apidocs): import Markdown documentation suites as guides
sgammon Nov 21, 2026
0c87c0a
fix(apidocs): copy only images from a suite, and sanitize SVG
sgammon Nov 21, 2026
dfb25ec
fix(apidocs): resolve relative header links from the site root
sgammon Nov 21, 2026
963e875
docs(apidocs): document Markdown suites, guides-only sites and hosting
sgammon Nov 21, 2026
e210716
fix(apidocs): refuse CSS escapes and control characters in SVG values
sgammon Nov 21, 2026
01cfede
fix(apidocs): keep links out of member rows
sgammon Nov 21, 2026
54a0fe4
refactor(apidocs): make the client behaviors startable and stoppable
sgammon Nov 21, 2026
320b192
feat(apidocs): render apidocs pages in Astro, with the client router …
sgammon Nov 21, 2026
432de75
fix(apidocs): keep Astro links and redirects inside the site's base
sgammon Nov 21, 2026
a0e07e6
fix(apidocs): keep the Astro client script through tree shaking
sgammon Nov 21, 2026
4a3a5bd
fix(apidocs): render the first member rows of each group without a pl…
sgammon Nov 21, 2026
f705c5d
test(apidocs-astro): drive the sample app in Chromium
sgammon Nov 21, 2026
280917a
feat(apidocs): negotiate Markdown, send Link headers and a helpful 40…
sgammon Nov 21, 2026
e7f9915
feat(apidocs): audit a served site with --url
sgammon Nov 21, 2026
df456ee
fix(apidocs): optimize Preact up front in astro dev
sgammon Nov 21, 2026
f051d75
docs(apidocs): document the Astro integration
sgammon Nov 21, 2026
2a06c0b
fix(apidocs): list only Preact entry points an app can resolve
sgammon Nov 21, 2026
fb0eba5
fix(apidocs): build dependencies before linting; settle the leak test…
sgammon Nov 22, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/apidocs-package.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
"@elide/apidocs": minor
---

Add `@elide/apidocs`: static HTML and Markdown API reference pages from the `apidocs/1` model that Elide's Javadoc
doclet and Dokka plugin write, with a JSON Schema, a classic-script renderer bundle and runner for JVM tools, client
islands, neutral and Elide theme presets, sample models and a hot-reload development loop.
5 changes: 5 additions & 0 deletions apps/apidocs-astro/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
dist/
.astro/
.wrangler/
src/generated/
public/guides/
27 changes: 27 additions & 0 deletions apps/apidocs-astro/astro.config.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
// The sample app for @elide/apidocs/astro: the Java sample in two versions (2.0, the latest release, and main,
// a development version), the Kotlin sample, and the Markdown sample suite, on the Cloudflare adapter. Pages
// render on request, as the Komodo docs Worker renders them; the version menu and notice are server islands.
import cloudflare from "@astrojs/cloudflare";
import { apidocs } from "@elide/apidocs/astro/integration";
import { defineConfig } from "astro/config";
import { guidesPlugin } from "./scripts/guides.mjs";

const theme = { extends: "elide" };

export default defineConfig({
adapter: cloudflare(),
server: { host: "127.0.0.1", port: 5190 },
devToolbar: { enabled: false },
integrations: [
apidocs({
sites: [
{ base: "/java/2.0/", model: "./src/models/java.ts", theme, version: "2.0" },
{ base: "/java/main/", model: "./src/models/java.ts", theme, version: "main" },
{ base: "/kotlin/", model: "./src/models/kotlin.ts", theme },
{ base: "/guides/", model: "./src/generated/guides.json", theme },
],
versions: "./src/versions.ts",
}),
],
vite: { plugins: [guidesPlugin()] },
});
28 changes: 28 additions & 0 deletions apps/apidocs-astro/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{
"name": "@elide/apidocs-astro",
"private": true,
"version": "0.0.0",
"type": "module",
"description": "Sample Astro app for @elide/apidocs/astro: the Java and Kotlin sample models in two fake versions, with server islands and the client router.",
"scripts": {
"dev": "astro dev --host 127.0.0.1 --port 5190",
"build": "astro build",
"preview": "wrangler dev -c dist/server/wrangler.json --ip 127.0.0.1 --port 5190",
"lint": "astro sync && tsc --noEmit",
"test": "bun test --timeout 60000 test/"
},
"dependencies": {
"@astrojs/cloudflare": "14.4.4",
"@astrojs/preact": "6.1.6",
"@elide/apidocs": "workspace:*",
"astro": "7.4.7",
"preact": "^11.2.0"
},
"devDependencies": {
"@types/bun": "^1.3.0",
"axe-core": "4.14.0",
"playwright": "^1.65.0",
"typescript": "^7.0.2",
"wrangler": "4.157.0"
}
}
4 changes: 4 additions & 0 deletions apps/apidocs-astro/public/versions.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
[
{ "id": "2.0", "base": "/java/2.0/", "latest": true },
{ "id": "main", "base": "/java/main/", "channel": "development" }
]
39 changes: 39 additions & 0 deletions apps/apidocs-astro/scripts/guides.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
// Imports the Markdown sample suite (packages/apidocs/samples/guides) into a guides-only model at
// src/generated/guides.json, and copies its images to public/guides/, when Astro starts and whenever a file in
// the suite changes. Both outputs are generated and ignored by git.
import { mkdirSync, rmSync, writeFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { guidesModel, importMarkdown, readSuite } from "@elide/apidocs/import";

const app = fileURLToPath(new URL("..", import.meta.url));
const suite = resolve(app, "../../packages/apidocs/samples/guides");

export function generateGuides() {
const { files, assets } = readSuite(suite);
const result = importMarkdown(files, {
suite: "markdown",
assets,
links: [{ prefix: "../developer/", target: "https://example.com/developer/" }, { prefix: "../api/", target: "/java/2.0/" }],
});
const model = guidesModel(result, { name: "Geo user guide", version: "2.0" });
mkdirSync(resolve(app, "src/generated"), { recursive: true });
writeFileSync(resolve(app, "src/generated/guides.json"), JSON.stringify(model));
rmSync(resolve(app, "public/guides"), { recursive: true, force: true });
for (const copy of result.files) {
const to = resolve(app, "public/guides", copy.to);
mkdirSync(dirname(to), { recursive: true });
writeFileSync(to, copy.data);
}
}

export function guidesPlugin() {
generateGuides();
return {
name: "sample-guides",
configureServer(server) {
server.watcher.add(suite);
server.watcher.on("change", file => file.startsWith(suite) && generateGuides());
},
};
}
4 changes: 4 additions & 0 deletions apps/apidocs-astro/src/env.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/** The Workers runtime module that src/versions.ts reads the assets binding from, when it runs there. */
declare module "cloudflare:workers" {
export const env: Record<string, unknown>;
}
4 changes: 4 additions & 0 deletions apps/apidocs-astro/src/models/java.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/** The Java sample model, as the doclet would write it. */
import { samples } from "@elide/apidocs/samples";

export default samples.java;
4 changes: 4 additions & 0 deletions apps/apidocs-astro/src/models/kotlin.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/** The Kotlin sample model, as the Dokka plugin would write it. */
import { samples } from "@elide/apidocs/samples";

export default samples.kotlin;
30 changes: 30 additions & 0 deletions apps/apidocs-astro/src/pages/index.astro
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
---
/** The sample's front page: links to each site. Not part of the integration. */
const sites = [
{ href: "/java/2.0/", label: "Java sample 2.0", note: "the latest release" },
{ href: "/java/main/", label: "Java sample main", note: "a development version, with a version notice" },
{ href: "/kotlin/", label: "Kotlin sample", note: "unversioned" },
{ href: "/guides/", label: "Markdown sample suite", note: "a guides-only site from the importer" },
];
---
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>@elide/apidocs on Astro</title>
<meta name="description" content="The sample models served by the @elide/apidocs Astro integration." />
<style>
body { font: 15px/1.6 system-ui, sans-serif; max-width: 40rem; margin: 3rem auto; padding: 0 1rem; color: #161a21; background: #fbfcfd; }
a { color: #5b21b6; }
</style>
</head>
<body>
<main>
<h1>@elide/apidocs on Astro</h1>
<ul>
{sites.map(site => <li><a href={site.href}>{site.label}</a>: {site.note}</li>)}
</ul>
</main>
</body>
</html>
22 changes: 22 additions & 0 deletions apps/apidocs-astro/src/versions.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
/**
* The Java sample's versions. Pages render with `versions` (the fallback the version islands show first); the
* islands call loadVersions on each request, which reads public/versions.json through the Worker's assets
* binding, so editing that file changes the menu on pages that are already cached. A real app reads its
* versions.json from R2 the same way.
*/
import type { Version } from "@elide/apidocs/astro/helpers";
import initial from "../public/versions.json";

export const versions: Version[] = initial as Version[];

export async function loadVersions(request: Request): Promise<Version[]> {
try {
const { env } = await import("cloudflare:workers");
const assets = (env as { ASSETS?: { fetch: (input: string | URL) => Promise<Response> } }).ASSETS;
const response = await assets?.fetch(new URL("/versions.json", request.url));
if (response?.ok) return (await response.json()) as Version[];
} catch {
/* not on the Workers runtime */
}
return versions;
}
Loading
Loading