blodemd 0.0.4 → 0.0.6

package/docs/lib/contextual-options.ts

@@ -0,0 +1,193 @@
+import type {
+  ContextualBuiltinOption,
+  ContextualCustomOption,
+} from "@repo/models";
+
+interface BuiltinOptionDefinition {
+  title: string;
+  description: string;
+  iconName: string;
+  type: "action" | "link";
+}
+
+export const builtinOptions: Record<
+  ContextualBuiltinOption,
+  BuiltinOptionDefinition
+> = {
+  "add-mcp": {
+    description: "Copy the npx add-mcp command",
+    iconName: "CodeBracketsIcon",
+    title: "Copy MCP install command",
+    type: "action",
+  },
+  aistudio: {
+    description: "Ask questions about this page",
+    iconName: "GoogleColoredIcon",
+    title: "Open in Google AI Studio",
+    type: "link",
+  },
+  assistant: {
+    description: "Open the assistant with this page as context",
+    iconName: "SparkleIcon",
+    title: "Ask assistant",
+    type: "action",
+  },
+  chatgpt: {
+    description: "Ask questions about this page",
+    iconName: "OpenaiIcon",
+    title: "Open in ChatGPT",
+    type: "link",
+  },
+  claude: {
+    description: "Ask questions about this page",
+    iconName: "ClaudeaiIcon",
+    title: "Open in Claude",
+    type: "link",
+  },
+  copy: {
+    description: "Copy page as Markdown for LLMs",
+    iconName: "CopySimpleIcon",
+    title: "Copy page",
+    type: "action",
+  },
+  cursor: {
+    description: "Install MCP server in Cursor",
+    iconName: "CodeIcon",
+    title: "Connect to Cursor",
+    type: "link",
+  },
+  devin: {
+    description: "Create a Devin session with this page",
+    iconName: "CodeAssistantIcon",
+    title: "Open in Devin",
+    type: "link",
+  },
+  "devin-mcp": {
+    description: "Install MCP server in Devin",
+    iconName: "CodeAssistantIcon",
+    title: "Connect to Devin",
+    type: "link",
+  },
+  grok: {
+    description: "Ask questions about this page",
+    iconName: "GrokIcon",
+    title: "Open in Grok",
+    type: "link",
+  },
+  mcp: {
+    description: "Copy your MCP server URL to clipboard",
+    iconName: "Plugin1Icon",
+    title: "Copy MCP server URL",
+    type: "action",
+  },
+  perplexity: {
+    description: "Ask questions about this page",
+    iconName: "PerplexityIcon",
+    title: "Open in Perplexity",
+    type: "link",
+  },
+  view: {
+    description: "Open the current page as Markdown",
+    iconName: "MarkdownIcon",
+    title: "View as Markdown",
+    type: "link",
+  },
+  vscode: {
+    description: "Install MCP server in VS Code",
+    iconName: "CodeLinesIcon",
+    title: "Connect to VS Code",
+    type: "link",
+  },
+  windsurf: {
+    description: "Open Windsurf Cascade with this page",
+    iconName: "WindIcon",
+    title: "Open in Windsurf",
+    type: "link",
+  },
+};
+
+interface UrlContext {
+  pageUrl: string;
+  pagePath: string;
+  pageContent: string;
+  mcpServerUrl?: string;
+}
+
+const askPrompt = (url: string) =>
+  `Read from ${url} so I can ask questions about it.`;
+
+const encoded = (text: string) => encodeURIComponent(text);
+
+export const buildBuiltinUrl = (
+  id: ContextualBuiltinOption,
+  context: UrlContext
+): string | null => {
+  const { pageUrl, pagePath, mcpServerUrl } = context;
+
+  switch (id) {
+    case "chatgpt": {
+      return `https://chatgpt.com/?hints=search&q=${encoded(askPrompt(pageUrl))}`;
+    }
+    case "claude": {
+      return `https://claude.ai/new?q=${encoded(askPrompt(pageUrl))}`;
+    }
+    case "perplexity": {
+      return `https://www.perplexity.ai/?q=${encoded(askPrompt(pageUrl))}`;
+    }
+    case "grok": {
+      return `https://grok.com/?q=${encoded(askPrompt(pageUrl))}`;
+    }
+    case "aistudio": {
+      return `https://aistudio.google.com/prompts/new_chat?q=${encoded(askPrompt(pageUrl))}`;
+    }
+    case "devin": {
+      return `https://app.devin.ai/sessions?url=${encoded(pageUrl)}`;
+    }
+    case "windsurf": {
+      return `windsurf://cascade?url=${encoded(pageUrl)}`;
+    }
+    case "view": {
+      const mdxPath = pagePath === "index" ? "/index" : `/${pagePath}`;
+      return `${mdxPath}.mdx`;
+    }
+    case "cursor": {
+      return mcpServerUrl
+        ? `cursor://anysphere.cursor-deeplink/mcp/install?url=${encoded(mcpServerUrl)}`
+        : null;
+    }
+    case "vscode": {
+      return mcpServerUrl
+        ? `vscode://anysphere.open-mcp?url=${encoded(mcpServerUrl)}`
+        : null;
+    }
+    case "devin-mcp": {
+      return mcpServerUrl
+        ? `https://app.devin.ai/mcp/install?url=${encoded(mcpServerUrl)}`
+        : null;
+    }
+    default: {
+      return null;
+    }
+  }
+};
+
+export const resolveCustomHref = (
+  href: ContextualCustomOption["href"],
+  context: UrlContext
+): string => {
+  const substitute = (value: string) =>
+    value
+      .replaceAll("$page", context.pageContent)
+      .replaceAll("$path", context.pagePath)
+      .replaceAll("$mcp", context.mcpServerUrl ?? "");
+
+  if (typeof href === "string") {
+    return substitute(href);
+  }
+
+  const params = new URLSearchParams();
+  for (const item of href.query) {
+    params.set(item.key, substitute(item.value));
+  }
+  return `${href.base}?${params.toString()}`;
+};

package/docs/lib/docs-collection.ts

@@ -0,0 +1,22 @@
+import type { SiteConfig } from "@repo/models";
+
+export const getDocsCollection = (
+  config: SiteConfig
+): SiteConfig["collections"][number] | undefined =>
+  config.collections.find((collection) => collection.type === "docs");
+
+export const getDocsNavigation = (config: SiteConfig) =>
+  getDocsCollection(config)?.navigation ?? config.navigation;
+
+export const getDocsCollectionWithNavigation = (
+  config: SiteConfig
+): SiteConfig["collections"][number] | undefined => {
+  const docsCollection = getDocsCollection(config);
+  const docsNavigation = getDocsNavigation(config);
+
+  return docsCollection &&
+    docsNavigation &&
+    docsCollection.navigation !== docsNavigation
+    ? { ...docsCollection, navigation: docsNavigation }
+    : docsCollection;
+};

package/docs/lib/mdx.ts

@@ -0,0 +1,90 @@
+import { run } from "@mdx-js/mdx";
+import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
+import { compileMDX } from "next-mdx-remote/rsc";
+import { createElement } from "react";
+import type { ComponentType } from "react";
+import * as jsxRuntime from "react/jsx-runtime";
+import rehypeAutolinkHeadings from "rehype-autolink-headings";
+import rehypeSlug from "rehype-slug";
+import remarkGfm from "remark-gfm";
+
+import { mdxComponents } from "@/components/mdx";
+
+import { getHighlighter } from "./shiki";
+
+const FRONTMATTER_REGEX = /^---\s*\n[\s\S]*?\n---\s*\n?/;
+
+const stripFrontmatter = (source: string) => ({
+  body: source.replace(FRONTMATTER_REGEX, ""),
+  frontmatter: {} as Record<string, unknown>,
+});
+
+/**
+ * Renders pre-compiled MDX content. The `compiledSource` is a JS function body
+ * produced by `@repo/mdx-compiler` at deploy time via `compile()` with
+ * `outputFormat: 'function-body'`. This is the fast path — no parsing,
+ * no plugin execution, no Shiki. Sub-millisecond execution.
+ */
+export const renderFromCompiled = async (compiledSource: string) => {
+  const mdxModule = await run(compiledSource, {
+    ...jsxRuntime,
+    baseUrl: import.meta.url,
+  });
+  const Content = mdxModule.default as ComponentType<{
+    components?: typeof mdxComponents;
+  }>;
+
+  return {
+    content: createElement(Content, { components: mdxComponents }),
+    frontmatter: {} as Record<string, unknown>,
+  };
+};
+
+/**
+ * Full MDX compilation + rendering. Used as fallback for local development
+ * (FsContentSource) and any content that wasn't pre-compiled at deploy time.
+ */
+export const renderMdx = async (source: string) => {
+  const { body, frontmatter } = stripFrontmatter(source);
+  const highlighter = await getHighlighter();
+  const shikiTransformer = rehypeShikiFromHighlighter(highlighter, {
+    defaultColor: false,
+    themes: {
+      dark: "github-dark",
+      light: "github-light",
+    },
+  });
+  const shikiPlugin = () => shikiTransformer;
+
+  const result = await compileMDX({
+    components: mdxComponents,
+    options: {
+      blockDangerousJS: false,
+      blockJS: false,
+      mdxOptions: {
+        rehypePlugins: [
+          rehypeSlug,
+          [
+            rehypeAutolinkHeadings,
+            {
+              behavior: "append",
+              properties: {
+                className: [
+                  "ml-2 text-[0.9em] opacity-0 transition-opacity hover:opacity-100",
+                ],
+              },
+            },
+          ],
+          shikiPlugin,
+        ],
+        remarkPlugins: [remarkGfm],
+      },
+    },
+    source: body,
+  });
+
+  return {
+    content: result.content,
+    frontmatter,
+  };
+};

package/docs/lib/navigation.ts

@@ -0,0 +1,288 @@
+import { normalizePath } from "@repo/common";
+import type { DocsNavigation } from "@repo/models";
+import type { PageMetadata } from "@repo/previewing";
+
+import type { OpenApiRegistry } from "./openapi";
+import { toDocHref } from "./routes";
+
+export interface NavPage {
+  type: "page";
+  title: string;
+  path: string;
+  source: "mdx" | "openapi";
+  identifier?: string;
+  sidebarTitle?: string;
+  icon?: string;
+  iconType?: string;
+  tag?: string;
+  hidden?: boolean;
+  deprecated?: boolean;
+  url?: string;
+  hideApiMarker?: boolean;
+}
+
+export interface NavGroup {
+  type: "group";
+  title: string;
+  items: NavPage[];
+  expanded?: boolean;
+  hidden?: boolean;
+}
+
+export type NavEntry = NavGroup | NavPage;
+
+export const getNavPageTitle = (page: NavPage): string =>
+  page.sidebarTitle ?? page.title;
+
+export const getNavPageHref = (page: NavPage, basePath: string): string =>
+  page.url ?? toDocHref(page.path, basePath);
+
+const titleFromSlug = (slug: string) => {
+  const clean = slug.replaceAll("-", " ").split("/").pop() ?? slug;
+  if (clean === "index") {
+    return "Overview";
+  }
+  return clean.replaceAll(/\b\w/g, (char) => char.toUpperCase());
+};
+
+const createPageItem = (
+  page: string,
+  registry: OpenApiRegistry,
+  slugPrefix: string
+): NavPage => {
+  const entry = registry.byIdentifier.get(page);
+  if (entry) {
+    return {
+      identifier: entry.identifier,
+      path: entry.slug,
+      source: "openapi",
+      title: entry.operation.summary ?? entry.identifier,
+      type: "page",
+    };
+  }
+
+  const normalized = normalizePath(page);
+  const path = slugPrefix
+    ? normalizePath(`${slugPrefix}/${normalized}`)
+    : normalized;
+
+  return {
+    path,
+    source: "mdx",
+    title: titleFromSlug(page),
+    type: "page",
+  };
+};
+
+// oxlint-disable-next-line eslint/complexity
+export const buildNavigation = (
+  navigation: DocsNavigation | undefined,
+  registry: OpenApiRegistry,
+  slugPrefix = ""
+) => {
+  const entries: NavEntry[] = [];
+  const groups = navigation?.groups ?? [];
+  const hiddenPages = new Set(navigation?.hidden);
+
+  for (const group of groups) {
+    const title = group.group ?? "Untitled";
+    const items: NavPage[] = [];
+    const groupHidden = group.hidden === true;
+
+    if (group.pages?.length) {
+      for (const page of group.pages) {
+        const item = createPageItem(page, registry, slugPrefix);
+        if (groupHidden || hiddenPages.has(page)) {
+          item.hidden = true;
+        }
+        items.push(item);
+      }
+    } else if (group.openapi) {
+      const sourceKey =
+        typeof group.openapi === "string"
+          ? `${group.openapi}::::`
+          : `${group.openapi.source}::${group.openapi.directory ?? ""}::${(
+              group.openapi.include ?? []
+            ).join("|")}`;
+      const sourceEntries = registry.bySource.get(sourceKey) ?? [];
+      for (const entry of sourceEntries) {
+        items.push({
+          hidden: groupHidden || undefined,
+          identifier: entry.identifier,
+          path: entry.slug,
+          source: "openapi",
+          title: entry.operation.summary ?? entry.identifier,
+          type: "page",
+        });
+      }
+    }
+
+    if (items.length) {
+      entries.push({
+        expanded: group.expanded,
+        hidden: groupHidden || undefined,
+        items,
+        title,
+        type: "group",
+      });
+    }
+  }
+
+  const topPages = navigation?.pages ?? [];
+  for (const page of topPages) {
+    const item = createPageItem(page, registry, slugPrefix);
+    if (hiddenPages.has(page)) {
+      item.hidden = true;
+    }
+    entries.push(item);
+  }
+
+  return entries;
+};
+
+const enrichPage = (
+  page: NavPage,
+  metadataMap: Map<string, PageMetadata>
+): NavPage => {
+  const meta = metadataMap.get(page.path);
+  if (!meta) {
+    return page;
+  }
+  return {
+    ...page,
+    deprecated: meta.deprecated ?? page.deprecated,
+    hidden: meta.hidden ?? page.hidden,
+    hideApiMarker: meta.hideApiMarker ?? page.hideApiMarker,
+    icon: meta.icon ?? page.icon,
+    iconType: meta.iconType ?? page.iconType,
+    sidebarTitle: meta.sidebarTitle ?? page.sidebarTitle,
+    tag: meta.tag ?? page.tag,
+    title: meta.title ?? page.title,
+    url: meta.url ?? page.url,
+  };
+};
+
+export const enrichNavWithMetadata = (
+  entries: NavEntry[],
+  metadataMap: Map<string, PageMetadata>
+): NavEntry[] =>
+  entries.map((entry) => {
+    if (entry.type === "page") {
+      return enrichPage(entry, metadataMap);
+    }
+    return {
+      ...entry,
+      items: entry.items.map((item) => enrichPage(item, metadataMap)),
+    };
+  });
+
+export const getVisibleNavigation = (entries: NavEntry[]): NavEntry[] => {
+  const visible: NavEntry[] = [];
+  for (const entry of entries) {
+    if (entry.hidden) {
+      continue;
+    }
+    if (entry.type === "group") {
+      const visibleItems = entry.items.filter((item) => !item.hidden);
+      if (visibleItems.length) {
+        visible.push({ ...entry, items: visibleItems });
+      }
+    } else {
+      visible.push(entry);
+    }
+  }
+  return visible;
+};
+
+export const flattenNav = (entries: NavEntry[]): NavPage[] => {
+  const pages: NavPage[] = [];
+  for (const entry of entries) {
+    if (entry.type === "page") {
+      pages.push(entry);
+    } else {
+      pages.push(...entry.items);
+    }
+  }
+  return pages;
+};
+
+export interface NavTab {
+  label: string;
+  icon?: string;
+  href?: string;
+  entries: NavEntry[];
+  slugPrefix?: string;
+}
+
+export const buildTabbedNavigation = (
+  navigation: DocsNavigation | undefined,
+  registry: OpenApiRegistry,
+  slugPrefix = ""
+): NavTab[] | null => {
+  if (!navigation?.tabs?.length) {
+    return null;
+  }
+  const { tabs } = navigation;
+
+  return tabs.map((tab) => {
+    if (tab.href) {
+      return {
+        entries: [],
+        href: tab.href,
+        icon: tab.icon,
+        label: tab.label,
+      };
+    }
+
+    const tabNav: DocsNavigation = {
+      groups: tab.groups,
+      hidden: navigation.hidden,
+      pages: tab.pages,
+    };
+    const entries = buildNavigation(tabNav, registry, slugPrefix);
+    const [firstPage] = flattenNav(entries);
+
+    return {
+      entries,
+      icon: tab.icon,
+      label: tab.label,
+      slugPrefix: firstPage?.path,
+    };
+  });
+};
+
+export const findActiveTabIndex = (
+  tabs: NavTab[],
+  currentPath: string
+): number => {
+  const normalized = normalizePath(currentPath);
+  for (const [index, tab] of tabs.entries()) {
+    if (tab.href) {
+      continue;
+    }
+    const pages = flattenNav(tab.entries);
+    if (pages.some((page) => page.path === normalized)) {
+      return index;
+    }
+  }
+  return 0;
+};
+
+export const findBreadcrumbs = (entries: NavEntry[], path: string) => {
+  const normalized = normalizePath(path);
+  for (const entry of entries) {
+    if (entry.type === "page" && entry.path === normalized) {
+      return [{ label: getNavPageTitle(entry), path: entry.path }];
+    }
+    if (entry.type === "group") {
+      const found = entry.items.find((item) => item.path === normalized);
+      if (found) {
+        return [
+          { label: entry.title, path: "" },
+          { label: getNavPageTitle(found), path: found.path },
+        ];
+      }
+    }
+  }
+  return [] as { label: string; path: string }[];
+};