@mintlify/astro 0.1.1

package/README.md

@@ -0,0 +1,49 @@
+# @mintlify/astro
+
+Mintlify integration for Astro. This package syncs Mintlify-style docs content into Astro content collections and provides MDX components for rendering docs pages.
+
+## Install
+
+```bash
+npm install @mintlify/components
+```
+
+## Usage
+
+### 1) Configure Astro integration
+
+```ts
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import mdx from '@astrojs/mdx';
+import { mintlify } from '@mintlify/astro';
+
+export default defineConfig({
+  integrations: [mintlify({ docsDir: './docs' }), react(), mdx()],
+});
+```
+
+### 2) Use MDX components in docs page
+
+```astro
+---
+import { render } from 'astro:content';
+import { components } from '@mintlify/astro/components';
+---
+<Content components={components} />
+```
+
+## Expected docs structure
+
+- `./docs/docs.json`
+- `./docs/**/*.mdx`
+- `./docs/snippets/*` (optional)
+- assets like `./docs/images`, `./docs/logo`, `./docs/favicon.*` (optional)
+
+At build setup time, the integration generates:
+
+- `src/content/docs/**/*`
+- `src/content/components/**/*`
+- `src/content/generated/favicons.json` (when favicon is configured)
+

package/dist/components.d.ts

@@ -0,0 +1 @@
+export { components, useMDXComponents } from './utils/mintlify-components.js';

package/dist/components.js

@@ -0,0 +1 @@
+export { components, useMDXComponents } from './utils/mintlify-components.js';

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { AstroIntegration } from 'astro';
+export type { DocsConfig, NavigationConfig, Favicons } from './types.js';
+export interface MintlifyOptions {
+    docsDir?: string;
+}
+export declare function mintlify(options?: MintlifyOptions): AstroIntegration;

package/dist/index.js

@@ -0,0 +1,70 @@
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getAllPathsInDocsNav } from '@mintlify/common';
+import { clearContentDirectory } from './utils/clear-content-directory.js';
+import { copyAssets } from './utils/copy-assets.js';
+import { findUserComponents } from './utils/find-user-components.js';
+import { loadAllSnippets } from './utils/load-all-snippets.js';
+import { initLogger } from './utils/logger.js';
+import { readDocsConfig } from './utils/read-docs-config.js';
+import { readPageContent } from './utils/read-page-content.js';
+import { writePageContent } from './utils/write-page-content.js';
+import { writeFaviconsManifest } from './utils/write-favicons-manifest.js';
+export function mintlify(options) {
+    return {
+        name: '@mintlify/astro',
+        hooks: {
+            'astro:config:setup': async ({ config: astroConfig, logger }) => {
+                initLogger(logger);
+                const rootDir = fileURLToPath(astroConfig.root);
+                const srcDir = fileURLToPath(astroConfig.srcDir);
+                const publicDir = fileURLToPath(astroConfig.publicDir);
+                const contentDir = join(srcDir, 'content', 'docs');
+                const componentsDir = join(srcDir, 'content', 'components');
+                const docsDir = resolve(rootDir, options?.docsDir ?? './docs');
+                await Promise.all([
+                    clearContentDirectory(contentDir),
+                    clearContentDirectory(componentsDir),
+                ]);
+                await copyAssets(docsDir, publicDir);
+                const snippets = await loadAllSnippets(docsDir);
+                logger.info(`Loaded ${snippets.length} snippet files`);
+                const userComponents = await findUserComponents(docsDir);
+                const docsConfig = await readDocsConfig(docsDir);
+                const pagePaths = getAllPathsInDocsNav(docsConfig.navigation);
+                if (docsConfig.favicon) {
+                    const faviconHref = typeof docsConfig.favicon === 'string'
+                        ? docsConfig.favicon
+                        : docsConfig.favicon.light;
+                    await writeFaviconsManifest(srcDir, {
+                        icons: [
+                            {
+                                rel: 'icon',
+                                type: 'image/svg+xml',
+                                href: faviconHref,
+                            },
+                        ],
+                    });
+                }
+                logger.info(`Found ${pagePaths.length} pages to sync`);
+                await Promise.all(pagePaths.map(async (pagePath) => {
+                    try {
+                        const { content, slug } = await readPageContent(pagePath, docsDir);
+                        await writePageContent({
+                            content,
+                            slug,
+                            contentDir,
+                            componentsDir,
+                            userComponents,
+                            snippets,
+                        });
+                    }
+                    catch (error) {
+                        logger.warn(`Failed to read content for ${pagePath}: ${error}`);
+                    }
+                }));
+                logger.info(`Synced ${pagePaths.length} pages`);
+            },
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,12 @@
+export type { DocsConfig, NavigationConfig } from '@mintlify/validation';
+export interface FaviconIcon {
+    rel: string;
+    sizes?: string;
+    type: string;
+    href: string;
+    media?: string;
+}
+export interface Favicons {
+    icons: FaviconIcon[];
+    browserconfig?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/clear-content-directory.d.ts

@@ -0,0 +1 @@
+export declare function clearContentDirectory(dirPath: string): Promise<void>;

package/dist/utils/clear-content-directory.js

@@ -0,0 +1,8 @@
+import { mkdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+export async function clearContentDirectory(dirPath) {
+    if (existsSync(dirPath)) {
+        await rm(dirPath, { recursive: true });
+    }
+    await mkdir(dirPath, { recursive: true });
+}

package/dist/utils/copy-assets.d.ts

@@ -0,0 +1 @@
+export declare function copyAssets(docsDir: string, publicDir: string): Promise<void>;

package/dist/utils/copy-assets.js

@@ -0,0 +1,36 @@
+import { cp, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function isDirectory(path) {
+    try {
+        const stats = await stat(path);
+        return stats.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function copyDirectoryIfExists(source, dest) {
+    if (!(await isDirectory(source)))
+        return;
+    await cp(source, dest, { recursive: true });
+}
+async function copyFileIfExists(source, dest) {
+    if (!(await exists(source)))
+        return;
+    await cp(source, dest);
+}
+export async function copyAssets(docsDir, publicDir) {
+    await copyDirectoryIfExists(join(docsDir, 'images'), join(publicDir, 'images'));
+    await copyDirectoryIfExists(join(docsDir, 'logo'), join(publicDir, 'logo'));
+    await copyFileIfExists(join(docsDir, 'favicon.svg'), join(publicDir, 'favicon.svg'));
+    await copyFileIfExists(join(docsDir, 'favicon.ico'), join(publicDir, 'favicon.ico'));
+}

package/dist/utils/extract-react-components.d.ts

@@ -0,0 +1 @@
+export declare function extractReactComponents(mdxContent: string, mdxFilePath: string, componentsDir: string, pageSlug: string, userComponents: Set<string>): Promise<string>;

package/dist/utils/extract-react-components.js

@@ -0,0 +1,219 @@
+import { compile } from '@mdx-js/mdx';
+import { visit, SKIP } from 'unist-util-visit';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, dirname, relative, posix, sep } from 'node:path';
+import { getAST, stringifyTree, findExportedNodes, getExportMapFromTree, isMdxJsxAttribute, createMdxJsxAttribute, allowedComponents, } from '@mintlify/common';
+import { getLogger } from './logger.js';
+const COMPOUND_COMPONENTS = new Set([
+    'Accordion',
+    'AccordionGroup',
+    'Card',
+    'CardGroup',
+    'CodeGroup',
+    'Expandable',
+    'Steps',
+    'Tabs',
+    'Tooltip',
+]);
+const SUPPORTED_HOOKS = new Set([
+    'useState',
+    'useEffect',
+    'useRef',
+    'useCallback',
+    'useMemo',
+    'useReducer',
+    'useContext',
+    'useLayoutEffect',
+    'useImperativeHandle',
+    'useDebugValue',
+    'useDeferredValue',
+    'useTransition',
+    'useId',
+    'useSyncExternalStore',
+    'useInsertionEffect',
+]);
+const MDX_COMPONENTS_PATH = '@mintlify/astro/components';
+function isJsxNode(node) {
+    const n = node;
+    return n?.type === 'mdxJsxFlowElement' || n?.type === 'mdxJsxTextElement';
+}
+function visitJsxNodes(tree, visitor) {
+    visit(tree, (node, index, parent) => {
+        if (isJsxNode(node)) {
+            return visitor(node, index, parent);
+        }
+    });
+}
+const detectHooksInCode = (code) => [...SUPPORTED_HOOKS].filter((hook) => code.includes(hook));
+function createImportNode(name, path) {
+    return {
+        type: 'mdxjsEsm',
+        value: `import { ${name} } from "${path}";`,
+    };
+}
+function addClientDirective(node) {
+    node.attributes ??= [];
+    const hasClientDirective = node.attributes.some((attr) => isMdxJsxAttribute(attr) &&
+        typeof attr.name === 'string' &&
+        attr.name.startsWith('client:'));
+    if (!hasClientDirective) {
+        node.attributes.push(createMdxJsxAttribute('client:load', null));
+    }
+}
+function generateComponentFile(code, usedHooks) {
+    const validComponents = allowedComponents.filter((c) => !c.includes('.') && !c.includes('-') && /^[A-Z]/.test(c));
+    const imports = [
+        `import * as Mintlify from "@mintlify/components";`,
+        `const { ${validComponents.join(', ')} } = Mintlify;`,
+    ];
+    if (usedHooks.length > 0) {
+        imports.unshift(`import { ${usedHooks.join(', ')} } from "react";`);
+    }
+    return imports.join('\n') + '\n\n' + code + '\n';
+}
+function findExportedComponents(tree) {
+    const exportedNames = findExportedNodes(tree, 'ArrowFunctionExpression', 'FunctionExpression');
+    if (exportedNames.length === 0) {
+        return { components: [], nodesToRemove: new Set() };
+    }
+    const exportMap = getExportMapFromTree(tree);
+    const nodesToRemove = new Set();
+    visit(tree, 'mdxjsEsm', (node) => {
+        if (exportedNames.some((name) => node.value?.includes(name))) {
+            nodesToRemove.add(node);
+        }
+    });
+    const components = exportedNames
+        .filter((name) => exportMap[name])
+        .map((name) => ({
+        name,
+        code: exportMap[name],
+        usedHooks: detectHooksInCode(exportMap[name]),
+    }));
+    return { components, nodesToRemove };
+}
+function processCompoundNode(node, ctx) {
+    if (!node.name || !COMPOUND_COMPONENTS.has(node.name))
+        return;
+    if (!node.position?.start?.offset || !node.position?.end?.offset) {
+        getLogger()?.warn(`Skipping ${node.name}: missing position info`);
+        return;
+    }
+    const count = (ctx.counters.get(node.name) || 0) + 1;
+    ctx.counters.set(node.name, count);
+    const wrapperName = `${node.name}_${count}`;
+    ctx.compounds.push({
+        wrapperName,
+        mdxSource: ctx.mdxContent.slice(node.position.start.offset, node.position.end.offset),
+    });
+    ctx.nodeReplacements.set(node, wrapperName);
+    return SKIP;
+}
+function findCompoundComponents(tree, mdxContent) {
+    const ctx = {
+        compounds: [],
+        nodeReplacements: new Map(),
+        counters: new Map(),
+        mdxContent,
+    };
+    visitJsxNodes(tree, (node) => processCompoundNode(node, ctx));
+    return { compounds: ctx.compounds, nodeReplacements: ctx.nodeReplacements };
+}
+async function writeComponentFiles(components, componentsDir, pageSlug) {
+    const pageComponentsDir = join(componentsDir, pageSlug);
+    await mkdir(pageComponentsDir, { recursive: true });
+    await Promise.all(components.map(({ name, code, usedHooks }) => writeFile(join(pageComponentsDir, `${name}.jsx`), generateComponentFile(code, usedHooks), 'utf-8')));
+}
+async function compileCompoundComponent(wrapperName, mdxSource) {
+    const compiled = await compile(mdxSource, {
+        jsx: true,
+        outputFormat: 'program',
+        development: false,
+        providerImportSource: MDX_COMPONENTS_PATH,
+    });
+    const compiledStr = String(compiled)
+        .replace(/export default function MDXContent/g, `export function ${wrapperName}`)
+        .replace(/export \{ MDXContent as default \};?/g, '');
+    return compiledStr;
+}
+async function writeCompoundComponentFiles(compounds, componentsDir, pageSlug) {
+    if (compounds.length === 0)
+        return;
+    const pageComponentsDir = join(componentsDir, pageSlug);
+    await mkdir(pageComponentsDir, { recursive: true });
+    await Promise.all(compounds.map(async ({ wrapperName, mdxSource }) => {
+        const code = await compileCompoundComponent(wrapperName, mdxSource);
+        await writeFile(join(pageComponentsDir, `${wrapperName}.jsx`), code, 'utf-8');
+    }));
+}
+function getInsertIndex(tree, skipEsm = false) {
+    const skipTypes = skipEsm ? ['yaml', 'mdxjsEsm'] : ['yaml'];
+    const index = tree.children.findIndex((c) => !skipTypes.includes(c.type));
+    return index === -1 ? tree.children.length : index;
+}
+function transformTree(tree, components, nodesToRemove, relativeComponentsDir) {
+    tree.children = tree.children.filter((child) => !nodesToRemove.has(child));
+    const importNodes = components.map((c) => createImportNode(c.name, posix.join(relativeComponentsDir, `${c.name}.jsx`)));
+    tree.children.splice(getInsertIndex(tree), 0, ...importNodes);
+    const componentNames = new Set(components.map((c) => c.name));
+    visitJsxNodes(tree, (node) => {
+        if (node.name && componentNames.has(node.name)) {
+            addClientDirective(node);
+        }
+    });
+}
+function createReplacementNode(type, wrapperName) {
+    return {
+        type,
+        name: wrapperName,
+        attributes: [createMdxJsxAttribute('client:load', null)],
+        children: [],
+    };
+}
+function transformTreeWithCompounds(tree, compounds, nodeReplacements, relativeComponentsDir) {
+    if (compounds.length === 0)
+        return;
+    const importNodes = compounds.map((c) => createImportNode(c.wrapperName, posix.join(relativeComponentsDir, `${c.wrapperName}.jsx`)));
+    tree.children.splice(getInsertIndex(tree, true), 0, ...importNodes);
+    visitJsxNodes(tree, (node, index, parent) => {
+        const wrapperName = nodeReplacements.get(node);
+        if (!wrapperName || index === undefined || !parent)
+            return;
+        parent.children[index] = createReplacementNode(node.type, wrapperName);
+        return SKIP;
+    });
+}
+function addClientDirectivesToUserComponents(tree, userComponents) {
+    if (userComponents.size === 0)
+        return;
+    visitJsxNodes(tree, (node) => {
+        if (node.name && userComponents.has(node.name)) {
+            addClientDirective(node);
+        }
+    });
+}
+export async function extractReactComponents(mdxContent, mdxFilePath, componentsDir, pageSlug, userComponents) {
+    const tree = getAST(mdxContent, mdxFilePath);
+    const { components, nodesToRemove } = findExportedComponents(tree);
+    const { compounds, nodeReplacements } = findCompoundComponents(tree, mdxContent);
+    if (components.length === 0 &&
+        compounds.length === 0 &&
+        userComponents.size === 0) {
+        return mdxContent;
+    }
+    const mdxDir = dirname(mdxFilePath);
+    const pageComponentsDir = join(componentsDir, pageSlug);
+    const relativeComponentsDir = relative(mdxDir, pageComponentsDir)
+        .split(sep)
+        .join(posix.sep);
+    if (components.length > 0) {
+        await writeComponentFiles(components, componentsDir, pageSlug);
+        transformTree(tree, components, nodesToRemove, relativeComponentsDir);
+    }
+    addClientDirectivesToUserComponents(tree, userComponents);
+    if (compounds.length > 0) {
+        await writeCompoundComponentFiles(compounds, componentsDir, pageSlug);
+        transformTreeWithCompounds(tree, compounds, nodeReplacements, relativeComponentsDir);
+    }
+    return stringifyTree(tree);
+}

package/dist/utils/find-user-components.d.ts

@@ -0,0 +1 @@
+export declare function findUserComponents(docsDir: string): Promise<Set<string>>;

package/dist/utils/find-user-components.js

@@ -0,0 +1,40 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, extname, relative } from 'node:path';
+import { getAST, findExportedNodes, DEFAULT_MINT_IGNORES, } from '@mintlify/common';
+export async function findUserComponents(docsDir) {
+    const components = new Set();
+    async function scanDirectory(dir) {
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        for (const entry of entries) {
+            const fullPath = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!DEFAULT_MINT_IGNORES.includes(entry.name)) {
+                    await scanDirectory(fullPath);
+                }
+            }
+            else {
+                const ext = extname(entry.name).toLowerCase();
+                if (ext === '.jsx' || ext === '.tsx') {
+                    const fileComponents = await extractComponentNames(fullPath, docsDir);
+                    fileComponents.forEach((name) => components.add(name));
+                }
+            }
+        }
+    }
+    await scanDirectory(docsDir);
+    return components;
+}
+async function extractComponentNames(filePath, docsDir) {
+    const content = await readFile(filePath, 'utf-8').catch(() => null);
+    if (!content)
+        return [];
+    try {
+        const relativePath = '/' + relative(docsDir, filePath);
+        const tree = getAST(content, relativePath);
+        const exportedNames = findExportedNodes(tree, 'ArrowFunctionExpression', 'FunctionExpression');
+        return exportedNames.filter((name) => /^[A-Z]/.test(name));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/utils/load-all-snippets.d.ts

@@ -0,0 +1,7 @@
+import type { Root } from 'mdast';
+export interface SnippetFile {
+    filename: string;
+    tree: Root;
+    content: string;
+}
+export declare function loadAllSnippets(docsDir: string): Promise<SnippetFile[]>;

package/dist/utils/load-all-snippets.js

@@ -0,0 +1,63 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, extname, relative } from 'node:path';
+import { getAST, SNIPPET_EXTENSIONS, topologicalSort, extractImportSources, resolveImportPath, DEFAULT_MINT_IGNORES, } from '@mintlify/common';
+import { getLogger } from './logger.js';
+async function scanDirectory(dir, rootDir, files = []) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (DEFAULT_MINT_IGNORES.includes(entry.name)) {
+                continue;
+            }
+            await scanDirectory(fullPath, rootDir, files);
+        }
+        else {
+            const ext = extname(entry.name).toLowerCase();
+            if (SNIPPET_EXTENSIONS.includes(ext)) {
+                const relativePath = '/' + relative(rootDir, fullPath);
+                files.push({ path: fullPath, relativePath });
+            }
+        }
+    }
+    return files;
+}
+export async function loadAllSnippets(docsDir) {
+    const files = await scanDirectory(docsDir, docsDir);
+    const snippets = [];
+    for (const file of files) {
+        try {
+            const content = await readFile(file.path, 'utf-8');
+            const tree = getAST(content, file.relativePath);
+            snippets.push({
+                filename: file.relativePath,
+                tree,
+                content,
+            });
+        }
+        catch (error) {
+            getLogger()?.warn(`Failed to parse ${file.relativePath}: ${error}`);
+        }
+    }
+    const graph = {};
+    for (const snippet of snippets) {
+        const normalizedPath = snippet.filename.toLowerCase();
+        graph[normalizedPath] = [];
+        const importSources = extractImportSources(snippet.tree);
+        for (const source of importSources) {
+            const resolved = resolveImportPath(source, snippet.filename);
+            if (resolved) {
+                graph[normalizedPath].push(resolved.toLowerCase());
+            }
+        }
+    }
+    const sortedPaths = topologicalSort(graph);
+    const sortedSnippets = [];
+    for (const path of sortedPaths) {
+        const snippet = snippets.find((s) => s.filename.toLowerCase() === path.toLowerCase());
+        if (snippet) {
+            sortedSnippets.push(snippet);
+        }
+    }
+    return sortedSnippets;
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,3 @@
+import type { AstroIntegrationLogger } from 'astro';
+export declare function initLogger(logger: AstroIntegrationLogger): void;
+export declare function getLogger(): AstroIntegrationLogger | undefined;

package/dist/utils/logger.js

@@ -0,0 +1,7 @@
+let _logger;
+export function initLogger(logger) {
+    _logger = logger;
+}
+export function getLogger() {
+    return _logger;
+}

package/dist/utils/mintlify-components.d.ts

@@ -0,0 +1,121 @@
+import type { ReactNode } from 'react';
+import type { MDXComponents } from 'mdx/types';
+export declare const components: {
+    Accordion: (({ title, description, defaultOpen, icon, iconType, children, className, _disabled, trackOpen, trackClose, onMount, topOffset, getInitialOpenFromUrl, onUrlStateChange, _onKeyDownCapture, }: import("@mintlify/components").AccordionProps) => import("react/jsx-runtime").JSX.Element) & {
+        Group: ({ children, className }: import("@mintlify/components").AccordionGroupProps) => import("react/jsx-runtime").JSX.Element;
+    };
+    Badge: ({ children, className, color, shape, variant: variantProp, stroke, disabled, size, leadIcon, tailIcon: tailIconProp, icon, iconType, iconLibrary, onClick, href, }: import("@mintlify/components").BadgeProps) => import("react/jsx-runtime").JSX.Element;
+    Callout: ({ children, variant, icon, iconType, iconLibrary, color, className, ariaLabel, }: import("@mintlify/components").CalloutProps) => import("react/jsx-runtime").JSX.Element;
+    Card: ({ title, icon, iconType, iconLibrary, color, horizontal, href, img, children, disabled, cta, arrow, as, className, }: import("@mintlify/components").CardComponentProps) => import("react/jsx-runtime").JSX.Element;
+    Check: (props: {
+        children: ReactNode;
+        className?: string | undefined;
+        color?: string | undefined;
+        icon?: ReactNode;
+        iconType?: ("brands" | "duotone" | "light" | "regular" | "sharp-duotone-solid" | "sharp-light" | "sharp-regular" | "sharp-solid" | "sharp-thin" | "solid" | "thin") | undefined;
+        iconLibrary?: ("fontawesome" | "lucide") | undefined;
+        ariaLabel?: string | undefined;
+    }) => import("react/jsx-runtime").JSX.Element;
+    CodeBlock: (params: import("@mintlify/components").CodeBlockProps) => import("react/jsx-runtime").JSX.Element;
+    CodeGroup: ({ children, isSmallText, className, noMargins, dropdown, feedbackModalOpen, anchorRef, codeBlockTheme, codeBlockThemeObject, initialSelectedTab, onSelectedTabChange, askAiButton, feedbackButton, copyButtonProps, }: import("@mintlify/components").CodeGroupProps) => import("react/jsx-runtime").JSX.Element | null;
+    Color: {
+        ({ children, variant, className }: import("@mintlify/components").ColorProps): import("react/jsx-runtime").JSX.Element;
+        Row: ({ children, title }: import("@mintlify/components").ColorRowProps) => import("react/jsx-runtime").JSX.Element;
+        Item: ({ name, value }: import("@mintlify/components").ColorItemProps) => import("react/jsx-runtime").JSX.Element;
+    };
+    Columns: ({ children, className, cols }: import("@mintlify/components").ColumnsProps) => import("react/jsx-runtime").JSX.Element;
+    Danger: (props: {
+        children: ReactNode;
+        className?: string | undefined;
+        color?: string | undefined;
+        icon?: ReactNode;
+        iconType?: ("brands" | "duotone" | "light" | "regular" | "sharp-duotone-solid" | "sharp-light" | "sharp-regular" | "sharp-solid" | "sharp-thin" | "solid" | "thin") | undefined;
+        iconLibrary?: ("fontawesome" | "lucide") | undefined;
+        ariaLabel?: string | undefined;
+    }) => import("react/jsx-runtime").JSX.Element;
+    Expandable: ({ title, defaultOpen, onChange: onChangeProp, lazy, className, children, uniqueParamId, onMount, onOpen, onClose, openedText, closedText, hasScrolledToAnchorRef, anchor, }: import("@mintlify/components").ExpandableProps) => import("react/jsx-runtime").JSX.Element;
+    Frame: ({ as: Component, title, description, renderDescription, style, className, children, }: import("@mintlify/components").FrameProps) => import("react/jsx-runtime").JSX.Element;
+    Icon: ({ icon, iconType, color, colorLight, colorDark, size, className, iconLibrary, basePath, pageType, overrideColor, overrideSize, }: import("@mintlify/components").IconProps) => import("react/jsx-runtime").JSX.Element | null;
+    Info: (props: {
+        children: ReactNode;
+        className?: string | undefined;
+        color?: string | undefined;
+        icon?: ReactNode;
+        iconType?: ("brands" | "duotone" | "light" | "regular" | "sharp-duotone-solid" | "sharp-light" | "sharp-regular" | "sharp-solid" | "sharp-thin" | "solid" | "thin") | undefined;
+        iconLibrary?: ("fontawesome" | "lucide") | undefined;
+        ariaLabel?: string | undefined;
+    }) => import("react/jsx-runtime").JSX.Element;
+    Mermaid: ({ chart, className, ariaLabel, placement, actions, }: import("@mintlify/components").MermaidProps) => import("react/jsx-runtime").JSX.Element;
+    Note: (props: {
+        children: ReactNode;
+        className?: string | undefined;
+        color?: string | undefined;
+        icon?: ReactNode;
+        iconType?: ("brands" | "duotone" | "light" | "regular" | "sharp-duotone-solid" | "sharp-light" | "sharp-regular" | "sharp-solid" | "sharp-thin" | "solid" | "thin") | undefined;
+        iconLibrary?: ("fontawesome" | "lucide") | undefined;
+        ariaLabel?: string | undefined;
+    }) => import("react/jsx-runtime").JSX.Element;
+    Panel: ({ children, className, ...props }: import("@mintlify/components").PanelProps) => import("react/jsx-runtime").JSX.Element;
+    Property: ({ name, type, location, hidden, default: defaultValue, required, deprecated, children, id, pre, post, className, onMount, navigateToHeaderAriaLabel, defaultLabel, requiredLabel, deprecatedLabel, }: import("@mintlify/components").PropertyProps) => import("react/jsx-runtime").JSX.Element | null;
+    Steps: {
+        ({ children, titleSize, className }: import("@mintlify/components").StepsProps): import("react/jsx-runtime").JSX.Element;
+        Item: ({ stepNumber, icon, iconType, iconLibrary, title, children, titleSize, className, isLast, id, noAnchor, scrollElementIntoView, onRegisterHeading, onUnregisterHeading, _hasContext, onCopyAnchorLink, }: import("@mintlify/components").StepsItemProps) => import("react/jsx-runtime").JSX.Element;
+    };
+    Tabs: (({ children, defaultTabIndex, onTabChange, className, borderBottom, ariaLabel, panelsRef, }: import("@mintlify/components").TabsProps) => import("react/jsx-runtime").JSX.Element) & {
+        Item: ({ children }: import("@mintlify/components").TabsItemProps) => import("react/jsx-runtime").JSX.Element;
+    };
+    Tile: ({ href, children, title, description, className }: import("@mintlify/components").TileProps) => import("react/jsx-runtime").JSX.Element;
+    Tip: (props: {
+        children: ReactNode;
+        className?: string | undefined;
+        color?: string | undefined;
+        icon?: ReactNode;
+        iconType?: ("brands" | "duotone" | "light" | "regular" | "sharp-duotone-solid" | "sharp-light" | "sharp-regular" | "sharp-solid" | "sharp-thin" | "solid" | "thin") | undefined;
+        iconLibrary?: ("fontawesome" | "lucide") | undefined;
+        ariaLabel?: string | undefined;
+    }) => import("react/jsx-runtime").JSX.Element;
+    Tooltip: ({ description, children, title, cta, href, className, side, align, }: import("@mintlify/components").TooltipProps) => import("react/jsx-runtime").JSX.Element | null;
+    Tree: (({ className, children }: import("@mintlify/components").TreeProps) => import("react/jsx-runtime").JSX.Element) & {
+        File: ({ name }: import("@mintlify/components").TreeFileProps) => import("react/jsx-runtime").JSX.Element;
+        Folder: ({ name, defaultOpen, children, openable: _openable, }: import("@mintlify/components").TreeFolderProps) => import("react/jsx-runtime").JSX.Element;
+    };
+    Update: import("react").ForwardRefExoticComponent<{
+        id: string;
+        label: string;
+        description?: string;
+        tags?: string[];
+        rss?: {
+            title?: string;
+            description?: string;
+        };
+        onRegisterHeading?: (id: string, rect: import("react-use-rect").Rect) => void;
+        onUnregisterHeading?: (id: string) => void;
+        hasContext?: boolean;
+        isVisible: boolean;
+        onCopyAnchorLink?: (id: string) => void;
+    } & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof {
+        id: string;
+        label: string;
+        description?: string;
+        tags?: string[];
+        rss?: {
+            title?: string;
+            description?: string;
+        };
+        onRegisterHeading?: (id: string, rect: import("react-use-rect").Rect) => void;
+        onUnregisterHeading?: (id: string) => void;
+        hasContext?: boolean;
+        isVisible: boolean;
+        onCopyAnchorLink?: (id: string) => void;
+    }> & import("react").RefAttributes<HTMLDivElement>>;
+    Warning: (props: {
+        children: ReactNode;
+        className?: string | undefined;
+        color?: string | undefined;
+        icon?: ReactNode;
+        iconType?: ("brands" | "duotone" | "light" | "regular" | "sharp-duotone-solid" | "sharp-light" | "sharp-regular" | "sharp-solid" | "sharp-thin" | "solid" | "thin") | undefined;
+        iconLibrary?: ("fontawesome" | "lucide") | undefined;
+        ariaLabel?: string | undefined;
+    }) => import("react/jsx-runtime").JSX.Element;
+};
+export declare function useMDXComponents(): MDXComponents;

package/dist/utils/mintlify-components.js

@@ -0,0 +1,65 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Accordion, Badge, Callout, Card, Check, CodeBlock, CodeGroup, Color, Columns, Danger, Expandable, Frame, Icon, Info, Mermaid, Note, Panel, Property, Steps, Tabs, Tile, Tip, Tooltip, Tree, Update, Warning, } from '@mintlify/components';
+const Wrapper = ({ children }) => (_jsx("div", { children: children }));
+const MintlifyComponents = {
+    Accordion,
+    Badge,
+    Callout,
+    Card,
+    Check,
+    CodeBlock,
+    CodeGroup,
+    Color,
+    Columns,
+    Danger,
+    Expandable,
+    Frame,
+    Icon,
+    Info,
+    Mermaid,
+    Note,
+    Panel,
+    Property,
+    Steps,
+    Tabs,
+    Tile,
+    Tip,
+    Tooltip,
+    Tree,
+    Update,
+    Warning,
+};
+const placeholderComponents = {
+    AccordionGroup: Wrapper,
+    ApiPlayground: Wrapper,
+    CardGroup: Wrapper,
+    Column: Wrapper,
+    CustomCode: Wrapper,
+    CustomComponent: Wrapper,
+    DynamicCustomComponent: Wrapper,
+    Heading: Wrapper,
+    Latex: Wrapper,
+    Link: Wrapper,
+    Loom: Wrapper,
+    MDXContentController: Wrapper,
+    Param: Wrapper,
+    ParamField: Wrapper,
+    PreviewButton: Wrapper,
+    RequestExample: Wrapper,
+    ResponseExample: Wrapper,
+    ResponseField: Wrapper,
+    Snippet: Wrapper,
+    SnippetGroup: Wrapper,
+    View: Wrapper,
+};
+export const components = {
+    ...MintlifyComponents,
+    ...placeholderComponents,
+};
+export function useMDXComponents() {
+    return {
+        ...components,
+        Step: Steps.Item,
+        Tab: Tabs.Item,
+    };
+}

package/dist/utils/read-docs-config.d.ts

@@ -0,0 +1,2 @@
+import type { DocsConfig } from '@mintlify/validation';
+export declare function readDocsConfig(docsDir: string): Promise<DocsConfig>;

package/dist/utils/read-docs-config.js

@@ -0,0 +1,7 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function readDocsConfig(docsDir) {
+    const configPath = join(docsDir, 'docs.json');
+    const content = await readFile(configPath, 'utf-8');
+    return JSON.parse(content);
+}

package/dist/utils/read-page-content.d.ts

@@ -0,0 +1,5 @@
+export interface PageContent {
+    content: string;
+    slug: string;
+}
+export declare function readPageContent(pagePath: string, docsDir: string): Promise<PageContent>;

package/dist/utils/read-page-content.js

@@ -0,0 +1,10 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function readPageContent(pagePath, docsDir) {
+    const filePath = join(docsDir, `${pagePath}.mdx`);
+    const content = await readFile(filePath, 'utf-8');
+    return {
+        content,
+        slug: pagePath,
+    };
+}

package/dist/utils/resolve-snippets.d.ts

@@ -0,0 +1,2 @@
+import type { SnippetFile } from './load-all-snippets.js';
+export declare function resolveSnippets(content: string, filename: string, snippets: SnippetFile[]): Promise<string>;

package/dist/utils/resolve-snippets.js

@@ -0,0 +1,28 @@
+import { getAST, findAndRemoveImports, resolveAllImports, stringifyTree, } from '@mintlify/common';
+import { getLogger } from './logger.js';
+export async function resolveSnippets(content, filename, snippets) {
+    try {
+        const tree = getAST(content, filename);
+        const { importMap, tree: treeWithoutImports } = await findAndRemoveImports(structuredClone(tree));
+        if (Object.keys(importMap).length === 0) {
+            return content;
+        }
+        const snippetTrees = snippets.map((s) => ({
+            filename: s.filename,
+            tree: s.tree,
+        }));
+        const resolvedTree = await resolveAllImports({
+            snippets: snippetTrees,
+            fileWithImports: {
+                tree: treeWithoutImports,
+                filename,
+                importMap,
+            },
+        });
+        return stringifyTree(resolvedTree);
+    }
+    catch (error) {
+        getLogger()?.warn(`Failed to resolve snippets in ${filename}: ${error}`);
+        return content;
+    }
+}

package/dist/utils/write-favicons-manifest.d.ts

@@ -0,0 +1,2 @@
+import type { Favicons } from '../types';
+export declare function writeFaviconsManifest(srcDir: string, favicons: Favicons): Promise<void>;

package/dist/utils/write-favicons-manifest.js

@@ -0,0 +1,8 @@
+import { join } from 'node:path';
+import { mkdir, writeFile } from 'node:fs/promises';
+export async function writeFaviconsManifest(srcDir, favicons) {
+    const generatedDir = join(srcDir, 'content/generated');
+    await mkdir(generatedDir, { recursive: true });
+    const filePath = join(generatedDir, 'favicons.json');
+    await writeFile(filePath, JSON.stringify(favicons, null, 2));
+}

package/dist/utils/write-page-content.d.ts

@@ -0,0 +1,10 @@
+import type { SnippetFile } from './load-all-snippets.js';
+export interface WritePageContentOptions {
+    content: string;
+    slug: string;
+    contentDir: string;
+    componentsDir: string;
+    userComponents: Set<string>;
+    snippets: SnippetFile[];
+}
+export declare function writePageContent({ content, slug, contentDir, componentsDir, userComponents, snippets, }: WritePageContentOptions): Promise<void>;

package/dist/utils/write-page-content.js

@@ -0,0 +1,28 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { extractReactComponents } from './extract-react-components.js';
+import { resolveSnippets } from './resolve-snippets.js';
+export async function writePageContent({ content, slug, contentDir, componentsDir, userComponents, snippets, }) {
+    let filePath;
+    if (slug === 'index') {
+        filePath = join(contentDir, 'index.mdx');
+    }
+    else {
+        const parts = slug.split('/');
+        const fileName = parts.pop() + '.mdx';
+        const dirPath = join(contentDir, ...parts);
+        if (parts.length > 0) {
+            await mkdir(dirPath, { recursive: true });
+        }
+        filePath = join(dirPath, fileName);
+    }
+    // Resolve all snippet/MDX imports by inlining their content
+    // This happens before React component extraction since snippets may contain React components
+    const contentWithResolvedSnippets = await resolveSnippets(content, `/${slug}.mdx`, snippets);
+    // Extract compound React components to separate .jsx files
+    // This is necessary because Astro compiles MDX with its own JSX runtime,
+    // which is incompatible with React hooks. By extracting to .jsx files and
+    // re-importing with client:load, we ensure React's JSX runtime handles these components.
+    const finalContent = await extractReactComponents(contentWithResolvedSnippets, filePath, componentsDir, slug, userComponents);
+    await writeFile(filePath, finalContent, 'utf-8');
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@mintlify/astro",
+  "version": "0.1.1",
+  "description": "Mintlify integration for Astro",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./components": {
+      "types": "./dist/components.d.ts",
+      "import": "./dist/components.js"
+    }
+  },
+  "scripts": {
+    "prepare": "npm run build",
+    "build": "tsc",
+    "type": "tsc --noEmit"
+  },
+  "author": "Mintlify, Inc.",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@mdx-js/mdx": "^3.1.1",
+    "@mintlify/common": "^1.0.716",
+    "@mintlify/validation": "^0.1.587",
+    "unist-util-visit": "^5.1.0"
+  },
+  "devDependencies": {
+    "@mintlify/components": "^1.0.4",
+    "@types/node": "^25.2.2",
+    "@types/react": "^19.2.13",
+    "astro": "^5.17.1",
+    "mdast": "^2.3.2",
+    "mdast-util-mdx": "^3.0.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "@astrojs/mdx": "^4.3.1",
+    "@astrojs/react": "^4.4.2",
+    "@mintlify/components": "^1.0.4",
+    "astro": "^5",
+    "react": "^18 || ^19"
+  }
+}