docstra 1.6.3 → 1.7.0

package/README.md

@@ -1,77 +1,137 @@
-# **Docstra**
+# Docstra
 
-Docstra is a modern documentation framework for Next.js. It's built with Tailwind CSS and MDX, making it easy to create beautiful and responsive documentation sites.
+**The Modern Documentation Framework for Next.js**
 
-> Documentation of Docstra is coming soon. Stay tuned!
+Docstra is a powerful, type-safe, and easy-to-use documentation framework built for Next.js 15+ App Router. It provides a beautiful default theme, MDX support, and flexible components to build your documentation site in minutes.
 
-> For any questions, feel free to reach out us on [contact@sudhucodes.com](mailto:contact@sudhucodes.com)
+---
 
-## Features
+## 🚀 Quick Start
 
-- MDX support
-- Custom content directories
-- Works in monorepos
-- Beautiful sidebar + TOC
-- Edit-on-GitHub links
-- Search coming soon
+### 1. Installation
 
-## Install
+Install `docstra` and its peer dependencies:
 
 ```bash
-npm install docstra
+npm install docstra next-mdx-remote gray-matter lucide-react prism-react-renderer react-toast-msg
 ```
 
-## Usage
+### 2. Configuration
+
+Create `docstra.config.ts` in your project root:
 
 ```ts
-// docstra.config.ts
-import { defineDocstraConfig } from 'docstra/config';
-
-export default defineDocstraConfig({
-    siteName: 'Docstra',
-    githubRepo: 'https://github.com/sudhucodes/docstra',
-    contentDir: 'docs/content',
-    editOnGithub: true,
-    feedback: {
-        enabled: true,
-        formSyncFormID: 'FORM_ID'
-    },
-    navbar: {
-        logo: {
-            link: '/docs',
-            src: '/logo.svg',
-            alt: 'Logo',
-            className: 'h-9.5 w-auto'
-        },
-        links: [
-            { name: 'Guides', href: '/docs/guides' },
-            { name: 'Examples', href: '/docs/examples' }
-        ]
+import { DocstraConfig } from "docstra/config";
+
+const config: DocstraConfig = {
+    title: "My Docs",
+    description: "Documentation for my project",
+    github: {
+        user: "myuser",
+        repo: "myrepo",
     },
     sidebar: {
-        links: [
-            {
-                section: 'Introduction',
-                items: [
-                    {
-                        name: 'Overview',
-                        href: '/docs',
-                        icon: 'NotebookPenIcon'
-                    },
-                    {
-                        name: 'Quick Start',
-                        href: '/docs/quick-start',
-                        icon: 'RocketIcon'
-                    }
-                ]
-            },
-            {
-                section: 'Tailwind Setup',
-                items: [{ name: 'Installation', href: '/docs/setup/installation' }]
-            }
-        ]
+        // ... sidebar entries
     }
-});
+};
+
+export default config;
+```
+
+### 3. Source Setup
+
+Create `src/lib/source.ts` (or `lib/source.ts`) to manage your content:
+
+```ts
+import { createSource } from "docstra/server";
+import { docs } from "../.docstra"; // Generated at build time
+
+export const source = createSource(docs);
+```
+
+### 4. Component Mapping (Important!)
+
+Create `mdx-components.tsx` in your project root. This is critical for getting the default components (like code blocks) working correctly.
+
+```tsx
+import { defaultMdxComponents } from "docstra/server";
+import { DocstraCodeBlock } from "docstra";
+
+export function useMDXComponents() {
+    return {
+        ...defaultMdxComponents(),
+        pre: DocstraCodeBlock, // Manually map to avoid server/client bundle conflicts
+    };
+}
+```
+
+### 5. Create the Page
+
+Create your catch-all route at `app/docs/[[...slug]]/page.tsx`:
+
+```tsx
+import { source } from "@/lib/source";
+import { notFound } from "next/navigation";
+import { DocstraProvider, DocstraPage, DocstraBody, DocstraHeader } from "docstra";
+import { useMDXComponents } from "@/mdx-components";
+import config from "@/docstra.config";
+
+export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
+    const { slug } = await params;
+    
+    // 1. Get page data
+    const page = source.getPage(slug);
+    if (!page) return notFound();
+
+    // 2. Destructure info (safe JSON) and body (MDX Component)
+    const { info, body: MDX } = page;
+
+    // 3. Render
+    return (
+        <DocstraProvider docstraConfig={config} docs={source.files} pageData={info}>
+            <DocstraHeader />
+            <DocstraPage>
+                <DocstraBody>
+                    <MDX components={useMDXComponents()} />
+                </DocstraBody>
+            </DocstraPage>
+        </DocstraProvider>
+    );
+}
+
+// Generate static params for SSG
+export function generateStaticParams() {
+    return source.generateStaticParams();
+}
+
+// Generate metadata
+export async function generateMetadata({ params }: { params: Promise<{ slug?: string[] }> }) {
+    const { slug } = await params;
+    const page = source.getPage(slug);
+    if (!page) return notFound();
+    return {
+        title: page.info.data.metadata.title,
+        description: page.info.data.metadata.description,
+    };
+}
 ```
 
-> Created and maintained with 💙 by [SudhuCodes](https://github.com/sudhucodes)
+### 6. Build
+
+Update your `next.config.ts` or `with-docstra` setup (if applicable) and run:
+
+```bash
+npm run build
+```
+
+Docstra will generate the `.docstra/index.ts` file manifest, and your docs will be live!
+
+---
+
+## 🛠 Features
+
+- **MDX Support**: Write documentation in Markdown/MDX.
+- **Auto Sidebar/TOC**: `DocstraPage` automatically handles layouts.
+- **Search**: Built-in search (requires configuration).
+- **Code Highlighting**: Powered by Prism with copy support.
+- **Type Safe**: Full TypeScript support.

package/dist/client/index.d.mts

@@ -1,12 +1,13 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1 from 'react';
-import { D as DocstraConfig, p as pageDataContent, a as DocstraContextType } from '../types-BCr1htTq.mjs';
+import { D as DocstraConfig, p as pageDataContent, a as DocstraContextType } from '../types-QzxGYJU4.mjs';
 
-declare function DocstraProvider({ children, docstraConfig, docs, pageData }: {
+declare function DocstraProvider({ children, docstraConfig, docs, pageData: initialPageData, slug }: {
     children: React$1.ReactNode;
     docstraConfig: DocstraConfig;
     docs: pageDataContent[];
-    pageData: pageDataContent;
+    pageData?: pageDataContent;
+    slug?: string | string[];
 }): react_jsx_runtime.JSX.Element;
 declare function useDocstra(): DocstraContextType;
 
@@ -14,9 +15,12 @@ declare function DocstraHeader(): react_jsx_runtime.JSX.Element;
 
 declare function DocstraSidebar(): react_jsx_runtime.JSX.Element;
 
-declare function DocstraPage({ children }: {
+interface DocstraPageProps {
     children: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
+    toc?: boolean;
+    sidebar?: boolean;
+}
+declare function DocstraPage({ children, toc, sidebar }: DocstraPageProps): react_jsx_runtime.JSX.Element;
 
 interface Props {
     children: React.ReactNode;
@@ -27,4 +31,6 @@ declare function DocstraTOC(): react_jsx_runtime.JSX.Element;
 
 declare function DocstraCodeBlock(props: any): react_jsx_runtime.JSX.Element;
 
-export { DocstraBody, DocstraCodeBlock, DocstraHeader, DocstraPage, DocstraProvider, DocstraSidebar, DocstraTOC, useDocstra };
+declare function DocstraSearchBox(): react_jsx_runtime.JSX.Element;
+
+export { DocstraBody, DocstraCodeBlock, DocstraHeader, DocstraPage, DocstraProvider, DocstraSearchBox, DocstraSidebar, DocstraTOC, useDocstra };

package/dist/client/index.d.ts

@@ -1,12 +1,13 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1 from 'react';
-import { D as DocstraConfig, p as pageDataContent, a as DocstraContextType } from '../types-BCr1htTq.js';
+import { D as DocstraConfig, p as pageDataContent, a as DocstraContextType } from '../types-QzxGYJU4.js';
 
-declare function DocstraProvider({ children, docstraConfig, docs, pageData }: {
+declare function DocstraProvider({ children, docstraConfig, docs, pageData: initialPageData, slug }: {
     children: React$1.ReactNode;
     docstraConfig: DocstraConfig;
     docs: pageDataContent[];
-    pageData: pageDataContent;
+    pageData?: pageDataContent;
+    slug?: string | string[];
 }): react_jsx_runtime.JSX.Element;
 declare function useDocstra(): DocstraContextType;
 
@@ -14,9 +15,12 @@ declare function DocstraHeader(): react_jsx_runtime.JSX.Element;
 
 declare function DocstraSidebar(): react_jsx_runtime.JSX.Element;
 
-declare function DocstraPage({ children }: {
+interface DocstraPageProps {
     children: React.ReactNode;
-}): react_jsx_runtime.JSX.Element;
+    toc?: boolean;
+    sidebar?: boolean;
+}
+declare function DocstraPage({ children, toc, sidebar }: DocstraPageProps): react_jsx_runtime.JSX.Element;
 
 interface Props {
     children: React.ReactNode;
@@ -27,4 +31,6 @@ declare function DocstraTOC(): react_jsx_runtime.JSX.Element;
 
 declare function DocstraCodeBlock(props: any): react_jsx_runtime.JSX.Element;
 
-export { DocstraBody, DocstraCodeBlock, DocstraHeader, DocstraPage, DocstraProvider, DocstraSidebar, DocstraTOC, useDocstra };
+declare function DocstraSearchBox(): react_jsx_runtime.JSX.Element;
+
+export { DocstraBody, DocstraCodeBlock, DocstraHeader, DocstraPage, DocstraProvider, DocstraSearchBox, DocstraSidebar, DocstraTOC, useDocstra };