@wrikka/create-docs 0.1.0 → 0.2.1

package/docs/config.md

@@ -2,7 +2,7 @@
 title: Configuration
 description: Site, features, i18n, versioning, and navigation config.
 order: 4
-category: Guide
+category: Reference
 tags: [config]
 ---
 

package/docs/data-sources.md

@@ -2,7 +2,7 @@
 title: Data Sources
 description: Filesystem, remote, composite, and custom data sources.
 order: 6
-category: Guide
+category: Reference
 tags: [data]
 ---
 

package/docs/deploy.md

@@ -2,7 +2,7 @@
 title: Deployment
 description: Build, output, and deploy the docs site.
 order: 7
-category: Guide
+category: Reference
 tags: [deploy]
 ---
 

package/docs/features.md

@@ -2,7 +2,7 @@
 title: Features
 description: Search, SEO, API references, analytics, PWA, and more.
 order: 5
-category: Guide
+category: Features
 tags: [features]
 ---
 

package/docs/markdown.md

@@ -2,7 +2,7 @@
 title: Markdown Syntax
 description: Callouts, code groups, steps, playgrounds, UI components, and more.
 order: 3
-category: Guide
+category: Features
 tags: [markdown]
 ---
 

package/docs/theming.md

@@ -2,7 +2,7 @@
 title: Theming
 description: Customize colors, fonts, and UnoCSS shortcuts.
 order: 8
-category: Guide
+category: Features
 tags: [theme]
 ---
 

package/docs/translate.md

@@ -0,0 +1,46 @@
+---
+title: AI Translation
+description: Translate docs with AI from CI — plan, review, and ship locales.
+order: 9
+category: Features
+tags: [translate, i18n, ai]
+---
+
+create-docs ships a translation pipeline that runs in CI, not in the browser.
+The runtime shows the UX — locale cards, per-doc status, and copyable
+commands — while the actual translation is produced by an AI provider in a
+workflow.
+
+## Enable
+
+```ts
+mountDocsApp({
+  features: { translate: true },
+  translate: {
+    provider: "ai",          // provider hint shown in the UI
+    workflow: "translate.yml",
+    locales: [
+      { id: "th", label: "ไทย" },
+      { id: "ja", label: "日本語" },
+    ],
+  },
+});
+```
+
+This adds a **Translate** item to the top nav and sidebar, a `/translate`
+page, and a per-page Translate action on doc pages.
+
+## How it works
+
+1. `bunx create-docs-translate --docs docs --locales th,ja` scans your docs
+   and writes `translation-plan.json` with one task per
+   `(document, locale)` pair.
+2. A CI workflow (e.g. `.github/workflows/translate.yml`) runs the planner
+   and — once a `TRANSLATE_PROVIDER` and API key are configured — feeds the
+   plan to the provider.
+3. Translated markdown lands under `docs/<locale>/…`, gets committed, and the
+   locale switcher picks it up automatically.
+
+The `/translate` page derives per-doc status from doc ids and tags: a doc
+counts as translated for a locale when its id contains `.{locale}` or
+`--{locale}`, or when it carries a `lang:{locale}` / `locale:{locale}` tag.

package/package.json

@@ -1,11 +1,12 @@
 {
 	"name": "@wrikka/create-docs",
 	"description": "Vite plugin for documentation sites built on Functional Clean Architecture with SolidJS support",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"type": "module",
 	"bin": {
-		"create-docs": "./bin/cli.js",
-		"create-docs-pull": "./scripts/github-pull.ts"
+		"create-docs": "bin/cli.js",
+		"create-docs-pull": "scripts/github-pull.ts",
+		"create-docs-translate": "scripts/translate.ts"
 	},
 	"files": [
 		"bin",
@@ -57,7 +58,7 @@
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/wrikka/create-docs"
+		"url": "git+https://github.com/wrikka/create-docs.git"
 	},
 	"bugs": {
 		"url": "https://github.com/wrikka/create-docs/issues"
@@ -86,7 +87,8 @@
 		"deps:analyze": "bunx depcheck",
 		"clean": "bunx rimraf dist node_modules",
 		"security": "bunx audit",
-		"pull": "bun scripts/github-pull.ts"
+		"pull": "bun scripts/github-pull.ts",
+		"translate": "bun scripts/translate.ts"
 	},
 	"dependencies": {
 		"@codemirror/basic-setup": "^0.20.0",

package/scripts/generate-docs-index.ts

@@ -99,9 +99,9 @@ for (const collection of collections) {
 	}
 }
 
-const outDir = process.argv.includes("--dev")
-	? join(root, "dev", "dist")
-	: join(root, "dist");
+const outDir = process.argv.includes("--lib")
+	? join(root, "dist")
+	: join(root, "dev", "dist");
 mkdirSync(outDir, { recursive: true });
 writeFileSync(
 	join(outDir, "search-index.json"),

package/scripts/translate.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env bun
+/**
+ * create-docs translate — CI-friendly AI translation planner.
+ *
+ * Scans a docs directory, computes which (document, locale) pairs are missing
+ * translations, and writes a `translation-plan.json` that a CI workflow (or an
+ * AI provider integration) can consume.
+ *
+ * Usage:
+ *   bun scripts/translate.ts --docs docs --locales th,ja [--out translation-plan.json]
+ *
+ * The script is intentionally a planner: it does not call an AI provider yet.
+ * To wire a real provider, set TRANSLATE_PROVIDER plus the provider's API key
+ * (e.g. OPENAI_API_KEY) and pipe the emitted plan into your translation step.
+ */
+
+import {
+	mkdirSync,
+	readdirSync,
+	statSync,
+	writeFileSync,
+} from "node:fs";
+import * as path from "node:path";
+
+interface CliArgs {
+	docs: string;
+	locales: string[];
+	out: string;
+}
+
+function parseArgs(argv: string[]): CliArgs {
+	const args: CliArgs = {
+		docs: "docs",
+		locales: [],
+		out: "translation-plan.json",
+	};
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--docs") args.docs = argv[++i] ?? args.docs;
+		else if (a === "--locales")
+			args.locales = (argv[++i] ?? "")
+				.split(",")
+				.map((s) => s.trim())
+				.filter(Boolean);
+		else if (a === "--out") args.out = argv[++i] ?? args.out;
+	}
+	if (args.locales.length === 0) {
+		console.error("Missing --locales (comma separated, e.g. --locales th,ja)");
+		process.exit(1);
+	}
+	return args;
+}
+
+function walk(dir: string, prefix = ""): string[] {
+	const out: string[] = [];
+	for (const name of readdirSync(dir)) {
+		if (name.startsWith(".") || name === "node_modules") continue;
+		const abs = path.join(dir, name);
+		const rel = prefix ? `${prefix}/${name}` : name;
+		if (statSync(abs).isDirectory()) out.push(...walk(abs, rel));
+		else if (/\.(md|mdx)$/i.test(name)) out.push(rel);
+	}
+	return out;
+}
+
+function main() {
+	const args = parseArgs(process.argv.slice(2));
+	const docsDir = path.resolve(args.docs);
+	if (!statSync(docsDir, { throwIfNoEntry: false })?.isDirectory()) {
+		console.error(`Docs directory not found: ${docsDir}`);
+		process.exit(1);
+	}
+
+	const files = walk(docsDir);
+	const provider = process.env.TRANSLATE_PROVIDER ?? "ai";
+
+	const plan = {
+		generatedAt: new Date().toISOString(),
+		provider,
+		sourceLocale: process.env.SOURCE_LOCALE ?? "en",
+		targetLocales: args.locales,
+		docsDir: args.docs,
+		tasks: [] as Array<{
+			source: string;
+			target: string;
+			locale: string;
+			sourcePath: string;
+			targetPath: string;
+			status: "pending" | "translated";
+		}>,
+	};
+
+	let pending = 0;
+	let done = 0;
+	for (const file of files) {
+		for (const locale of args.locales) {
+			const targetPath = path.join(docsDir, locale, file);
+			const exists =
+				statSync(targetPath, { throwIfNoEntry: false })?.isFile() ?? false;
+			plan.tasks.push({
+				source: file,
+				target: `${locale}/${file}`,
+				locale,
+				sourcePath: path.join(docsDir, file),
+				targetPath,
+				status: exists ? "translated" : "pending",
+			});
+			if (exists) done++;
+			else pending++;
+		}
+	}
+
+	mkdirSync(path.dirname(path.resolve(args.out)), { recursive: true });
+	writeFileSync(args.out, JSON.stringify(plan, null, 2), "utf8");
+
+	console.log(
+		`[create-docs translate] ${files.length} docs x ${args.locales.length} locales -> ${done} translated, ${pending} pending`,
+	);
+	console.log(`Plan written to ${path.resolve(args.out)}`);
+	if (pending > 0 && !process.env.TRANSLATE_PROVIDER) {
+		console.log(
+			"No TRANSLATE_PROVIDER configured — plan emitted for review; set a provider + API key to run real translations.",
+		);
+	}
+}
+
+main();

package/src/adapters/github/github-pull.ts

@@ -12,6 +12,7 @@ import {
 	mkdirSync,
 	readdirSync,
 	readFileSync,
+	rmSync,
 	statSync,
 	writeFileSync,
 } from "node:fs";
@@ -179,12 +180,31 @@ interface LocalFile {
 	absolute: string;
 }
 
+const EXCLUDED_DIRS = new Set([
+	"node_modules",
+	"dist",
+	"build",
+	"coverage",
+	".git",
+	".vitepress",
+	".next",
+	".turbo",
+	".cache",
+]);
+
+function isExcludedPath(relative: string): boolean {
+	return relative
+		.split("/")
+		.some((seg) => EXCLUDED_DIRS.has(seg) || seg.startsWith("."));
+}
+
 function scanLocalDir(dir: string, prefix = ""): LocalFile[] {
 	const items: LocalFile[] = [];
 	for (const name of readdirSync(dir)) {
 		const absolute = path.join(dir, name);
 		const relative = prefix ? `${prefix}/${name}` : name;
 		if (statSync(absolute).isDirectory()) {
+			if (EXCLUDED_DIRS.has(name) || name.startsWith(".")) continue;
 			items.push(...scanLocalDir(absolute, relative));
 		} else if (/\.(md|mdx)$/i.test(name) || /^_dir\.ya?ml$/i.test(name)) {
 			items.push({ relative, absolute });
@@ -252,6 +272,8 @@ export async function pullFromGitHub(
 			const collectionId = source.id;
 
 			const collectionOut = path.join(docsOut, collectionId);
+			// Clean previous output so deleted/excluded upstream files don't linger.
+			rmSync(collectionOut, { recursive: true, force: true });
 			mkdirSync(collectionOut, { recursive: true });
 
 			// Local mode: copy files from a local directory.
@@ -277,6 +299,7 @@ export async function pullFromGitHub(
 					if (item.type !== "blob") continue;
 					const relative = relativeWithinDocs(item.path, docsDir);
 					if (relative === item.path && docsDir !== "") continue;
+					if (isExcludedPath(relative)) continue;
 					if (
 						/\.(md|mdx)$/i.test(relative) ||
 						/^_dir\.ya?ml$/i.test(path.basename(relative))

package/src/runtime/components/ApiReference.tsx

@@ -0,0 +1,332 @@
+import { createSignal, For, Show } from "solid-js";
+import type { ApiEndpoint, ApiParameter } from "../types";
+import { DocMarkdown } from "./DocMarkdown";
+
+function CopyButton(props: { text: () => string; label?: string }) {
+	const [copied, setCopied] = createSignal(false);
+	return (
+		<button
+			type="button"
+			onClick={() => {
+				navigator.clipboard.writeText(props.text()).catch(() => {});
+				setCopied(true);
+				setTimeout(() => setCopied(false), 1500);
+			}}
+			class="px-2 h-6 inline-flex items-center gap-1 rounded text-[10px] text-muted hover:text-foreground hover:bg-surface transition-colors cursor-pointer border-none bg-transparent"
+		>
+			<span
+				class={copied() ? "i-mdi:check text-success" : "i-mdi:content-copy"}
+				aria-hidden="true"
+			/>
+			{copied() ? "Copied" : (props.label ?? "Copy")}
+		</button>
+	);
+}
+
+function SectionCard(props: {
+	title: string;
+	icon: string;
+	children: import("solid-js").JSX.Element;
+	actions?: import("solid-js").JSX.Element;
+}) {
+	return (
+		<section class="border border-border rounded-xl bg-surface/30 overflow-hidden mb-6">
+			<header class="flex items-center gap-2 px-4 py-2.5 border-b border-border bg-background/50">
+				<span class={`${props.icon} text-primary`} aria-hidden="true" />
+				<h2 class="text-sm font-semibold text-foreground m-0">{props.title}</h2>
+				<div class="ml-auto">{props.actions}</div>
+			</header>
+			<div class="p-4">{props.children}</div>
+		</section>
+	);
+}
+
+const IN_BADGE: Record<string, string> = {
+	path: "bg-primary/10 text-primary border-primary/30",
+	query: "bg-accent/10 text-accent border-accent/30",
+	header: "bg-warning/10 text-warning border-warning/30",
+	cookie: "bg-muted/10 text-muted border-border",
+};
+
+function statusClass(code: string): string {
+	const n = Number.parseInt(code, 10);
+	if (n >= 200 && n < 300)
+		return "bg-success/15 text-success border-success/30";
+	if (n >= 300 && n < 400) return "bg-accent/15 text-accent border-accent/30";
+	if (n >= 400 && n < 500)
+		return "bg-warning/15 text-warning border-warning/30";
+	if (n >= 500)
+		return "bg-destructive/15 text-destructive border-destructive/30";
+	return "bg-surface text-muted border-border";
+}
+
+function ParamRow(props: { p: ApiParameter }) {
+	return (
+		<div class="flex items-start gap-3 py-2.5 border-b border-border/50 last:border-0">
+			<div class="min-w-0 flex-1">
+				<div class="flex items-center gap-2 flex-wrap">
+					<code class="text-sm font-mono font-semibold text-foreground">
+						{props.p.name}
+					</code>
+					<span
+						class={`text-[10px] px-1.5 py-0.5 rounded border ${IN_BADGE[props.p.in] ?? IN_BADGE.query}`}
+					>
+						{props.p.in}
+					</span>
+					<Show
+						when={props.p.required}
+						fallback={<span class="text-[10px] text-muted">optional</span>}
+					>
+						<span class="text-[10px] px-1.5 py-0.5 rounded bg-destructive/10 text-destructive font-medium">
+							required
+						</span>
+					</Show>
+				</div>
+				<Show when={props.p.description}>
+					<p class="text-xs text-muted m-0 mt-1 leading-relaxed">
+						{props.p.description}
+					</p>
+				</Show>
+			</div>
+			<Show when={props.p.example != null}>
+				<code class="text-[11px] font-mono px-2 py-1 rounded bg-background border border-border text-muted shrink-0 max-w-40 truncate">
+					{typeof props.p.example === "string"
+						? props.p.example
+						: JSON.stringify(props.p.example)}
+				</code>
+			</Show>
+		</div>
+	);
+}
+
+function JsonBlock(props: { value: unknown }) {
+	const text = () => JSON.stringify(props.value, null, 2);
+	return (
+		<div class="relative rounded-lg bg-background border border-border">
+			<div class="absolute top-1.5 right-1.5">
+				<CopyButton text={text} />
+			</div>
+			<pre class="text-xs font-mono text-foreground p-3 m-0 overflow-x-auto whitespace-pre-wrap break-all">
+				{text()}
+			</pre>
+		</div>
+	);
+}
+
+function ResponseRow(props: {
+	code: string;
+	description: string;
+	example?: unknown;
+}) {
+	const [open, setOpen] = createSignal(false);
+	return (
+		<div class="border-b border-border/50 last:border-0">
+			<button
+				type="button"
+				onClick={() => props.example != null && setOpen(!open())}
+				class="w-full flex items-center gap-3 px-1 py-2.5 text-left cursor-pointer border-none bg-transparent"
+			>
+				<span
+					class={`inline-flex items-center justify-center min-w-12 px-2 py-0.5 rounded-md border text-xs font-bold font-mono ${statusClass(props.code)}`}
+				>
+					{props.code}
+				</span>
+				<span class="text-sm text-muted flex-1">{props.description}</span>
+				<Show when={props.example != null}>
+					<span
+						class={`i-mdi:chevron-down text-muted transition-transform ${open() ? "rotate-180" : ""}`}
+						aria-hidden="true"
+					/>
+				</Show>
+			</button>
+			<Show when={open() && props.example != null}>
+				<div class="pb-3">
+					<JsonBlock value={props.example} />
+				</div>
+			</Show>
+		</div>
+	);
+}
+
+function curlCommand(ep: ApiEndpoint, base?: string): string {
+	const url = `${base ?? ep.server ?? "https://api.example.com"}${ep.path}`;
+	const lines = [`curl -X ${ep.method} "${url}"`];
+	for (const p of ep.parameters.filter((x) => x.in === "header")) {
+		lines.push(`  -H "${p.name}: <value>"`);
+	}
+	if (ep.requestBody?.example != null) {
+		lines.push(`  -H "Content-Type: application/json"`);
+		lines.push(`  -d '${JSON.stringify(ep.requestBody.example)}'`);
+	}
+	return lines.join(" \\\n");
+}
+
+export function ApiReference(props: {
+	endpoint: ApiEndpoint;
+	style: "rest" | "graphql" | "cli" | "rpc";
+}) {
+	const ep = () => props.endpoint;
+	const codes = () => Object.keys(ep().responses);
+
+	return (
+		<div>
+			<Show when={ep().description}>
+				<div class="markdown-body mb-6">
+					<DocMarkdown source={ep().description ?? ""} />
+				</div>
+			</Show>
+
+			<Show when={props.style === "cli"}>
+				<SectionCard
+					title="Usage"
+					icon="i-mdi:console-line"
+					actions={
+						<CopyButton
+							text={() =>
+								ep().cli
+									? [
+											ep().cli!.command,
+											ep().cli!.subcommand,
+											...(ep().cli!.args?.map((a) =>
+												a.required ? `<${a.name}>` : `[${a.name}]`,
+											) ?? []),
+										].join(" ")
+									: `${ep().method} ${ep().path}`
+							}
+						/>
+					}
+				>
+					<pre class="text-sm font-mono text-foreground bg-background border border-border rounded-lg p-3 m-0 overflow-x-auto">
+						{ep().cli
+							? [
+									ep().cli!.command,
+									ep().cli!.subcommand,
+									...(ep().cli!.args?.map((a) =>
+										a.required ? `<${a.name}>` : `[${a.name}]`,
+									) ?? []),
+								].join(" ")
+							: `${ep().method} ${ep().path}`}
+					</pre>
+					<Show when={ep().cli?.args?.length}>
+						<div class="mt-4">
+							<For each={ep().cli?.args ?? []}>
+								{(a) => (
+									<div class="flex items-start gap-3 py-2 border-b border-border/50 last:border-0">
+										<code class="text-sm font-mono font-semibold text-foreground">
+											{a.name}
+										</code>
+										<Show when={a.required}>
+											<span class="text-[10px] px-1.5 py-0.5 rounded bg-destructive/10 text-destructive font-medium">
+												required
+											</span>
+										</Show>
+										<span class="text-xs text-muted flex-1">
+											{a.description}
+										</span>
+									</div>
+								)}
+							</For>
+						</div>
+					</Show>
+				</SectionCard>
+			</Show>
+
+			<Show when={props.style === "graphql"}>
+				<Show when={ep().graphql?.query}>
+					<SectionCard
+						title="Query"
+						icon="i-mdi:graphql"
+						actions={<CopyButton text={() => ep().graphql?.query ?? ""} />}
+					>
+						<pre class="text-xs font-mono text-foreground bg-background border border-border rounded-lg p-3 m-0 overflow-x-auto whitespace-pre-wrap">
+							{ep().graphql?.query}
+						</pre>
+					</SectionCard>
+				</Show>
+				<Show when={ep().graphql?.variables != null}>
+					<SectionCard title="Variables" icon="i-mdi:code-json">
+						<JsonBlock value={ep().graphql?.variables} />
+					</SectionCard>
+				</Show>
+			</Show>
+
+			<Show when={props.style === "rest" || props.style === "rpc"}>
+				<Show when={ep().parameters.length > 0}>
+					<SectionCard
+						title="Parameters"
+						icon="i-mdi:tune-variant"
+						actions={
+							<span class="text-[10px] text-muted">
+								{ep().parameters.length} field
+								{ep().parameters.length === 1 ? "" : "s"}
+							</span>
+						}
+					>
+						<For each={ep().parameters}>{(p) => <ParamRow p={p} />}</For>
+					</SectionCard>
+				</Show>
+
+				<Show when={ep().requestBody}>
+					<SectionCard
+						title="Request Body"
+						icon="i-mdi:code-braces"
+						actions={
+							<Show when={ep().requestBody?.required}>
+								<span class="text-[10px] px-1.5 py-0.5 rounded bg-destructive/10 text-destructive font-medium">
+									required
+								</span>
+							</Show>
+						}
+					>
+						<Show when={ep().requestBody?.description}>
+							<p class="text-sm text-muted m-0 mb-3 leading-relaxed">
+								{ep().requestBody?.description}
+							</p>
+						</Show>
+						<Show when={ep().requestBody?.example != null}>
+							<JsonBlock value={ep().requestBody?.example} />
+						</Show>
+					</SectionCard>
+				</Show>
+
+				<SectionCard
+					title="cURL"
+					icon="i-mdi:console"
+					actions={<CopyButton text={() => curlCommand(ep())} />}
+				>
+					<pre class="text-xs font-mono text-foreground bg-background border border-border rounded-lg p-3 m-0 overflow-x-auto whitespace-pre-wrap">
+						{curlCommand(ep())}
+					</pre>
+				</SectionCard>
+			</Show>
+
+			<Show when={ep().requestBody?.example != null && props.style === "cli"}>
+				<SectionCard title="Options" icon="i-mdi:code-json">
+					<JsonBlock value={ep().requestBody?.example} />
+				</SectionCard>
+			</Show>
+
+			<Show when={codes().length > 0}>
+				<SectionCard
+					title={props.style === "cli" ? "Exit codes" : "Responses"}
+					icon="i-mdi:reply-outline"
+					actions={
+						<span class="text-[10px] text-muted">
+							{codes().length} code{codes().length === 1 ? "" : "s"}
+						</span>
+					}
+				>
+					<For each={codes()}>
+						{(code) => (
+							<ResponseRow
+								code={code}
+								description={ep().responses[code]?.description ?? ""}
+								example={ep().responses[code]?.example}
+							/>
+						)}
+					</For>
+				</SectionCard>
+			</Show>
+		</div>
+	);
+}