@raybase/docs 0.0.2 → 0.1.3

package/templates/astro-emdash/site/src/docs/docs-page-actions.tsx

@@ -0,0 +1,146 @@
+import { Check, ChevronDown, Copy, ExternalLink, FileText, Sparkles } from "lucide-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+
+interface DocsPageActionsProps {
+  markdownUrl: string;
+  title: string;
+}
+
+export function DocsPageActions(props: DocsPageActionsProps) {
+  const [copyState, setCopyState] = useState<"idle" | "copying" | "copied" | "failed">("idle");
+  const [open, setOpen] = useState(false);
+  const [origin, setOrigin] = useState("");
+  const menuRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    setOrigin(window.location.origin);
+  }, []);
+
+  useEffect(() => {
+    if (!open) return;
+
+    function onPointerDown(event: PointerEvent) {
+      if (!menuRef.current?.contains(event.target as Node)) {
+        setOpen(false);
+      }
+    }
+
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") {
+        setOpen(false);
+      }
+    }
+
+    document.addEventListener("pointerdown", onPointerDown);
+    document.addEventListener("keydown", onKeyDown);
+
+    return () => {
+      document.removeEventListener("pointerdown", onPointerDown);
+      document.removeEventListener("keydown", onKeyDown);
+    };
+  }, [open]);
+
+  const absoluteMarkdownUrl = useMemo(() => {
+    if (!origin) return props.markdownUrl;
+    return new URL(props.markdownUrl, origin).toString();
+  }, [origin, props.markdownUrl]);
+
+  const aiPrompt = useMemo(() => {
+    return `Read this documentation page and help me use it:\n\n${absoluteMarkdownUrl}`;
+  }, [absoluteMarkdownUrl]);
+
+  const options = [
+    {
+      label: "View as Markdown",
+      href: props.markdownUrl,
+      icon: FileText
+    },
+    {
+      label: "Open in ChatGPT",
+      href: `https://chatgpt.com/?q=${encodeURIComponent(aiPrompt)}`,
+      icon: Sparkles
+    },
+    {
+      label: "Open in Claude",
+      href: `https://claude.ai/new?q=${encodeURIComponent(aiPrompt)}`,
+      icon: Sparkles
+    }
+  ];
+
+  const copyLabel = {
+    idle: "Copy as Markdown",
+    copying: "Copying",
+    copied: "Copied",
+    failed: "Copy failed"
+  }[copyState];
+
+  async function copyMarkdown() {
+    setCopyState("copying");
+
+    try {
+      const response = await fetch(props.markdownUrl);
+
+      if (!response.ok) {
+        throw new Error(`Failed to load Markdown for ${props.title}`);
+      }
+
+      await navigator.clipboard.writeText(await response.text());
+      setCopyState("copied");
+    } catch {
+      setCopyState("failed");
+    } finally {
+      window.setTimeout(() => setCopyState("idle"), 1600);
+    }
+  }
+
+  return (
+    <div className="not-prose my-6 flex flex-wrap items-center gap-2 border-y border-fd-border/70 py-3 text-sm">
+      <button
+        className="inline-flex h-9 items-center gap-2 rounded-md border border-fd-border bg-fd-background px-3 font-medium text-fd-foreground shadow-xs transition hover:bg-fd-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring"
+        disabled={copyState === "copying"}
+        type="button"
+        onClick={() => void copyMarkdown()}
+      >
+        {copyState === "copied" ? <Check className="size-4" aria-hidden="true" /> : <Copy className="size-4" aria-hidden="true" />}
+        {copyLabel}
+      </button>
+
+      <div className="relative" ref={menuRef}>
+        <button
+          aria-expanded={open}
+          aria-haspopup="menu"
+          className="inline-flex h-9 items-center gap-2 rounded-md border border-fd-border bg-fd-background px-3 font-medium text-fd-foreground shadow-xs transition hover:bg-fd-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring"
+          type="button"
+          onClick={() => setOpen((value) => !value)}
+        >
+          Open
+          <ChevronDown className="size-4 text-fd-muted-foreground" aria-hidden="true" />
+        </button>
+
+        {open ? (
+          <div className="absolute left-0 top-10 z-20 w-56 overflow-hidden rounded-md border border-fd-border bg-fd-popover p-1 text-fd-popover-foreground shadow-lg" role="menu">
+            {options.map((option) => {
+              const Icon = option.icon;
+
+              return (
+                <a
+                  className="flex min-h-9 items-center gap-2 rounded-sm px-2.5 py-2 text-sm outline-none transition hover:bg-fd-muted focus-visible:bg-fd-muted"
+                  href={option.href}
+                  key={option.label}
+                  onClick={() => setOpen(false)}
+                  rel="noreferrer"
+                  role="menuitem"
+                  target="_blank"
+                >
+                  <Icon className="size-4 text-fd-muted-foreground" aria-hidden="true" />
+                  <span className="min-w-0 flex-1 truncate">{option.label}</span>
+                  <ExternalLink className="size-3.5 text-fd-muted-foreground" aria-hidden="true" />
+                </a>
+              );
+            })}
+          </div>
+        ) : null}
+      </div>
+    </div>
+  );
+}

package/templates/astro-emdash/site/src/docs/docs-page.tsx

@@ -0,0 +1,70 @@
+import browserCollections from "collections/browser";
+import { FrameworkProvider } from "fumadocs-core/framework";
+import { useFumadocsLoader, type SerializedPageTree } from "fumadocs-core/source/client";
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
+import { DocsBody, DocsDescription, DocsPage, DocsTitle } from "fumadocs-ui/layouts/docs/page";
+import { RootProvider } from "fumadocs-ui/provider/base";
+import { DocsPageActions } from "./docs-page-actions";
+import { baseOptions } from "./docs-layout";
+import { getMDXComponents } from "./docs-mdx";
+
+export type DocsPageData = {
+  path: string;
+  url: string;
+  title: string;
+  description?: string;
+  pageTree: SerializedPageTree;
+};
+
+const clientLoader = browserCollections.docs.createClientLoader({
+  component({ toc, frontmatter, default: MDX }) {
+    const pageUrl = currentDocsData.url.replace(/\/$/, "") || "/docs";
+    const markdownUrl = pageUrl === "/docs" ? "/docs/index.md" : `${pageUrl}.md`;
+
+    return (
+      <DocsPage toc={toc}>
+        <DocsTitle>{frontmatter.title}</DocsTitle>
+        <DocsDescription>{frontmatter.description}</DocsDescription>
+        <DocsPageActions markdownUrl={markdownUrl} title={frontmatter.title} />
+        <DocsBody>
+          <MDX components={getMDXComponents()} />
+        </DocsBody>
+      </DocsPage>
+    );
+  }
+});
+
+let currentDocsData: { url: string } = { url: "/docs" };
+
+export async function preloadDocsContent(data: DocsPageData): Promise<void> {
+  currentDocsData = data;
+  await clientLoader.preload(data.path);
+}
+
+export function DocsRoot({ data }: { data: DocsPageData }) {
+  currentDocsData = data;
+  const loaderData = useFumadocsLoader(data);
+  const content = clientLoader.useContent(loaderData.path);
+
+  return (
+    <FrameworkProvider
+      Link={({ href, prefetch: _prefetch, ...props }) => <a href={href} {...props} />}
+      useParams={() => ({})}
+      usePathname={() => currentDocsData.url}
+      useRouter={() => ({
+        push(url) {
+          if (typeof window !== "undefined") window.location.href = url;
+        },
+        refresh() {
+          if (typeof window !== "undefined") window.location.reload();
+        }
+      })}
+    >
+      <RootProvider search={{ options: { api: "/docs/api/search" } }}>
+        <DocsLayout {...baseOptions()} tree={loaderData.pageTree}>
+          {content}
+        </DocsLayout>
+      </RootProvider>
+    </FrameworkProvider>
+  );
+}

package/templates/astro-emdash/site/src/docs/llm-text.ts

@@ -0,0 +1,61 @@
+import { source } from "./source";
+
+type DocsPage = ReturnType<typeof source.getPage>;
+
+export async function getDocsMarkdownResponse(path: string | null) {
+  const page = source.getPage(getDocsSlugs(path));
+
+  if (!page) {
+    return null;
+  }
+
+  return markdownResponse(await getLLMText(page));
+}
+
+export async function getLLMText(page: NonNullable<DocsPage>) {
+  const markdown = renderRuntimeMdxPlaceholders((await page.data.getText("processed")) ?? "");
+
+  return `# ${page.data.title} (${page.url})\n\n${markdown}`;
+}
+
+function renderRuntimeMdxPlaceholders(markdown: string) {
+  return markdown
+    .replace(/<McpServerUrl(Block)?([^>]*)\/>/g, (_match, block: string | undefined, attrs: string) => {
+      const value = `[current-app-origin]${mdxStringAttribute(attrs, "path") ?? "/mcp"}`;
+      return block ? `\`\`\`text\n${value}\n\`\`\`` : `\`${value}\``;
+    })
+    .replace(/<ClaudeMcpAddCommand([^>]*)\/>/g, (_match, attrs: string) => {
+      const path = mdxStringAttribute(attrs, "path") ?? "/mcp";
+      const name = mdxStringAttribute(attrs, "name") ?? "this-app";
+      return `\`\`\`bash\nclaude mcp add --transport http ${name} "[current-app-origin]${path}"\n\`\`\``;
+    })
+    .replace(/<CodexMcpAddCommand([^>]*)\/>/g, (_match, attrs: string) => {
+      const path = mdxStringAttribute(attrs, "path") ?? "/mcp";
+      const name = mdxStringAttribute(attrs, "name") ?? "this-app";
+      return `\`\`\`bash\ncodex mcp add ${name} --url "[current-app-origin]${path}"\n\`\`\``;
+    });
+}
+
+function mdxStringAttribute(attrs: string, name: string) {
+  const match = attrs.match(new RegExp(`\\b${name}="([^"]*)"`));
+  return match?.[1] ?? null;
+}
+
+export function markdownResponse(markdown: string) {
+  return new Response(markdown, {
+    headers: {
+      "content-type": "text/markdown; charset=utf-8"
+    }
+  });
+}
+
+export function getDocsSlugs(path: string | null) {
+  const pathname = path?.trim() || "/docs";
+  const withoutBase = pathname
+    .replace(/\.mdx?$/, "")
+    .replace(/^\/docs(?:\/|$)/, "")
+    .replace(/^\/+|\/+$/g, "");
+  const withoutIndex = withoutBase === "index" ? "" : withoutBase.replace(/\/index$/, "");
+
+  return withoutIndex ? withoutIndex.split("/").filter(Boolean) : [];
+}

package/templates/astro-emdash/site/src/docs/source.ts

@@ -0,0 +1,7 @@
+import { docs } from "collections/server";
+import { loader } from "fumadocs-core/source";
+
+export const source = loader({
+  baseUrl: "/docs",
+  source: docs.toFumadocsSource()
+});

package/templates/astro-emdash/site/src/pages/docs/[...slug].ts

@@ -0,0 +1,6 @@
+export async function ALL({ request }: { request: Request }): Promise<Response> {
+  const { handleDocsRequest } = await import("../../docs/docs-handler");
+  return handleDocsRequest(request);
+}
+
+export const GET = ALL;

package/templates/astro-emdash/site/src/pages/docs/api/markdown.ts

@@ -0,0 +1,4 @@
+export async function GET({ request }: { request: Request }): Promise<Response> {
+  const { handleDocsRequest } = await import("../../../docs/docs-handler");
+  return handleDocsRequest(request);
+}

package/templates/astro-emdash/site/src/pages/docs/api/search.ts

@@ -0,0 +1,4 @@
+export async function GET({ request }: { request: Request }): Promise<Response> {
+  const { handleDocsRequest } = await import("../../../docs/docs-handler");
+  return handleDocsRequest(request);
+}

package/templates/astro-emdash/site/src/pages/llms.txt.ts

@@ -0,0 +1,8 @@
+import { getLLMText, markdownResponse } from "../docs/llm-text";
+import { source } from "../docs/source";
+
+export async function GET(): Promise<Response> {
+  const pages = source.getPages().sort((left, right) => left.url.localeCompare(right.url));
+  const body = (await Promise.all(pages.map((page) => getLLMText(page)))).join("\n\n---\n\n");
+  return markdownResponse(body);
+}

package/templates/astro-emdash/site/src/styles-docs.css

@@ -0,0 +1,3 @@
+@import "tailwindcss";
+@import "fumadocs-ui/css/neutral.css";
+@import "fumadocs-ui/css/preset.css";

package/templates/astro-emdash/source.config.ts

@@ -0,0 +1,10 @@
+import { defineDocs } from "fumadocs-mdx/config";
+
+export const docs = defineDocs({
+  dir: "content/docs",
+  docs: {
+    postprocess: {
+      includeProcessedMarkdown: true
+    }
+  }
+});

package/templates/astro-emdash/src/docs/docs-assets.ts

@@ -0,0 +1 @@
+export const docsClientScriptSrc = import.meta.env.DEV ? "/src/docs/docs-client.tsx" : "/assets/raybase-docs-client.js";

package/templates/astro-emdash/src/docs/docs-client.tsx

@@ -0,0 +1,22 @@
+import "@vitejs/plugin-react/preamble";
+import { StrictMode, startTransition } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { DocsRoot, preloadDocsContent, type DocsPageData } from "./docs-page";
+
+const root = document.getElementById("raybase-docs-root");
+const dataScript = document.getElementById("raybase-docs-page-data");
+
+if (root && dataScript?.textContent) {
+  const data = JSON.parse(dataScript.textContent) as DocsPageData;
+
+  startTransition(() => {
+    void preloadDocsContent(data).then(() => {
+      hydrateRoot(
+        root,
+        <StrictMode>
+          <DocsRoot data={data} />
+        </StrictMode>
+      );
+    });
+  });
+}

package/templates/astro-emdash/src/docs/docs-data.ts

@@ -0,0 +1,24 @@
+import type { SerializedPageTree } from "fumadocs-core/source/client";
+import type { DocsPageData } from "./docs-page";
+import { preloadDocsContent } from "./docs-page";
+import { source } from "./source";
+
+export async function loadDocsPageTree(): Promise<SerializedPageTree> {
+  return source.serializePageTree(source.getPageTree());
+}
+
+export async function loadDocsPageData(slugs: string[]): Promise<DocsPageData | null> {
+  const page = source.getPage(slugs);
+  if (!page) return null;
+
+  const data = {
+    path: page.path,
+    url: page.url,
+    title: page.data.title,
+    description: page.data.description,
+    pageTree: await loadDocsPageTree()
+  } satisfies DocsPageData;
+
+  await preloadDocsContent(data);
+  return data;
+}

package/templates/astro-emdash/src/docs/docs-handler.tsx

@@ -0,0 +1,105 @@
+import { createFromSource } from "fumadocs-core/search/server";
+import { renderToReadableStream } from "react-dom/server";
+import docsCss from "../styles-docs.css?inline";
+import { docsClientScriptSrc } from "./docs-assets";
+import { loadDocsPageData, loadDocsPageTree } from "./docs-data";
+import { DocsRoot, type DocsPageData } from "./docs-page";
+import { getDocsMarkdownResponse, getDocsSlugs } from "./llm-text";
+import { source } from "./source";
+
+const docsThemeInitScript =
+  "(function(){try{var t=localStorage.getItem('theme');var d=t==='dark'||((!t||t==='system')&&matchMedia('(prefers-color-scheme: dark)').matches);document.documentElement.classList.toggle('dark',d);}catch(e){}})();";
+
+const search = createFromSource(source, {
+  language: "english"
+});
+
+export async function handleDocsRequest(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+
+  if (url.pathname === "/docs/api/search") {
+    return search.GET(request);
+  }
+
+  if (url.pathname === "/docs/api/markdown") {
+    const response = await getDocsMarkdownResponse(url.searchParams.get("path"));
+    return response ?? new Response("Not found", { status: 404 });
+  }
+
+  if (/\.mdx?$/.test(url.pathname)) {
+    const response = await getDocsMarkdownResponse(url.pathname);
+    return response ?? new Response("Not found", { status: 404 });
+  }
+
+  const data = await loadDocsPageData(getDocsSlugs(url.pathname));
+  if (!data) {
+    return docsHtmlResponse(
+      {
+        path: "",
+        url: url.pathname,
+        title: "Docs page not found",
+        pageTree: await loadDocsPageTree()
+      },
+      "<main class=\"mx-auto flex min-h-screen max-w-3xl flex-col justify-center px-6 py-16\"><p class=\"text-sm font-medium text-fd-muted-foreground\">404</p><h1 class=\"mt-3 text-3xl font-semibold text-fd-foreground\">Docs page not found</h1><p class=\"mt-3 text-fd-muted-foreground\">The requested documentation page does not exist.</p><a class=\"mt-6 inline-flex text-sm font-medium text-fd-primary underline-offset-4 hover:underline\" href=\"/docs\">Back to docs</a></main>",
+      404
+    );
+  }
+
+  return docsHtmlResponse(data, await renderDocsBody(data));
+}
+
+async function renderDocsBody(data: DocsPageData): Promise<string> {
+  const stream = await renderToReadableStream(<DocsRoot data={cloneDocsPageData(data)} />);
+  await stream.allReady;
+  return new Response(stream).text();
+}
+
+function cloneDocsPageData(data: DocsPageData): DocsPageData {
+  return JSON.parse(JSON.stringify(data)) as DocsPageData;
+}
+
+function docsHtmlResponse(data: DocsPageData, body: string, status = 200): Response {
+  const html = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(data.title)}</title>
+    <script>${docsThemeInitScript}</script>
+    <style id="raybase-docs-styles">${docsCss}</style>
+  </head>
+  <body>
+    <div id="raybase-docs-root">${body}</div>
+    <script type="application/json" id="raybase-docs-page-data">${escapeJson(data)}</script>
+    <script type="module" async src="${docsClientScriptSrc}"></script>
+  </body>
+</html>`;
+
+  return new Response(html, {
+    status,
+    headers: {
+      "content-type": "text/html; charset=utf-8"
+    }
+  });
+}
+
+function escapeJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (char) => {
+    switch (char) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case "\"":
+        return "&quot;";
+      default:
+        return "&#39;";
+    }
+  });
+}

package/templates/astro-emdash/src/docs/docs-layout.tsx

@@ -0,0 +1,56 @@
+import type { DocsLayoutProps } from "fumadocs-ui/layouts/docs";
+import type { ComponentProps } from "react";
+import { ThemeSwitch } from "fumadocs-ui/layouts/shared/slots/theme-switch";
+import { ArrowLeft } from "lucide-react";
+import { appConfig } from "../raybase.config";
+
+const appHomeHref = "/";
+
+export function baseOptions(): Omit<DocsLayoutProps, "children" | "tree"> {
+  return {
+    nav: {
+      title: DocsNavTitle,
+      url: appHomeHref
+    },
+    sidebar: {
+      footer: <DocsSidebarFooter />
+    },
+    themeSwitch: {
+      enabled: false
+    }
+  };
+}
+
+function DocsNavTitle({ className, href = appHomeHref, ...props }: ComponentProps<"a">) {
+  return (
+    <div className={className}>
+      <div className="inline-flex min-w-0 flex-col items-start gap-0.5 leading-none">
+        <a
+          {...props}
+          href={href}
+          title={`Back to ${appConfig.appName}`}
+          className="max-w-44 truncate rounded-sm text-[0.9375rem] font-semibold leading-none text-fd-foreground underline-offset-4 transition-colors hover:text-fd-primary hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring"
+        >
+          {appConfig.appName}
+        </a>
+        <span className="text-[0.6875rem] font-medium leading-none text-fd-muted-foreground">Docs</span>
+      </div>
+    </div>
+  );
+}
+
+function DocsSidebarFooter() {
+  return (
+    <div className="mt-2 flex min-w-0 items-center justify-between gap-3 border-t pt-3">
+      <a
+        href={appHomeHref}
+        title={`Back to ${appConfig.appName}`}
+        className="inline-flex min-w-0 items-center gap-1.5 rounded-md px-1 py-1 text-xs font-medium text-fd-muted-foreground transition-colors hover:text-fd-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring"
+      >
+        <ArrowLeft className="size-3.5 shrink-0" aria-hidden="true" />
+        <span className="truncate">Back to app</span>
+      </a>
+      <ThemeSwitch className="shrink-0 p-0" />
+    </div>
+  );
+}

package/templates/astro-emdash/src/docs/docs-mdx.tsx

@@ -0,0 +1,79 @@
+import { CodeBlock, Pre } from "fumadocs-ui/components/codeblock";
+import defaultMdxComponents from "fumadocs-ui/mdx";
+import type { MDXComponents } from "mdx/types";
+
+interface McpServerUrlProps {
+  path?: string;
+}
+
+interface ClaudeMcpAddCommandProps extends McpServerUrlProps {
+  name?: string;
+}
+
+interface CodexMcpAddCommandProps extends McpServerUrlProps {
+  name?: string;
+}
+
+function browserOrigin() {
+  return typeof window === "undefined" ? "" : window.location.origin;
+}
+
+function currentUrl(path = "/mcp") {
+  const origin = browserOrigin();
+  return origin ? new URL(path, origin).toString() : path;
+}
+
+function McpServerUrl(props: McpServerUrlProps) {
+  return <code suppressHydrationWarning>{currentUrl(props.path)}</code>;
+}
+
+function McpServerUrlBlock(props: McpServerUrlProps) {
+  return (
+    <CodeBlock>
+      <Pre>
+        <code suppressHydrationWarning>{currentUrl(props.path)}</code>
+      </Pre>
+    </CodeBlock>
+  );
+}
+
+function ClaudeMcpAddCommand(props: ClaudeMcpAddCommandProps) {
+  const command = `claude mcp add --transport http ${props.name ?? "this-app"} "${currentUrl(props.path)}"`;
+
+  return (
+    <CodeBlock>
+      <Pre>
+        <code suppressHydrationWarning>{command}</code>
+      </Pre>
+    </CodeBlock>
+  );
+}
+
+function CodexMcpAddCommand(props: CodexMcpAddCommandProps) {
+  const command = `codex mcp add ${props.name ?? "this-app"} --url "${currentUrl(props.path)}"`;
+
+  return (
+    <CodeBlock>
+      <Pre>
+        <code suppressHydrationWarning>{command}</code>
+      </Pre>
+    </CodeBlock>
+  );
+}
+
+export function getMDXComponents(components?: MDXComponents) {
+  return {
+    ...defaultMdxComponents,
+    McpServerUrl,
+    McpServerUrlBlock,
+    ClaudeMcpAddCommand,
+    CodexMcpAddCommand,
+    ...components
+  } satisfies MDXComponents;
+}
+
+export const useMDXComponents = getMDXComponents;
+
+declare global {
+  type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
+}