@brainfish-ai/devdoc 0.1.44 → 0.1.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainfish-ai/devdoc",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "description": "Documentation framework for developers. Write docs in MDX, preview locally, deploy to Brainfish.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/renderer/app/api/docs/route.js

@@ -8,6 +8,7 @@ import rehypeSlug from 'rehype-slug';
 // Note: rehype-pretty-code is dynamically imported to handle serverless environments
 // where shiki may not be fully available
 import { getProjectFile } from '@/lib/storage/blob';
+import { remarkMermaid } from '@/lib/docs/mdx/remark-mermaid';
 const STARTER_PATH = process.env.STARTER_PATH || 'devdoc-docs';
 // Helper to get content root - supports both relative and absolute paths
 function getContentRoot() {
@@ -68,7 +69,8 @@ export async function GET(request) {
             mdxSource = await serialize(content, {
                 mdxOptions: {
                     remarkPlugins: [
-                        remarkGfm
+                        remarkGfm,
+                        remarkMermaid
                     ],
                     rehypePlugins: [
                         rehypeSlug,
@@ -86,7 +88,8 @@ export async function GET(request) {
             mdxSource = await serialize(content, {
                 mdxOptions: {
                     remarkPlugins: [
-                        remarkGfm
+                        remarkGfm,
+                        remarkMermaid
                     ],
                     rehypePlugins: [
                         rehypeSlug
@@ -149,7 +152,8 @@ export async function GET(request) {
             mdxSource = await serialize(content, {
                 mdxOptions: {
                     remarkPlugins: [
-                        remarkGfm
+                        remarkGfm,
+                        remarkMermaid
                     ],
                     rehypePlugins: [
                         rehypeSlug,
@@ -167,7 +171,8 @@ export async function GET(request) {
             mdxSource = await serialize(content, {
                 mdxOptions: {
                     remarkPlugins: [
-                        remarkGfm
+                        remarkGfm,
+                        remarkMermaid
                     ],
                     rehypePlugins: [
                         rehypeSlug

package/renderer/components/docs-viewer/content/doc-page.js

@@ -6,6 +6,7 @@ import { MDXRemote } from 'next-mdx-remote';
 import { useDocsNavigation } from '@/lib/docs-navigation-context';
 import { useCodeCopy } from '@/hooks/use-code-copy';
 import { NotFoundPage } from './not-found-page';
+import { MDXErrorBoundary } from './mdx-error-boundary';
 // Custom Link component for MDX - uses docs navigation context
 function MdxLink({ href, children, ...props }) {
     const docsNav = useDocsNavigation();
@@ -213,29 +214,65 @@ export function DocPage({ slug, onSearch }) {
     const showHeader = !hideHeader && !isCustomMode;
     // Custom mode: Full-width layout for landing pages
     if (isCustomMode) {
-        return /*#__PURE__*/ _jsx("div", {
-            ref: contentRef,
-            className: "docs-page docs-page-custom docs-content w-full min-h-full",
-            style: {
-                background: background || 'var(--background)',
-                // Ensure the content fills the entire viewport width within the content area
-                marginLeft: 0,
-                marginRight: 0
-            },
+        return /*#__PURE__*/ _jsx(MDXErrorBoundary, {
+            slug: slug,
             children: /*#__PURE__*/ _jsx("div", {
-                className: "docs-custom-content [&>*]:w-full",
-                children: /*#__PURE__*/ _jsx(MDXRemote, {
-                    ...pageData.mdxSource,
-                    components: mdxComponents
+                ref: contentRef,
+                className: "docs-page docs-page-custom docs-content w-full min-h-full",
+                style: {
+                    background: background || 'var(--background)',
+                    // Ensure the content fills the entire viewport width within the content area
+                    marginLeft: 0,
+                    marginRight: 0
+                },
+                children: /*#__PURE__*/ _jsx("div", {
+                    className: "docs-custom-content [&>*]:w-full",
+                    children: /*#__PURE__*/ _jsx(MDXRemote, {
+                        ...pageData.mdxSource,
+                        components: mdxComponents
+                    })
                 })
             })
         });
     }
     // Wide mode: No prose wrapper (for landing pages with custom components)
     if (isWideMode) {
-        return /*#__PURE__*/ _jsxs("div", {
+        return /*#__PURE__*/ _jsx(MDXErrorBoundary, {
+            slug: slug,
+            children: /*#__PURE__*/ _jsxs("div", {
+                ref: contentRef,
+                className: "docs-page docs-content max-w-6xl mx-auto px-4 py-6 sm:px-8 sm:py-8",
+                children: [
+                    showHeader && /*#__PURE__*/ _jsxs("div", {
+                        className: "docs-page-header mb-6",
+                        children: [
+                            /*#__PURE__*/ _jsx("h1", {
+                                className: "docs-content-title text-2xl sm:text-3xl font-bold mb-2 text-foreground",
+                                children: pageData.frontmatter.title
+                            }),
+                            pageData.frontmatter.description && /*#__PURE__*/ _jsx("p", {
+                                className: "docs-content-description text-lg text-muted-foreground",
+                                children: pageData.frontmatter.description
+                            })
+                        ]
+                    }),
+                    /*#__PURE__*/ _jsx("div", {
+                        className: "docs-wide-content",
+                        children: /*#__PURE__*/ _jsx(MDXRemote, {
+                            ...pageData.mdxSource,
+                            components: mdxComponents
+                        })
+                    })
+                ]
+            })
+        });
+    }
+    // Default mode: Standard documentation layout with prose
+    return /*#__PURE__*/ _jsx(MDXErrorBoundary, {
+        slug: slug,
+        children: /*#__PURE__*/ _jsxs("div", {
             ref: contentRef,
-            className: "docs-page docs-content max-w-6xl mx-auto px-4 py-6 sm:px-8 sm:py-8",
+            className: "docs-page docs-content max-w-4xl mx-auto px-4 py-6 sm:px-8 sm:py-8",
             children: [
                 showHeader && /*#__PURE__*/ _jsxs("div", {
                     className: "docs-page-header mb-6",
@@ -251,40 +288,13 @@ export function DocPage({ slug, onSearch }) {
                     ]
                 }),
                 /*#__PURE__*/ _jsx("div", {
-                    className: "docs-wide-content",
+                    className: "docs-prose prose prose-sm max-w-none prose-headings:text-foreground prose-p:text-muted-foreground prose-strong:text-foreground prose-code:text-foreground prose-pre:bg-muted prose-code:bg-muted prose-code:px-1 prose-code:py-0.5 prose-code:rounded prose-pre:overflow-x-auto prose-table:w-full prose-th:text-left prose-th:p-3 prose-th:bg-muted prose-td:p-3 prose-td:border-b prose-td:border-border",
                     children: /*#__PURE__*/ _jsx(MDXRemote, {
                         ...pageData.mdxSource,
                         components: mdxComponents
                     })
                 })
             ]
-        });
-    }
-    // Default mode: Standard documentation layout with prose
-    return /*#__PURE__*/ _jsxs("div", {
-        ref: contentRef,
-        className: "docs-page docs-content max-w-4xl mx-auto px-4 py-6 sm:px-8 sm:py-8",
-        children: [
-            showHeader && /*#__PURE__*/ _jsxs("div", {
-                className: "docs-page-header mb-6",
-                children: [
-                    /*#__PURE__*/ _jsx("h1", {
-                        className: "docs-content-title text-2xl sm:text-3xl font-bold mb-2 text-foreground",
-                        children: pageData.frontmatter.title
-                    }),
-                    pageData.frontmatter.description && /*#__PURE__*/ _jsx("p", {
-                        className: "docs-content-description text-lg text-muted-foreground",
-                        children: pageData.frontmatter.description
-                    })
-                ]
-            }),
-            /*#__PURE__*/ _jsx("div", {
-                className: "docs-prose prose prose-sm max-w-none prose-headings:text-foreground prose-p:text-muted-foreground prose-strong:text-foreground prose-code:text-foreground prose-pre:bg-muted prose-code:bg-muted prose-code:px-1 prose-code:py-0.5 prose-code:rounded prose-pre:overflow-x-auto prose-table:w-full prose-th:text-left prose-th:p-3 prose-th:bg-muted prose-td:p-3 prose-td:border-b prose-td:border-border",
-                children: /*#__PURE__*/ _jsx(MDXRemote, {
-                    ...pageData.mdxSource,
-                    components: mdxComponents
-                })
-            })
-        ]
+        })
     });
 }

package/renderer/components/docs-viewer/content/mdx-error-boundary.js

@@ -0,0 +1,184 @@
+'use client';
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component } from 'react';
+import { Warning, ArrowClockwise, Code, FileText } from '@phosphor-icons/react';
+/**
+ * Error boundary for MDX content rendering.
+ * Catches rendering errors and displays helpful guidance.
+ */ export class MDXErrorBoundary extends Component {
+    static getDerivedStateFromError(error) {
+        return {
+            hasError: true,
+            error
+        };
+    }
+    componentDidCatch(error, errorInfo) {
+        console.error('[MDX Rendering Error]', error, errorInfo);
+    }
+    render() {
+        if (this.state.hasError) {
+            const errorMessage = this.state.error?.message || 'Unknown error';
+            const suggestions = getErrorSuggestions(errorMessage);
+            return /*#__PURE__*/ _jsx("div", {
+                className: "docs-page docs-page-error w-full min-h-[200px] max-w-4xl mx-auto px-4 py-6 sm:px-8 sm:py-8",
+                children: /*#__PURE__*/ _jsxs("div", {
+                    className: "rounded-lg border border-amber-200 dark:border-amber-800 bg-amber-50 dark:bg-amber-950/50 p-6",
+                    children: [
+                        /*#__PURE__*/ _jsxs("div", {
+                            className: "flex items-start gap-3 mb-4",
+                            children: [
+                                /*#__PURE__*/ _jsx(Warning, {
+                                    className: "h-6 w-6 text-amber-600 dark:text-amber-400 flex-shrink-0 mt-0.5",
+                                    weight: "fill"
+                                }),
+                                /*#__PURE__*/ _jsxs("div", {
+                                    children: [
+                                        /*#__PURE__*/ _jsx("h2", {
+                                            className: "text-lg font-semibold text-amber-900 dark:text-amber-100",
+                                            children: "Unable to render this page"
+                                        }),
+                                        /*#__PURE__*/ _jsx("p", {
+                                            className: "text-sm text-amber-700 dark:text-amber-300 mt-1",
+                                            children: "There's a syntax error in the MDX content that prevented rendering."
+                                        })
+                                    ]
+                                })
+                            ]
+                        }),
+                        /*#__PURE__*/ _jsxs("div", {
+                            className: "bg-amber-100 dark:bg-amber-900/50 rounded-md p-3 mb-4",
+                            children: [
+                                /*#__PURE__*/ _jsx("p", {
+                                    className: "text-xs font-medium text-amber-800 dark:text-amber-200 mb-1",
+                                    children: "Error message:"
+                                }),
+                                /*#__PURE__*/ _jsx("code", {
+                                    className: "text-sm text-amber-900 dark:text-amber-100 break-all",
+                                    children: errorMessage
+                                })
+                            ]
+                        }),
+                        /*#__PURE__*/ _jsxs("div", {
+                            className: "space-y-3",
+                            children: [
+                                /*#__PURE__*/ _jsx("p", {
+                                    className: "text-sm font-medium text-amber-800 dark:text-amber-200",
+                                    children: "Common causes and fixes:"
+                                }),
+                                /*#__PURE__*/ _jsx("ul", {
+                                    className: "space-y-2",
+                                    children: suggestions.map((suggestion, index)=>/*#__PURE__*/ _jsxs("li", {
+                                            className: "flex items-start gap-2 text-sm text-amber-700 dark:text-amber-300",
+                                            children: [
+                                                /*#__PURE__*/ _jsx(suggestion.icon, {
+                                                    className: "h-4 w-4 flex-shrink-0 mt-0.5",
+                                                    weight: "bold"
+                                                }),
+                                                /*#__PURE__*/ _jsxs("div", {
+                                                    children: [
+                                                        /*#__PURE__*/ _jsxs("span", {
+                                                            className: "font-medium",
+                                                            children: [
+                                                                suggestion.title,
+                                                                ":"
+                                                            ]
+                                                        }),
+                                                        ' ',
+                                                        suggestion.description
+                                                    ]
+                                                })
+                                            ]
+                                        }, index))
+                                })
+                            ]
+                        }),
+                        /*#__PURE__*/ _jsxs("button", {
+                            onClick: this.handleRetry,
+                            className: "mt-6 inline-flex items-center gap-2 px-4 py-2 text-sm font-medium rounded-md bg-amber-200 dark:bg-amber-800 text-amber-900 dark:text-amber-100 hover:bg-amber-300 dark:hover:bg-amber-700 transition-colors",
+                            children: [
+                                /*#__PURE__*/ _jsx(ArrowClockwise, {
+                                    className: "h-4 w-4",
+                                    weight: "bold"
+                                }),
+                                "Try again"
+                            ]
+                        })
+                    ]
+                })
+            });
+        }
+        return this.props.children;
+    }
+    constructor(props){
+        super(props), _define_property(this, "handleRetry", ()=>{
+            this.setState({
+                hasError: false,
+                error: null
+            });
+        });
+        this.state = {
+            hasError: false,
+            error: null
+        };
+    }
+}
+/**
+ * Get context-aware error suggestions based on the error message
+ */ function getErrorSuggestions(errorMessage) {
+    const suggestions = [];
+    // Check for common MDX errors
+    if (errorMessage.includes('Unexpected') || errorMessage.includes('Expected')) {
+        suggestions.push({
+            icon: Code,
+            title: 'JSX Syntax',
+            description: 'Check for unclosed tags, missing quotes in attributes, or invalid JSX expressions. All tags must be properly closed (e.g., <Image /> not <Image>).'
+        });
+    }
+    if (errorMessage.includes('is not defined') || errorMessage.includes('is not a function')) {
+        suggestions.push({
+            icon: Code,
+            title: 'Unknown Component',
+            description: 'A component used in this page may not be available. Check that all component names are spelled correctly and are supported.'
+        });
+    }
+    if (errorMessage.includes('mermaid') || errorMessage.includes('Mermaid')) {
+        suggestions.push({
+            icon: Code,
+            title: 'Mermaid Syntax',
+            description: 'Check your Mermaid diagram syntax. Ensure proper indentation and valid diagram type (flowchart, sequenceDiagram, etc.).'
+        });
+    }
+    if (errorMessage.includes('frontmatter') || errorMessage.includes('yaml')) {
+        suggestions.push({
+            icon: FileText,
+            title: 'Frontmatter Format',
+            description: 'Ensure frontmatter is valid YAML between --- markers at the top of the file.'
+        });
+    }
+    // Always add generic suggestions
+    suggestions.push({
+        icon: Code,
+        title: 'Curly Braces',
+        description: 'In MDX, curly braces {} are for JavaScript expressions. Use {"{"} and {"}"} to display literal braces.'
+    });
+    suggestions.push({
+        icon: FileText,
+        title: 'Special Characters',
+        description: 'Characters like <, >, and & may need to be escaped or wrapped in JSX expressions.'
+    });
+    return suggestions.slice(0, 4) // Limit to 4 suggestions
+    ;
+}