jamdesk 1.0.0

package/vendored/lib/seo.ts

@@ -0,0 +1,264 @@
+/**
+ * SEO Metadata Builder
+ *
+ * Builds Next.js Metadata objects from docs.json config and page frontmatter.
+ * Supports 19+ meta tags with per-page overrides.
+ *
+ * Priority order: Page frontmatter > Global config > Auto-generated
+ */
+
+import type { Metadata } from 'next';
+import type { DocsConfig, Logo, LogoConfig, LanguageConfig, LanguageCode } from './docs-types';
+import { transformLanguagePath, extractLanguageFromPath, isValidLanguageCode } from './language-utils';
+
+/**
+ * Build the OG image URL for a page using the proxy's /api/og endpoint.
+ * Returns undefined if og:image is explicitly set in metatags.
+ */
+function buildOgImageUrl(
+  baseUrl: string,
+  title: string,
+  siteName: string,
+  options?: {
+    description?: string;
+    section?: string;
+    logo?: Logo;
+    theme?: 'light' | 'dark';
+  }
+): string {
+  const params = new URLSearchParams();
+  params.set('title', title);
+  params.set('siteName', siteName);
+
+  if (options?.description) {
+    params.set('description', options.description);
+  }
+  if (options?.section) {
+    params.set('section', options.section);
+  }
+  if (options?.theme) {
+    params.set('theme', options.theme);
+  }
+
+  // Get root URL (strip /docs path if present, since API endpoints are at domain root)
+  const rootUrl = baseUrl.replace(/\/docs$/, '');
+
+  // Handle logo - prefer dark variant for OG images (dark background)
+  if (options?.logo) {
+    let logoPath: string;
+    if (typeof options.logo === 'string') {
+      logoPath = options.logo;
+    } else {
+      logoPath = (options.logo as LogoConfig).dark || (options.logo as LogoConfig).light;
+    }
+    // Make logo URL absolute (use root URL since assets are at domain root)
+    if (logoPath && !logoPath.startsWith('http')) {
+      logoPath = `${rootUrl}${logoPath.startsWith('/') ? '' : '/'}${logoPath}`;
+    }
+    if (logoPath) {
+      params.set('logo', logoPath);
+    }
+  }
+
+  return `${rootUrl}/api/og?${params.toString()}`;
+}
+
+export interface PageFrontmatter {
+  title?: string;
+  description?: string;
+  noindex?: boolean;
+  hidden?: boolean;
+  /** Section/group name for OG image (optional) */
+  section?: string;
+  seo?: {
+    noindex?: boolean;
+    canonical?: string;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Build hreflang alternate links for multi-language pages.
+ * Generates links for each language version of the page, plus x-default.
+ *
+ * @param baseUrl - The base URL (e.g., "https://docs.example.com")
+ * @param pagePath - The current page path (e.g., "es/getting-started")
+ * @param languages - Array of language configurations from docs.json
+ * @returns Record of language code to URL for alternates.languages
+ */
+function buildHreflangAlternates(
+  baseUrl: string,
+  pagePath: string,
+  languages: LanguageConfig[]
+): Record<string, string> | undefined {
+  // Only generate hreflang if there are multiple languages
+  if (!languages || languages.length <= 1) {
+    return undefined;
+  }
+
+  // Find the default language
+  const defaultLang = languages.find((l) => l.default)?.language || languages[0]?.language || 'en';
+
+  // Detect current language from path
+  const currentLang = extractLanguageFromPath(pagePath) || defaultLang;
+
+  // Build alternates for each language
+  const alternates: Record<string, string> = {};
+
+  for (const langConfig of languages) {
+    const lang = langConfig.language;
+    // Transform current path to this language's version
+    // transformLanguagePath returns paths relative to app root (e.g., '/es/intro' or '/intro')
+    const langPath = transformLanguagePath(pagePath, currentLang, lang, defaultLang);
+    const cleanPath = langPath.replace(/^\//, ''); // Remove leading slash for URL building
+    alternates[lang] = cleanPath ? `${baseUrl}/${cleanPath}` : baseUrl;
+  }
+
+  // Add x-default pointing to the default language version
+  const defaultPath = transformLanguagePath(pagePath, currentLang, defaultLang, defaultLang);
+  const cleanDefaultPath = defaultPath.replace(/^\//, '');
+  alternates['x-default'] = cleanDefaultPath ? `${baseUrl}/${cleanDefaultPath}` : baseUrl;
+
+  return alternates;
+}
+
+/**
+ * Build SEO metadata for a documentation page.
+ *
+ * @param config - The docs.json configuration
+ * @param frontmatter - Page frontmatter data
+ * @param pagePath - The page path (e.g., "getting-started/installation")
+ * @param baseUrl - The base URL (e.g., "https://docs.example.com")
+ * @param languages - Optional array of language configurations for hreflang tags
+ * @returns Partial<Metadata> to spread into generateMetadata return
+ */
+export function buildSeoMetadata(
+  config: DocsConfig,
+  frontmatter: PageFrontmatter,
+  pagePath: string,
+  baseUrl: string,
+  languages?: LanguageConfig[]
+): Partial<Metadata> {
+  const globalMeta = config.seo?.metatags || {};
+  const pageMeta = (frontmatter.seo as Record<string, string>) || {};
+  // Merge: page overrides global
+  const metatags: Record<string, string> = { ...globalMeta, ...pageMeta };
+  const metadata: Partial<Metadata> = {};
+
+  // 1. Generator - always add
+  metadata.generator = 'Jamdesk';
+
+  // 2. Robots (priority: page > global)
+  // Page noindex can be set via frontmatter.noindex or frontmatter.seo.noindex
+  const pageNoindex = frontmatter.noindex ?? frontmatter.seo?.noindex;
+  if (pageNoindex === true) {
+    // noindex does NOT imply nofollow - use follow: true
+    metadata.robots = { index: false, follow: true };
+  } else if (pageNoindex !== false && metatags.robots) {
+    // Page didn't explicitly set noindex: false, so use global robots
+    metadata.robots = metatags.robots;
+  }
+  // If pageNoindex === false, it overrides any global noindex (no robots meta = index)
+
+  // 3. Googlebot (separate from robots)
+  if (metatags.googlebot) {
+    // Merge googlebot with existing robots config
+    const existingRobots = typeof metadata.robots === 'object' ? metadata.robots : {};
+    metadata.robots = {
+      ...existingRobots,
+      googleBot: metatags.googlebot,
+    };
+  }
+
+  // 4. Google site verification
+  if (metatags['google-site-verification']) {
+    metadata.verification = { google: metatags['google-site-verification'] };
+  }
+
+  // 5. Keywords
+  if (metatags.keywords) {
+    metadata.keywords = metatags.keywords.split(',').map((k) => k.trim());
+  }
+
+  // 6. Description (global fallback only - page description handled separately)
+  if (!frontmatter.description && metatags.description) {
+    metadata.description = metatags.description;
+  }
+
+  // 7. Canonical (auto-generate if not specified)
+  const cleanPath = pagePath.replace(/^\/+|\/+$/g, ''); // Remove leading/trailing slashes
+  const pageUrl = cleanPath ? `${baseUrl}/${cleanPath}` : baseUrl;
+  const canonical = pageMeta.canonical || metatags.canonical || pageUrl;
+
+  // 7b. Hreflang alternates for multi-language support
+  const hreflangLanguages = buildHreflangAlternates(baseUrl, pagePath, languages || []);
+
+  metadata.alternates = {
+    canonical,
+    ...(hreflangLanguages && { languages: hreflangLanguages }),
+  };
+
+  // 8. Open Graph
+  const hasOgTags = Object.keys(metatags).some((k) => k.startsWith('og:'));
+  if (hasOgTags || frontmatter.title) {
+    // Auto-generate OG image URL if not explicitly set
+    const ogImageUrl = metatags['og:image'] || buildOgImageUrl(
+      baseUrl,
+      frontmatter.title || 'Documentation',
+      config.name,
+      {
+        description: frontmatter.description,
+        section: frontmatter.section,
+        logo: config.logo,
+        theme: 'dark', // Dark theme looks better for OG images
+      }
+    );
+
+    metadata.openGraph = {
+      title: metatags['og:title'] || frontmatter.title,
+      description: metatags['og:description'] || frontmatter.description,
+      url: metatags['og:url'] || pageUrl,
+      siteName: metatags['og:site_name'] || config.name,
+      type: (metatags['og:type'] as 'website' | 'article') || 'website',
+      images: [ogImageUrl],
+    };
+  }
+
+  // 9. Twitter Cards
+  // Auto-generate Twitter card with OG image
+  const twitterImageUrl = metatags['twitter:image'] || (metadata.openGraph as { images?: string[] })?.images?.[0];
+  metadata.twitter = {
+    card: (metatags['twitter:card'] as 'summary' | 'summary_large_image') || 'summary_large_image',
+    site: metatags['twitter:site'],
+    title: metatags['twitter:title'] || frontmatter.title,
+    description: metatags['twitter:description'] || frontmatter.description,
+    ...(twitterImageUrl && { images: [twitterImageUrl] }),
+  };
+
+  // 10. Theme color
+  if (metatags['theme-color']) {
+    metadata.themeColor = metatags['theme-color'];
+  }
+
+  // 11. Authors
+  if (metatags.author) {
+    metadata.authors = [{ name: metatags.author }];
+  }
+
+  // 12. Other tags (google, copyright, etc.)
+  const other: Record<string, string> = {};
+  if (metatags.google) other.google = metatags.google;
+  if (metatags.copyright) other.copyright = metatags.copyright;
+
+  // 13. Build metadata - commit SHA helps identify which version created this page
+  // Note: We use commit SHA (not unique build ID) to ensure identical content = identical HTML
+  if (process.env.BUILD_ID) {
+    other['jamdesk:build-id'] = process.env.BUILD_ID;
+  }
+
+  if (Object.keys(other).length > 0) {
+    metadata.other = other;
+  }
+
+  return metadata;
+}

package/vendored/lib/shiki-client.ts

@@ -0,0 +1,131 @@
+/**
+ * Client-side Shiki syntax highlighting utility
+ * Used for dynamic code highlighting (e.g., OpenAPI code examples)
+ */
+'use client';
+
+import type { Highlighter, BundledLanguage, BundledTheme } from 'shiki';
+
+let highlighter: Highlighter | null = null;
+
+// Languages needed for API code examples
+const CLIENT_LANGUAGES: BundledLanguage[] = [
+  'javascript',
+  'typescript',
+  'python',
+  'bash',
+  'json',
+  'shell',
+];
+
+// Dual themes for light/dark mode support
+const THEMES = {
+  light: 'github-light-default' as BundledTheme,
+  dark: 'github-dark-default' as BundledTheme,
+};
+
+/**
+ * Get or initialize the Shiki highlighter for client-side use
+ */
+async function getHighlighter(): Promise<Highlighter> {
+  if (!highlighter) {
+    const { createHighlighter } = await import('shiki');
+
+    highlighter = await createHighlighter({
+      themes: [THEMES.dark, THEMES.light],
+      langs: CLIENT_LANGUAGES,
+    });
+  }
+  return highlighter;
+}
+
+/**
+ * Escape HTML entities for fallback rendering
+ */
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Highlight code synchronously if highlighter is ready, otherwise return escaped code
+ * This is useful for initial render - the component can re-render when highlighting is done
+ */
+export function highlightCodeSync(code: string, language: string): string {
+  if (!highlighter) {
+    // Return escaped code if highlighter not ready yet
+    return escapeHtml(code);
+  }
+
+  try {
+    const lang = normalizeLanguage(language);
+    return highlighter.codeToHtml(code, {
+      lang,
+      themes: THEMES,
+      defaultColor: 'dark',
+    });
+  } catch {
+    return escapeHtml(code);
+  }
+}
+
+/**
+ * Highlight code asynchronously
+ * Returns full HTML with pre.shiki element for proper theme background support
+ */
+export async function highlightCode(
+  code: string,
+  language: string
+): Promise<string> {
+  try {
+    const shiki = await getHighlighter();
+    const lang = normalizeLanguage(language);
+
+    // Return full HTML - the pre.shiki element contains background styles
+    // that switch via CSS variables in light mode
+    return shiki.codeToHtml(code, {
+      lang,
+      themes: THEMES,
+      defaultColor: 'dark',
+    });
+  } catch {
+    return escapeHtml(code);
+  }
+}
+
+/**
+ * Preload the highlighter (call early to reduce latency)
+ */
+export async function preloadHighlighter(): Promise<void> {
+  await getHighlighter();
+}
+
+/**
+ * Normalize language aliases
+ */
+function normalizeLanguage(lang: string): BundledLanguage {
+  const normalized = lang.toLowerCase().trim();
+
+  const aliases: Record<string, BundledLanguage> = {
+    js: 'javascript',
+    ts: 'typescript',
+    sh: 'bash',
+    curl: 'bash',
+    py: 'python',
+  };
+
+  if (normalized in aliases) {
+    return aliases[normalized];
+  }
+
+  if (CLIENT_LANGUAGES.includes(normalized as BundledLanguage)) {
+    return normalized as BundledLanguage;
+  }
+
+  // Default to text-like rendering
+  return 'bash';
+}

package/vendored/lib/shiki-config.ts

@@ -0,0 +1,289 @@
+/**
+ * Shiki syntax highlighting configuration
+ * Reads theme settings from docs.json and provides rehype plugin options
+ */
+
+import type { RehypeShikiOptions } from '@shikijs/rehype';
+import rehypeShikiFromHighlighter, { type RehypeShikiCoreOptions } from '@shikijs/rehype/core';
+import type { BuiltinLanguage, Highlighter, ThemeRegistration } from 'shiki';
+import type { Pluggable } from 'unified';
+import type { DocsConfig, StylingConfig } from './docs-types';
+import { transformerLineFeatures } from './shiki-transformers';
+import { JAMDESK_CSS_THEME } from './shiki-css-theme';
+
+/**
+ * Preloaded languages for faster static generation.
+ * These are loaded upfront when the highlighter initializes,
+ * avoiding I/O during page rendering.
+ *
+ * ## What happens if a language is NOT in this list?
+ * - The code block renders WITHOUT syntax highlighting (plain monospace text)
+ * - A warning is logged during build: "[shiki] Unknown language: <lang>"
+ * - The build continues successfully (no errors)
+ *
+ * ## How to add a new language:
+ * 1. Find the language ID from Shiki's bundled languages:
+ *    https://shiki.style/languages
+ * 2. Add it to this array (must match the exact Shiki language ID)
+ * 3. Deploy to Cloud Run and rebuild affected projects
+ *
+ * Each language adds ~100-500KB to highlighter init time.
+ * Keep this list focused on commonly-used documentation languages.
+ */
+export const PRELOADED_LANGUAGES: BuiltinLanguage[] = [
+  // Web fundamentals
+  'javascript',
+  'typescript',
+  'js',             // Alias for javascript
+  'ts',             // Alias for typescript
+  'jsx',
+  'tsx',
+  'html',
+  'css',
+  'json',
+  'yaml',
+  // Shell/scripting
+  'bash',
+  'shell',        // Alias for shellscript, commonly used in markdown
+  'shellscript',
+  'powershell',
+  // Backend languages
+  'python',
+  'ruby',
+  'go',
+  'rust',
+  'java',
+  'kotlin',
+  'swift',
+  'php',
+  'csharp',
+  'c',
+  'cpp',
+  'clojure',
+  // Data/query
+  'sql',
+  'graphql',
+  // Config/markup
+  'xml',
+  'toml',
+  'markdown',
+  'md',        // Alias for markdown - some docs use ```md instead of ```markdown
+  'mdx',
+  // DevOps
+  'dockerfile',
+  // Utility
+  'diff',
+  'log',          // Log files
+  'http',         // HTTP requests (GET https://api.example.com)
+  // Note: 'text' and 'plaintext' are NOT valid Shiki languages.
+  // Code blocks with these will render without highlighting (which is correct).
+];
+
+// Set for O(1) language lookups in the unknown language warning transformer
+const PRELOADED_LANGUAGES_SET = new Set<string>(PRELOADED_LANGUAGES);
+
+/**
+ * Languages that intentionally don't have syntax highlighting.
+ * Adding them here prevents the "Unknown language" warning during build.
+ *
+ * Note: 'mermaid' is included because it's rendered client-side by the Mermaid
+ * component. The data-language attribute is still set by Shiki's transformer,
+ * which MDXComponents.tsx uses to route to the Mermaid component.
+ */
+const NO_HIGHLIGHT_LANGS = new Set(['text', 'plaintext', 'plain', 'txt', 'raw', 'mermaid']);
+
+// Curated list of supported themes (reduces bundle size vs bundling all ~50)
+export const SUPPORTED_THEMES = [
+  // GitHub family (default themes - matching marketing)
+  'github-dark',
+  'github-light',
+  'github-dark-default',
+  'github-light-default',
+  // Popular dark themes
+  'tokyo-night',
+  'one-dark-pro',
+  'dracula',
+  'nord',
+  'vitesse-dark',
+  // Popular light themes
+  'vitesse-light',
+  'min-light',
+  // Catppuccin variants
+  'catppuccin-mocha',
+  'catppuccin-latte',
+  // Custom CSS styling
+  'css-variables',
+] as const;
+
+export type SupportedTheme = (typeof SUPPORTED_THEMES)[number];
+
+// Default themes - github-dark-default has the darker #0d1117 background
+const DEFAULT_DARK_THEME: SupportedTheme = 'github-dark-default';
+const DEFAULT_LIGHT_THEME: SupportedTheme = 'github-light-default';
+
+// Type for theme values (can be string or ThemeRegistration for css-variables)
+type ThemeValue = SupportedTheme | ThemeRegistration;
+
+/**
+ * Parse codeblocks config from docs.json styling section
+ */
+function parseCodeblocksConfig(styling?: StylingConfig): {
+  darkTheme: ThemeValue;
+  lightTheme: ThemeValue;
+} {
+  const codeblocks = styling?.codeblocks;
+
+  // Default: use github themes
+  if (!codeblocks || codeblocks === 'system') {
+    return { darkTheme: DEFAULT_DARK_THEME, lightTheme: DEFAULT_LIGHT_THEME };
+  }
+
+  // 'dark' mode only
+  if (codeblocks === 'dark') {
+    return { darkTheme: DEFAULT_DARK_THEME, lightTheme: DEFAULT_DARK_THEME };
+  }
+
+  // Object config with theme property
+  const themeConfig = codeblocks.theme;
+
+  if (!themeConfig) {
+    return { darkTheme: DEFAULT_DARK_THEME, lightTheme: DEFAULT_LIGHT_THEME };
+  }
+
+  // Single theme string - use for both
+  if (typeof themeConfig === 'string') {
+    const theme = validateTheme(themeConfig);
+    return { darkTheme: theme, lightTheme: theme };
+  }
+
+  // Light/dark theme pair
+  return {
+    darkTheme: validateTheme(themeConfig.dark),
+    lightTheme: validateTheme(themeConfig.light),
+  };
+}
+
+/**
+ * Validate a theme name against supported themes
+ * Returns ThemeRegistration object for css-variables, string for built-in themes
+ */
+function validateTheme(theme: string | undefined): ThemeValue {
+  if (!theme) return DEFAULT_DARK_THEME;
+
+  // Special handling for css-variables theme
+  if (theme === 'css-variables') {
+    return JAMDESK_CSS_THEME;
+  }
+
+  if (SUPPORTED_THEMES.includes(theme as SupportedTheme)) {
+    return theme as SupportedTheme;
+  }
+
+  console.warn(
+    `[shiki-config] Unsupported theme "${theme}", falling back to "${DEFAULT_DARK_THEME}". ` +
+      `Supported themes: ${SUPPORTED_THEMES.join(', ')}`
+  );
+  return DEFAULT_DARK_THEME;
+}
+
+/**
+ * Get Shiki rehype plugin options based on docs.json config
+ */
+export function getShikiOptions(config?: DocsConfig): Partial<RehypeShikiOptions> {
+  const { darkTheme, lightTheme } = parseCodeblocksConfig(config?.styling);
+
+  // Use dual themes for light/dark mode support
+  // The 'themes' option enables CSS variable-based theme switching
+  return {
+    themes: {
+      light: lightTheme,
+      dark: darkTheme,
+    },
+    // Preload common languages for faster static generation
+    // Unknown languages fall back to plaintext (no highlighting)
+    langs: PRELOADED_LANGUAGES,
+    // Default color mode (used when no preference is specified)
+    defaultColor: 'dark',
+    // Safety: skip highlighting lines >1000 chars to prevent OOM on minified code
+    // Lines exceeding this limit render without syntax highlighting
+    tokenizeMaxLineLength: 1000,
+    // Add transformers for language/meta attributes and line features
+    // Performance note: Order matters - cheaper transformers first, lazy notation last
+    transformers: [
+      {
+        name: 'log-unknown-languages',
+        preprocess(code: string, options: { lang?: string }) {
+          // Log warning for unknown languages so we know to add them
+          const lang = options.lang;
+          // Skip warning for intentionally unhighlighted languages
+          if (
+            lang &&
+            !PRELOADED_LANGUAGES_SET.has(lang) &&  // O(1) Set lookup instead of O(n) array
+            !NO_HIGHLIGHT_LANGS.has(lang)          // O(1) Set lookup
+          ) {
+            console.warn(
+              `[shiki] Unknown language: "${lang}" - code block will render without highlighting. ` +
+                `To add support, add "${lang}" to PRELOADED_LANGUAGES in lib/shiki-config.ts`
+            );
+          }
+          return code;
+        },
+      },
+      {
+        name: 'add-data-attributes',
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        pre(this: any, node: any) {
+          // Add data-language attribute to pre element for tab label extraction
+          if (this.options.lang) {
+            node.properties['data-language'] = this.options.lang;
+          }
+          // Add data-meta attribute to pre element
+          // This preserves the raw meta string from code fences (e.g., "Header" from ```json Header)
+          // A post-Shiki rehype plugin (rehypeRestoreDataTitle) converts this to data-title
+          if (this.options.meta?.__raw) {
+            node.properties['data-meta'] = this.options.meta.__raw;
+          }
+        },
+      },
+      // Add line highlighting ({1,3-5} syntax) and line numbers support
+      // Note: This handles all meta string parsing with caching for performance
+      transformerLineFeatures(),
+      // NOTE: Notation transformers ([!code highlight], [!code focus], [!code ++/--])
+      // were removed for performance. Use {1,3-5} meta syntax for line highlighting.
+      // If notation support is needed, add createLazyNotationTransformer() here.
+    ],
+  };
+}
+
+/**
+ * Create a rehype plugin that uses a pre-existing Shiki highlighter.
+ * This is more efficient than the default rehypeShiki plugin which
+ * creates a new highlighter for each page render.
+ *
+ * @param highlighter - Pre-created highlighter from getHighlighter()
+ * @param config - Docs configuration for theme selection
+ * @returns A rehype plugin that can be used in MDXRemote options
+ */
+export function createShikiRehypePlugin(
+  highlighter: Highlighter,
+  config?: DocsConfig
+): Pluggable {
+  const options = getShikiOptions(config) as RehypeShikiCoreOptions;
+  // Return a plugin function that creates the transformer
+  // This matches unified's expected plugin signature
+  return () => rehypeShikiFromHighlighter(highlighter, options);
+}
+
+/**
+ * Get themes array for preloading (excludes css-variables which is a ThemeRegistration)
+ */
+export function getThemesToLoad(config?: DocsConfig): SupportedTheme[] {
+  const { darkTheme, lightTheme } = parseCodeblocksConfig(config?.styling);
+  const themes = new Set<SupportedTheme>();
+
+  // Only add string themes (not ThemeRegistration objects like css-variables)
+  if (typeof darkTheme === 'string') themes.add(darkTheme);
+  if (typeof lightTheme === 'string') themes.add(lightTheme);
+
+  return Array.from(themes);
+}