@raybase/docs 0.0.1 → 0.1.2

package/templates/astro-emdash/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/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/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/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/src/routes/docs/$.tsx

@@ -0,0 +1,22 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { useEffect } from "react";
+
+export const Route = createFileRoute("/docs/$")({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const { handleDocsRequest } = await import("../../docs/docs-handler");
+        return handleDocsRequest(request);
+      }
+    }
+  },
+  component: DocumentNavigationFallback
+});
+
+function DocumentNavigationFallback() {
+  useEffect(() => {
+    window.location.assign(window.location.href);
+  }, []);
+
+  return null;
+}

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

@@ -0,0 +1,12 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/docs/api/markdown")({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const { handleDocsRequest } = await import("../../../docs/docs-handler");
+        return handleDocsRequest(request);
+      }
+    }
+  }
+});

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

@@ -0,0 +1,12 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/docs/api/search")({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const { handleDocsRequest } = await import("../../../docs/docs-handler");
+        return handleDocsRequest(request);
+      }
+    }
+  }
+});

package/templates/astro-emdash/src/routes/docs.index.tsx

@@ -0,0 +1,22 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { useEffect } from "react";
+
+export const Route = createFileRoute("/docs/")({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const { handleDocsRequest } = await import("../docs/docs-handler");
+        return handleDocsRequest(request);
+      }
+    }
+  },
+  component: DocumentNavigationFallback
+});
+
+function DocumentNavigationFallback() {
+  useEffect(() => {
+    window.location.assign(window.location.href);
+  }, []);
+
+  return null;
+}

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

@@ -0,0 +1,22 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { useEffect } from "react";
+
+export const Route = createFileRoute("/docs")({
+  server: {
+    handlers: {
+      GET: async ({ request }) => {
+        const { handleDocsRequest } = await import("../docs/docs-handler");
+        return handleDocsRequest(request);
+      }
+    }
+  },
+  component: DocumentNavigationFallback
+});
+
+function DocumentNavigationFallback() {
+  useEffect(() => {
+    window.location.assign(window.location.href);
+  }, []);
+
+  return null;
+}

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

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

package/templates/react-router/app/components/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>;
+}

package/templates/react-router/app/lib/layout.shared.tsx

@@ -0,0 +1,54 @@
+import type { DocsLayoutProps } from "fumadocs-ui/layouts/docs";
+import type { ComponentProps } from "react";
+import { ArrowLeft } from "lucide-react";
+
+const appName = "__APP_NAME__";
+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 ${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"
+        >
+          {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 border-t pt-3">
+      <a
+        href={appHomeHref}
+        title={`Back to ${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>
+    </div>
+  );
+}

package/templates/react-router/app/lib/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/react-router/app/routes/docs.$.tsx

@@ -0,0 +1,49 @@
+import { useLoaderData } from "react-router";
+import { useFumadocsLoader } from "fumadocs-core/source/client";
+import browserCollections from "collections/browser";
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
+import {
+  DocsBody,
+  DocsDescription,
+  DocsPage,
+  DocsTitle
+} from "fumadocs-ui/layouts/docs/page";
+import { getMDXComponents } from "../components/mdx";
+import { baseOptions } from "../lib/layout.shared";
+import { source } from "../lib/source";
+
+export async function loader({ params }: { params: { "*": string | undefined } }) {
+  const slugs = params["*"]?.split("/").filter(Boolean) ?? [];
+  const page = source.getPage(slugs);
+  if (!page) throw new Response("Not found", { status: 404 });
+
+  return {
+    path: page.path,
+    pageTree: await source.serializePageTree(source.getPageTree())
+  };
+}
+
+const clientLoader = browserCollections.docs.createClientLoader({
+  component({ toc, frontmatter, default: MDX }) {
+    return (
+      <DocsPage toc={toc}>
+        <DocsTitle>{frontmatter.title}</DocsTitle>
+        <DocsDescription>{frontmatter.description}</DocsDescription>
+        <DocsBody>
+          <MDX components={getMDXComponents()} />
+        </DocsBody>
+      </DocsPage>
+    );
+  }
+});
+
+export default function DocsRoute() {
+  const data = useFumadocsLoader(useLoaderData<typeof loader>());
+  const content = clientLoader.useContent(data.path);
+
+  return (
+    <DocsLayout {...baseOptions()} tree={data.pageTree}>
+      {content}
+    </DocsLayout>
+  );
+}

package/templates/react-router/app/routes/docs.api.search.ts

@@ -0,0 +1,10 @@
+import { createFromSource } from "fumadocs-core/search/server";
+import { source } from "../lib/source";
+
+const search = createFromSource(source, {
+  language: "english"
+});
+
+export async function loader({ request }: { request: Request }) {
+  return search.GET(request);
+}

package/templates/react-router/app/routes/docs.tsx

@@ -0,0 +1,13 @@
+import { Outlet } from "react-router";
+import { RootProvider } from "fumadocs-ui/provider/react-router";
+
+export default function DocsLayoutRoute() {
+  return (
+    <RootProvider
+      search={{ options: { api: "/docs/api/search" } }}
+      theme={{ enabled: false }}
+    >
+      <Outlet />
+    </RootProvider>
+  );
+}

package/templates/react-router/content/docs/getting-started.mdx

@@ -0,0 +1,8 @@
+---
+title: Getting started
+description: Replace this page with the first real workflow guide.
+---
+
+Replace this placeholder with the first workflow a real user or operator needs.
+
+Document behavior only after it exists in the app. Avoid promising screens, APIs, permissions, or automations that have not been implemented.

package/templates/react-router/content/docs/index.mdx

@@ -0,0 +1,8 @@
+---
+title: Welcome to the docs
+description: Start here when replacing the placeholder documentation.
+---
+
+Use this space for product, operator, and API documentation once those workflows exist.
+
+Keep docs in `content/docs`, and update the page tree as the documentation grows.