<Callout type="warning" title="Be careful">
...
</Callout>

export type ThemePackage = {
  metadata: ThemeMetadata;
  layouts: ThemeLayouts;
  components: ComponentRegistry;
  tokens: ThemeTokens;
  assets: ThemeAssets;
  renderers: ThemeRenderers;
};

export type ThemeMetadata = {
  name: string;
  version: string;
  compatibleWith: {
    docforge: string;
    componentContract: string;
  };
};

export type DocsLayoutProps = {
  page: PageManifestEntry;
  site: SiteConfig;
  navigation: RenderNavNode[];
  breadcrumbs: BreadcrumbItem[];
  previous?: PageManifestEntry;
  next?: PageManifestEntry;
  tableOfContents: TocItem[];
  children: React.ReactNode;
};

export type ThemeTokens = {
  color: {
    background: string;
    foreground: string;
    muted: string;
    border: string;
    accent: string;
    danger: string;
    warning: string;
    success: string;
    info: string;
    codeBackground: string;
  };
  typography: {
    fontSans: string;
    fontMono: string;
    baseSize: string;
    lineHeight: string;
  };
  spacing: {
    pageX: string;
    pageY: string;
    sectionGap: string;
  };
  radius: {
    sm: string;
    md: string;
    lg: string;
  };
};

{
  "theme": {
    "tokens": {
      "color": {
        "accent": "#6366f1"
      },
      "radius": {
        "md": "8px"
      }
    }
  }
}

:root {
  --df-color-background: #ffffff;
  --df-color-foreground: #111827;
  --df-color-accent: #6366f1;
  --df-font-sans: Inter, system-ui, sans-serif;
  --df-font-mono: ui-monospace, SFMono-Regular, monospace;
  --df-radius-md: 8px;
}

[data-theme="dark"] {
  --df-color-background: #0b0f19;
  --df-color-foreground: #f9fafb;
}

.df-callout {
  border: 1px solid var(--df-color-border);
  border-radius: var(--df-radius-md);
}

export type ComponentSpec = {
  name: string;
  version: string;
  props: Record<string, PropSpec>;
  children: ChildrenSpec;
  render: ComponentRenderer;
  toMarkdown: MarkdownExporter;
  extractSearchText: SearchTextExtractor;
  accessibility?: AccessibilitySpec;
  deprecated?: DeprecationInfo;
};

export type ComponentRegistry = {
  contractVersion: string;
  components: Map<string, ComponentSpec>;
  get(name: string): ComponentSpec | undefined;
  has(name: string): boolean;
};

export type PropSpec =
  | {
      type: "string";
      required?: boolean;
      maxLength?: number;
      pattern?: RegExp;
    }
  | {
      type: "number";
      required?: boolean;
      min?: number;
      max?: number;
      integer?: boolean;
    }
  | {
      type: "boolean";
      required?: boolean;
    }
  | {
      type: "enum";
      required?: boolean;
      values: string[];
    }
  | {
      type: "href";
      required?: boolean;
      allowExternal?: boolean;
    };

const CalloutProps = {
  type: {
    type: "enum",
    required: true,
    values: ["note", "tip", "warning", "danger", "info"],
  },
  title: {
    type: "string",
    required: false,
    maxLength: 80,
  },
} satisfies Record<string, PropSpec>;

export type ChildrenSpec =
  | { type: "none" }
  | { type: "inline" }
  | { type: "blocks" }
  | { type: "only"; components: string[] };

const TabsChildren: ChildrenSpec = {
  type: "only",
  components: ["Tab"],
};

const CardChildren: ChildrenSpec = {
  type: "blocks",
};

<Tabs>
  <Card title="Wrong" href="/x" />
</Tabs>

<Callout type="warning" title="Generated pages can overwrite managed regions">
Run `docforge generate --dry-run` before applying documentation updates.
</Callout>

export const CalloutSpec: ComponentSpec = {
  name: "Callout",
  version: "1.0.0",
  props: {
    type: {
      type: "enum",
      required: true,
      values: ["note", "tip", "warning", "danger", "info"],
    },
    title: {
      type: "string",
      required: false,
      maxLength: 100,
    },
  },
  children: { type: "blocks" },
  render: renderCallout,
  toMarkdown: calloutToMarkdown,
  extractSearchText: extractChildrenText,
};

> [!WARNING] Generated pages can overwrite managed regions
> Run `docforge generate --dry-run` before applying documentation updates.

Generated pages can overwrite managed regions
Run docforge generate --dry-run before applying documentation updates.

<Steps>
  <Step title="Initialize documentation">
    ```bash
    docforge init
    ```
  </Step>

  <Step title="Start preview">
    ```bash
    docforge dev
    ```
  </Step>
</Steps>

export const StepsSpec: ComponentSpec = {
  name: "Steps",
  version: "1.0.0",
  props: {},
  children: { type: "only", components: ["Step"] },
  render: renderSteps,
  toMarkdown: stepsToMarkdown,
  extractSearchText: extractChildrenText,
};

export const StepSpec: ComponentSpec = {
  name: "Step",
  version: "1.0.0",
  props: {
    title: { type: "string", required: true, maxLength: 120 },
  },
  children: { type: "blocks" },
  render: renderStep,
  toMarkdown: stepToMarkdown,
  extractSearchText: extractChildrenText,
};

1. **Initialize documentation**

   ```bash
   docforge init
   ```

2. **Start preview**

   ```bash
   docforge dev
   ```

<Tabs>
  <Tab title="npm">
    ```bash
    npm install -D docforge
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash
    pnpm add -D docforge
    ```
  </Tab>
</Tabs>

export const TabsSpec: ComponentSpec = {
  name: "Tabs",
  version: "1.0.0",
  props: {},
  children: { type: "only", components: ["Tab"] },
  render: renderTabs,
  toMarkdown: tabsToMarkdown,
  extractSearchText: extractChildrenText,
};

export const TabSpec: ComponentSpec = {
  name: "Tab",
  version: "1.0.0",
  props: {
    title: { type: "string", required: true, maxLength: 60 },
  },
  children: { type: "blocks" },
  render: renderTab,
  toMarkdown: tabToMarkdown,
  extractSearchText: extractChildrenText,
};

### npm

```bash
npm install -D docforge
```

### pnpm

```bash
pnpm add -D docforge
```

<CardGroup cols={2}>
  <Card title="Generate API reference" href="/guides/api-reference">
    Create endpoint documentation from an OpenAPI specification.
  </Card>

  <Card title="Configure navigation" href="/reference/navigation">
    Define manual and generated sidebar sections.
  </Card>
</CardGroup>

export const CardGroupSpec: ComponentSpec = {
  name: "CardGroup",
  version: "1.0.0",
  props: {
    cols: {
      type: "number",
      required: false,
      min: 1,
      max: 3,
      integer: true,
    },
  },
  children: { type: "only", components: ["Card"] },
  render: renderCardGroup,
  toMarkdown: cardGroupToMarkdown,
  extractSearchText: extractChildrenText,
};

export const CardSpec: ComponentSpec = {
  name: "Card",
  version: "1.0.0",
  props: {
    title: { type: "string", required: true, maxLength: 120 },
    href: { type: "href", required: true, allowExternal: false },
    icon: { type: "string", required: false, maxLength: 40 },
  },
  children: { type: "blocks" },
  render: renderCard,
  toMarkdown: cardToMarkdown,
  extractSearchText: extractChildrenText,
};

- [Generate API reference](/guides/api-reference): Create endpoint documentation from an OpenAPI specification.
- [Configure navigation](/reference/navigation): Define manual and generated sidebar sections.

<AccordionGroup>
  <Accordion title="Why does DocForge keep a local index?">
    The index avoids re-parsing unchanged files and supports diff-aware documentation updates.
  </Accordion>
</AccordionGroup>

export const AccordionGroupSpec: ComponentSpec = {
  name: "AccordionGroup",
  version: "1.0.0",
  props: {},
  children: { type: "only", components: ["Accordion"] },
  render: renderAccordionGroup,
  toMarkdown: accordionGroupToMarkdown,
  extractSearchText: extractChildrenText,
};

export const AccordionSpec: ComponentSpec = {
  name: "Accordion",
  version: "1.0.0",
  props: {
    title: { type: "string", required: true, maxLength: 120 },
  },
  children: { type: "blocks" },
  render: renderAccordion,
  toMarkdown: accordionToMarkdown,
  extractSearchText: extractChildrenText,
};

<CodeGroup>
  ```bash title="npm"
  npm install -D docforge
  ```

  ```bash title="pnpm"
  pnpm add -D docforge
  ```
</CodeGroup>

<ApiOperation operationId="createUser" />

export const ApiOperationSpec: ComponentSpec = {
  name: "ApiOperation",
  version: "1.0.0",
  props: {
    operationId: { type: "string", required: true, maxLength: 120 },
  },
  children: { type: "none" },
  render: renderApiOperation,
  toMarkdown: apiOperationToMarkdown,
  extractSearchText: apiOperationSearchText,
};

export type ComponentRenderContext = {
  page: PageManifestEntry;
  apiRegistry?: ApiRegistry;
  routeIndex: RouteIndex;
  basePath: string;
};

export function renderApiOperation(
  props: { operationId: string },
  ctx: ComponentRenderContext
): React.ReactNode {
  const operation = ctx.apiRegistry?.getOperation(props.operationId);

  if (!operation) {
    return <MissingApiOperation operationId={props.operationId} />;
  }

  return <ApiOperationView operation={operation} />;
}

ApiOperation
  EndpointBadge
  OperationSummary
  AuthRequirements
  ParameterTable
  RequestBodyViewer
  ResponseTable
  CodeSamples
  ErrorModel

<ApiOperation operationId="..." />

export type ThemeRenderContext = {
  site: SiteConfig;
  page: PageManifestEntry;
  routeIndex: RouteIndex;
  basePath: string;
  apiRegistry?: ApiRegistry;
  assetResolver: AssetResolver;
  searchConfig: SearchConfig;
};

const operation = globalApiRegistry.get(operationId);

renderApiOperation(props, context)

export type ComponentRenderer<Props = unknown> = (
  props: Props,
  children: React.ReactNode,
  context: ThemeRenderContext
) => React.ReactNode;

export type MarkdownExporter<Props = unknown> = (
  props: Props,
  children: MarkdownNode[],
  context: MarkdownExportContext
) => string;

export type SearchTextExtractor<Props = unknown> = (
  props: Props,
  children: SearchTextNode[],
  context: SearchExtractContext
) => string[];

import { Callout } from "@theme/components";

<Callout />

<Callout type="note" />

const mdxComponents = {
  Callout,
  Steps,
  Step,
  Tabs,
  Tab,
  CardGroup,
  Card,
  AccordionGroup,
  Accordion,
  ApiOperation,
};

export type ComponentContractVersion = "1.0";

export const themeMetadata = {
  name: "@docforge/theme-default",
  version: "1.4.0",
  compatibleWith: {
    docforge: "^1.0.0",
    componentContract: "1.0",
  },
};

componentContract: "1.0"

export const NoteSpec: ComponentSpec = {
  name: "Note",
  version: "0.9.0",
  props: {},
  children: { type: "blocks" },
  render: renderNote,
  toMarkdown: noteToMarkdown,
  extractSearchText: extractChildrenText,
  deprecated: {
    since: "1.0.0",
    replacement: "Callout",
    message: "Use <Callout type=\"note\"> instead.",
  },
};

warning mdx.component.deprecated docs/page.mdx:12:1
<Note> is deprecated. Use <Callout type="note"> instead.

{
  "theme": {
    "name": "default",
    "tokens": {
      "color": {
        "accent": "#2563eb"
      }
    },
    "logo": {
      "src": "/assets/logo.svg",
      "alt": "Acme"
    },
    "footer": {
      "text": "© 2026 Acme"
    }
  }
}

export const CustomChartSpec: ComponentSpec = {
  name: "CustomChart",
  version: "1.0.0",
  props: {
    id: { type: "string", required: true },
  },
  children: { type: "none" },
  render: renderCustomChart,
  toMarkdown: customChartToMarkdown,
  extractSearchText: customChartSearchText,
};

{
  "components": {
    "custom": ["./docs/components/custom-chart.ts"]
  }
}

export type ComponentReplacement = {
  name: string;
  render: ComponentRenderer;
};

export type ThemeConfig =
  | { type: "builtin"; name: "default" }
  | { type: "package"; packageName: string }
  | { type: "local"; path: string };

export async function loadTheme(config: ThemeConfig): Promise<ThemePackage> {
  if (config.type === "builtin") {
    return loadBuiltinTheme(config.name);
  }

  if (config.type === "package") {
    return loadThemePackage(config.packageName);
  }

  return loadLocalTheme(config.path);
}

export function validateThemeCompatibility(
  theme: ThemePackage,
  docforgeVersion: string
): Diagnostic[] {
  // Check component contract and package compatibility.
  return [];
}

export type ThemeAssets = {
  css: string[];
  js: string[];
  static: Array<{
    sourcePath: string;
    outputPath: string;
  }>;
};

assets/theme.css
assets/theme.js
assets/logo.svg

export type ColorScheme = "light" | "dark" | "system";

{
  "theme": {
    "colorScheme": "system"
  }
}

<html data-theme="light">

const preferred = localStorage.getItem("theme")
  ?? (matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");

document.documentElement.dataset.theme = preferred;

export type AccessibilitySpec = {
  requiresLabel?: boolean;
  keyboardInteractive?: boolean;
  semanticRole?: string;
};

```ts title="src/index.ts" {2-4}
export function main() {
  console.log("hello");
}
```

export type CodeBlockMeta = {
  title?: string;
  highlightLines?: number[];
  showLineNumbers?: boolean;
};

export type TocItem = {
  depth: number;
  title: string;
  href: string;
  children: TocItem[];
};

export type SearchProvider = {
  search(query: string): Promise<SearchResult[]>;
};

export type SearchResult = {
  title: string;
  route: string;
  excerpt: string;
  section?: string;
};

export type ApiPlaygroundProps = {
  operationId: string;
};

export type ApiPlaygroundContext = {
  operation: NormalizedApiOperation;
  environments: ApiEnvironment[];
  authSchemes: AuthScheme[];
  requestPolicy: RequestPolicy;
};

export type ThemeTrustMode =
  | "builtinOnly"
  | "trustedLocal"
  | "packageAllowed";

error theme.compatibility.unsupportedContract
Theme "@acme/doc-theme" supports component contract 0.9, but this project requires 1.0.

error theme.component.missingRequired
Theme does not provide required component: Callout.

warning theme.token.invalid
Invalid theme token color.accent: expected a valid CSS color.

error theme.asset.notFound
Theme asset does not exist: ./docs/logo.svg.

export const ThemeConfigSchema = z.object({
  name: z.string().default("default"),
  colorScheme: z.enum(["light", "dark", "system"]).default("system"),
  logo: z.object({
    src: z.string(),
    alt: z.string(),
  }).optional(),
  tokens: ThemeTokensSchema.optional(),
  footer: z.object({
    text: z.string().optional(),
    links: z.array(z.object({
      title: z.string(),
      href: z.string(),
    })).optional(),
  }).optional(),
});

export function DocsArticle({ compiledMdx, context }: Props) {
  const components = createMdxComponentMap(context.theme.components, context);

  return (
    <MDXProvider components={components}>
      <compiledMdx.Content />
    </MDXProvider>
  );
}

export function createMdxComponentMap(
  registry: ComponentRegistry,
  context: ThemeRenderContext
): Record<string, React.ComponentType<any>> {
  const map: Record<string, React.ComponentType<any>> = {};

  for (const spec of registry.components.values()) {
    map[spec.name] = function RegisteredComponent(props) {
      return spec.render(props, props.children, context);
    };
  }

  return map;
}

export function renderMdxAstToMarkdown(
  ast: unknown,
  registry: ComponentRegistry,
  context: MarkdownExportContext
): string {
  return walkAndRenderMarkdown(ast, {
    onComponent(node) {
      const name = getMdxElementName(node);
      const spec = registry.get(name);

      if (!spec?.toMarkdown) {
        return renderUnknownComponentFallback(node);
      }

      const props = getProps(node);
      const children = renderChildrenToMarkdownNodes(node);

      return spec.toMarkdown(props, children, context);
    },
  });
}

export function extractSearchTextFromMdxAst(
  ast: unknown,
  registry: ComponentRegistry,
  context: SearchExtractContext
): string[] {
  const chunks: string[] = [];

  walkAst(ast, {
    enter(node) {
      if (isTextNode(node)) {
        chunks.push(node.value);
      }

      if (isMdxJsxElement(node)) {
        const spec = registry.get(getMdxElementName(node));

        if (spec) {
          chunks.push(...spec.extractSearchText(getProps(node), getChildren(node), context));
        }
      }
    },
  }, createContext());

  return chunks;
}

# Callout

Use `Callout` to highlight notes, tips, warnings, and danger messages.

## Props

| Prop | Type | Required | Description |
|---|---|---|---|
| `type` | `note \| tip \| warning \| danger \| info` | yes | Visual and semantic callout type. |
| `title` | `string` | no | Optional title. |

{
  "allowedComponents": [
    {
      "name": "Callout",
      "props": {
        "type": ["note", "tip", "warning", "danger", "info"],
        "title": "optional string"
      },
      "children": "blocks"
    },
    {
      "name": "Steps",
      "children": "only Step"
    }
  ]
}

it("Callout supports render, markdown export, and search extraction", () => {
  const spec = registry.get("Callout")!;

  expect(spec.props.type).toBeDefined();
  expect(spec.toMarkdown).toBeDefined();
  expect(spec.extractSearchText).toBeDefined();
});

fixtures/component-export/callout.mdx
fixtures/component-export/callout.expected.md

export function validateThemePackage(theme: ThemePackage): Diagnostic[] {
  const diagnostics: Diagnostic[] = [];

  for (const required of REQUIRED_COMPONENTS) {
    if (!theme.components.has(required)) {
      diagnostics.push({
        code: "theme.component.missingRequired",
        severity: "error",
        category: "theme",
        message: `Theme is missing required component: ${required}.`,
      });
    }
  }

  diagnostics.push(...validateComponentSpecs(theme.components));
  diagnostics.push(...validateTokens(theme.tokens));
  diagnostics.push(...validateThemeAssets(theme.assets));

  return diagnostics;
}

packages/theme-contract/
  src/
    component-spec.ts
    prop-spec.ts
    registry.ts
    markdown-export.ts
    search-extract.ts
    diagnostics.ts

packages/theme-default/
  src/
    metadata.ts
    tokens.ts
    registry.ts
    layouts/
      DocsLayout.tsx
      NotFoundLayout.tsx
    components/
      Callout.tsx
      Steps.tsx
      Tabs.tsx
      Card.tsx
      Accordion.tsx
      ApiOperation.tsx
    styles/
      theme.css