docstra 1.7.6 → 1.7.9

package/README.md

@@ -1,11 +1,21 @@
-# Docstra
+# **Docstra**
 
 **The Modern Documentation Framework for Next.js**
 
-Docstra is a powerful and easy-to-use documentation framework built for Next.js App Router. It provides a beautiful default theme, MDX support and flexible components to build your documentation site in minutes.
+Docstra is a fast, flexible, and beautifully designed documentation framework built specifically for the **Next.js App Router**.
+With first-class **MDX support**, a clean UI, and powerful components, you can build production-ready documentation sites in just minutes.
 
 ---
 
-See Our [Website](https://docstra.sudhucodes.com) for more documentation.
+### **Documentation & Guide**
 
-Thanks for using Docstra! Happy Documentation :)
+Visit the official website for full guides, examples and API references:
+
+👉 **[https://docstra.sudhucodes.com](https://docstra.sudhucodes.com)**
+
+---
+
+### **Thank You**
+
+Thanks for choosing Docstra!
+Happy documenting — and build something great.

package/cli/commands/init.js

@@ -0,0 +1,149 @@
+const path = require("path");
+const fs = require("fs");
+const { safeWrite, createFolder } = require("../utils/fs");
+const {
+    DOCSTRA_CONFIG,
+    MDX_COMPONENTS,
+    NEXT_CONFIG,
+    INDEX_MDX,
+    PAGE_TSX,
+    SOURCE_TS
+} = require("../templates");
+
+function initDocstra() {
+    console.log("\n🔧 Initializing Docstra...\n");
+
+    const root = process.cwd();
+
+    // 1. Create structure
+    createFolder(path.join(root, "app"));
+
+    // 2. Create docs content
+    const contentDir = path.join(root, "app", "docs", "content");
+    const slugDir = path.join(root, "app", "docs", "[[...slug]]");
+
+    createFolder(contentDir);
+    createFolder(slugDir);
+
+    safeWrite(path.join(contentDir, "index.mdx"), INDEX_MDX);
+    safeWrite(path.join(slugDir, "page.tsx"), PAGE_TSX);
+
+    // 3. Create lib/source.ts
+    const libDir = path.join(root, "lib");
+    createFolder(libDir);
+    safeWrite(path.join(libDir, "source.ts"), SOURCE_TS);
+
+    // 4. Config files
+    safeWrite(path.join(root, "mdx-components.tsx"), MDX_COMPONENTS);
+    safeWrite(path.join(root, "docstra.config.ts"), DOCSTRA_CONFIG);
+
+    // 5. Update next.config
+    updateNextConfig(root);
+
+    // 6. Check/Update Tailwind
+    updateTailwindGlobals(root);
+
+    // 7. Instructions
+    console.log(`
+Please install latest version of Docstra by running:
+
+Package Manager | Command
+npm | npm install docstra@latest
+yarn | yarn add docstra@latest
+pnpm | pnpm add docstra@latest
+`);
+
+    console.log("\n🎉 Docstra initialized successfully!\n");
+}
+
+function updateNextConfig(root) {
+    const tsPath = path.join(root, "next.config.ts");
+    const jsPath = path.join(root, "next.config.js");
+
+    let nextConfigPath = fs.existsSync(tsPath) ? tsPath :
+        fs.existsSync(jsPath) ? jsPath :
+            null;
+
+    if (!nextConfigPath) {
+        // Create new if none exists
+        safeWrite(tsPath, NEXT_CONFIG);
+        return;
+    }
+
+    let content = fs.readFileSync(nextConfigPath, "utf8");
+
+    if (content.includes("withDocstra")) {
+        console.log("✔ next.config already uses withDocstra");
+        return;
+    }
+
+    if (!content.includes("withDocstra")) {
+        content = `import { withDocstra } from "docstra/server";\n` + content;
+    }
+
+    const exportRegex = /export\s+default\s+(.+);?/;
+    const match = content.match(exportRegex);
+
+    if (!match) {
+        console.log("⚠ Could not detect export default. Skipped patch.");
+        return;
+    }
+
+    let exportValue = match[1].trim();
+    if (exportValue.endsWith(";")) {
+        exportValue = exportValue.slice(0, -1).trim();
+    }
+
+    const wrapped = `export default withDocstra(${exportValue});`;
+    content = content.replace(exportRegex, wrapped);
+
+    fs.writeFileSync(nextConfigPath, content);
+    console.log("✔ Updated next.config with withDocstra()");
+}
+
+
+function updateTailwindGlobals(root) {
+    const globalsPath = path.join(root, "app", "globals.css");
+
+    if (!fs.existsSync(globalsPath)) {
+        console.log("❌ app/globals.css not found.");
+        console.log("Please ensure Tailwind is installed correctly before running Docstra init.");
+        return;
+    }
+
+    let css = fs.readFileSync(globalsPath, "utf8");
+
+    // Simple check for tailwind import/usage would go here if needed, 
+    // but we'll focus on injecting our styles.
+
+    if (css.includes('@import "docstra/css";')) {
+        console.log("✔ docstra/css already imported in globals.css");
+        return;
+    }
+
+    // Try to find where to insert
+    const tailwindRegex = /@import ['"]tailwindcss[^'"]*['"];?/g;
+    let lastMatch = null, match;
+    while ((match = tailwindRegex.exec(css)) !== null) {
+        lastMatch = match;
+    }
+
+    if (lastMatch) {
+        const insertPos = lastMatch.index + lastMatch[0].length;
+        const updatedCSS = css.slice(0, insertPos) + `\n@import "docstra/css";\n` + css.slice(insertPos);
+        fs.writeFileSync(globalsPath, updatedCSS, "utf8");
+        console.log("✔ Injected @import \"docstra/css\" into app/globals.css");
+    } else {
+        // If no explicit tailwind import found (e.g. using @tailwind directives or v4), just append or warn?
+        // For now, let's just append appropriately or warn.
+        // The original code warned if no tailwind imports were found.
+        // Let's keep it simple:
+        console.log(`
+⚠ Tailwind imports not detected (or using different format).
+Add manually:
+  @import "docstra/css";
+`);
+    }
+}
+
+module.exports = { initDocstra };

package/cli/index.js

@@ -1,25 +1,21 @@
 #!/usr/bin/env node
 
-const package = require("../package.json");
-const command = process.argv[2];
+const pkg = require("../package.json");
+const { initDocstra } = require("./commands/init");
 
-if (command === "init") {
-    console.log(`
-Docstra CLI ${package.version}
-${package.description}
+// --- CLI ENTRY ---
+const command = process.argv[2];
 
-Thank you for trying the Docstra CLI.
-We are actively working on the \`init\` command and it will be
-available in an upcoming release.
+switch (command) {
+  case "init":
+    initDocstra();
+    break;
 
-Stay tuned!
-`);
-} else {
+  default:
     console.log(`
-Usage:
-  docstra init
+Docstra CLI ${pkg.version}
 
-Description:
-  Initializes Docstra in your project (coming soon).
+Usage:
+  docstra init     Initialize Docstra in your project
 `);
 }

package/cli/templates/docstra-config.js

@@ -0,0 +1,53 @@
+module.exports = `import { defineDocstraConfig } from "docstra/config";
+
+export default defineDocstraConfig({
+    siteName: "Docstra",
+    githubRepo: "https://github.com/sudhucodes/docstra",
+    contentDir: "app/docs/content",
+    editOnGithub: {
+        owner: "sudhucodes",
+        repo: "docstra",
+        path: "docs/content",
+    },
+    feedback: {
+        enabled: true,
+        formSyncFormID: "69c728a1-ccd2-4dab-a9f7-bb52baeb4d31",
+    },
+    navbar: {
+        logo: {
+            link: "/",
+            src: "/brand/logo.svg",
+            alt: "Logo",
+            className: "h-8 w-auto",
+        },
+        links: [
+            { name: "Guides", href: "/docs/guides" },
+            { name: "Examples", href: "/docs/examples" },
+        ],
+    },
+    sidebar: {
+        links: [
+            {
+                section: 'Section 1',
+                items: [
+                    {
+                        name: 'Docs',
+                        href: '/docs',
+                        icon: '<Any-Lucide-Icon>'
+                    },
+                    {
+                        name: 'Link 2',
+                        href: '/docs/link-2',
+                    },
+                ],
+            },
+            {
+                section: 'Section 2',
+                items: [
+                    { name: 'Link 3', href: '/docs/link-3' },
+                ],
+            },
+        ],
+    },
+});
+`;

package/cli/templates/index.js

@@ -0,0 +1,11 @@
+const docstraConfig = require("./docstra-config");
+const mdxComponents = require("./mdx-components");
+const nextConfig = require("./next-config");
+const pages = require("./pages");
+
+module.exports = {
+    DOCSTRA_CONFIG: docstraConfig,
+    MDX_COMPONENTS: mdxComponents,
+    NEXT_CONFIG: nextConfig,
+    ...pages,
+};

package/cli/templates/mdx-components.js

@@ -0,0 +1,8 @@
+module.exports = `import { defaultMdxComponents } from "docstra/server";
+import { DocstraCodeBlock } from "docstra";
+
+export const mdxComponents = {
+    ...defaultMdxComponents,
+    code: DocstraCodeBlock
+};
+`;

package/cli/templates/next-config.js

@@ -0,0 +1,7 @@
+module.exports = `import type { NextConfig } from "next";
+import { withDocstra } from "docstra/server";
+
+const nextConfig: NextConfig = {};
+
+export default withDocstra(nextConfig);
+`;

package/cli/templates/pages.js

@@ -0,0 +1,63 @@
+exports.INDEX_MDX = `# Welcome to Docstra
+
+Your documentation starts inside \`app/docs\`!
+
+Start editing this file or add more MDX pages.
+
+## Tips
+- Pages in \`app/docs/content\` render automatically.
+- \`[[...slug]]\` handles dynamic routing.
+`;
+
+exports.PAGE_TSX = `import docstraConfig from "@/docstra.config";
+import { mdxComponents } from "@/mdx-components";
+import {
+    DocstraBody,
+    DocstraHeader,
+    DocstraPage,
+    DocstraProvider,
+} from "docstra";
+
+import { source } from "@/lib/source";
+import { notFound } from "next/navigation";
+
+export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
+    const { slug } = await params
+    const page = source.getPage(slug);
+    if (!page) return notFound();
+
+    const MDX = page.body;
+
+    return (
+        <DocstraProvider docstraConfig={docstraConfig} docs={source.files} pageData={page.info}>
+            <DocstraHeader />
+            <DocstraPage>
+                <DocstraBody>
+                    <MDX components={mdxComponents} />
+                </DocstraBody>
+            </DocstraPage>
+        </DocstraProvider>
+    );
+}
+
+export function generateStaticParams() {
+    return source.generateStaticParams();
+}
+
+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,
+    }
+}
+`;
+
+exports.SOURCE_TS = `import { docs } from "@/.docstra/index";
+import { createSource } from "docstra/server";
+
+export const source = createSource(docs);
+`;

package/cli/utils/fs.js

@@ -0,0 +1,31 @@
+const fs = require("fs");
+const path = require("path");
+
+function safeWrite(filePath, content) {
+    if (!fs.existsSync(filePath)) {
+        // Ensure directory exists
+        const dir = path.dirname(filePath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+
+        fs.writeFileSync(filePath, content);
+        console.log(`✔ Created ${filePath.replace(process.cwd() + path.sep, "")}`);
+    } else {
+        console.log(`✔ Already exists: ${filePath.replace(process.cwd() + path.sep, "")}`);
+    }
+}
+
+function createFolder(folderPath) {
+    if (!fs.existsSync(folderPath)) {
+        fs.mkdirSync(folderPath, { recursive: true });
+        console.log(`✔ Created /${path.relative(process.cwd(), folderPath).replace(/\\/g, "/")}`);
+    } else {
+        console.log(`✔ /${path.relative(process.cwd(), folderPath).replace(/\\/g, "/")} already exists`);
+    }
+}
+
+module.exports = {
+    safeWrite,
+    createFolder
+};

package/dist/server/index.js

@@ -1836,7 +1836,6 @@ export const docs = [
 ];
 `;
   import_fs.default.writeFileSync(outFile, finalOutput, "utf8");
-  logger.success(`MDX content compiled successfully`);
 }
 function getAllMdxFiles(dir) {
   return import_fs.default.readdirSync(dir).flatMap((file) => {
@@ -1869,18 +1868,16 @@ async function runDocstraDev(contentDir) {
     ignored: ["node_modules", ".next"]
   });
   watcher.add([contentDir, configFile]);
-  watcher.on("ready", () => {
-    logger.info("Watching for changes...");
-  });
+  logger.info(`Dev server started...`);
   watcher.on("all", async (_, file) => {
     if (!file.endsWith(".md") && !file.endsWith(".mdx") && !file.endsWith("docstra.config.ts")) {
       return;
     }
     if (rebuildTimeout) clearTimeout(rebuildTimeout);
     rebuildTimeout = setTimeout(async () => {
-      logger.info(`Rebuilding...`);
       await runDocstraBuild(contentDir);
     }, 200);
+    logger.info(`MDX content rebuilt successfully`);
   });
   process.on("exit", () => {
     if (!watcher.closed) {
@@ -1930,6 +1927,7 @@ function withDocstra(nextConfig = {}) {
     }
     if (isBuild) {
       runDocstraBuild(contentDir);
+      logger.info(`MDX content generated successfully`);
     }
   }
   const turbopack = {