@ahmedrowaihi/8n 6.0.53 → 6.0.55

package/dist/index.mjs

@@ -10,6 +10,8 @@ import { createInterface } from "node:readline/promises";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { readFile, readdir } from "node:fs/promises";
+import { createOpenAPI } from "fumadocs-openapi/server";
+import { generateFiles } from "fumadocs-openapi";
 
 //#region node_modules/zod/v4/core/core.js
 /** A special constant with type `never` */
@@ -3736,7 +3738,7 @@ async function checkSelfUpdate() {
 		});
 		if (!res.ok) return;
 		const { version: latest } = await res.json();
-		const current = "6.0.53";
+		const current = "6.0.55";
 		if (latest !== current) console.log(pc.yellow("⚠") + pc.dim(` new version available: `) + pc.cyan(latest) + pc.dim(` (current: ${current}) — run `) + pc.cyan("npm i -g @ahmedrowaihi/8n") + pc.dim(" to update"));
 	} catch {}
 }
@@ -3849,7 +3851,7 @@ async function dev() {
 async function build({ server = false } = {}) {
 	const { config, contentDir } = await resolveProject();
 	const projectDir = process.cwd();
-	console.log(pc.cyan("8n") + pc.dim(` v6.0.53 build → ${contentDir}`));
+	console.log(pc.cyan("8n") + pc.dim(` v6.0.55 build → ${contentDir}`));
 	if (server) await runNextFlat(projectDir, "build", buildEnv({
 		config,
 		contentDir,
@@ -4167,7 +4169,7 @@ async function mcp() {
 	const mcpDir = join(getStarterDir(), "content", "mcp", "en");
 	const server = new McpServer({
 		name: "8n",
-		version: "6.0.53"
+		version: "6.0.55"
 	});
 	server.registerTool("read_me", {
 		description: "Returns how to use the 8n MCP tools. Call this BEFORE documenting anything with 8n.",
@@ -4306,9 +4308,24 @@ Example: get_component({ name: "components" }) returns all available MDX compone
 	await server.connect(transport);
 }
 
+//#endregion
+//#region src/commands/generate.ts
+async function generateApi({ input, output }) {
+	const { contentDir } = await resolveProject();
+	const projectDir = process.cwd();
+	const outputDir = join(contentDir, output);
+	console.log(pc.cyan("8n") + pc.dim(` generate:api → ${outputDir}`));
+	await generateFiles({
+		input: createOpenAPI({ input: [resolve(projectDir, input)] }),
+		output: outputDir,
+		includeDescription: true
+	});
+	console.log(pc.green("✓") + pc.dim(` API docs generated → ${outputDir}`));
+}
+
 //#endregion
 //#region src/index.ts
-const program = new Command().name("8n").description("Run your 8n docs site").version("6.0.53").addOption(new Option("--debug").hideHelp()).hook("preAction", (cmd) => {
+const program = new Command().name("8n").description("Run your 8n docs site").version("6.0.55").addOption(new Option("--debug").hideHelp()).hook("preAction", (cmd) => {
 	if (cmd.opts().debug) process.env.DEBUG_8N = "1";
 });
 program.command("init").description("Scaffold a new docs project in the current directory").action(init);
@@ -4318,6 +4335,7 @@ program.command("start").description("Start the production server").action(start
 program.command("eject").description("Unpack starter into the project root for CI/Vercel builds").action(eject);
 program.command("deploy <target>").description("Generate deployment config — targets: vercel, github").action(deploy);
 program.command("mcp").description("Start the MCP server for AI-assisted docs authoring").action(mcp);
+program.command("generate:api").description("Generate API docs from an OpenAPI spec into a content section").requiredOption("-i, --input <spec>", "Path to OpenAPI spec file (JSON or YAML)").option("-o, --output <section>", "Content section name to write into", "api").action(generateApi);
 program.parse();
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmedrowaihi/8n",
-  "version": "6.0.53",
+  "version": "6.0.55",
   "description": "8n docs — run your docs site from your content directory",
   "bin": {
     "8n": "./dist/index.mjs"
@@ -19,6 +19,7 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "c12": "^2.0.0",
     "commander": "^14.0.0",
+    "fumadocs-openapi": "^10.3.18",
     "jiti": "^2.0.0",
     "picocolors": "^1.1.0",
     "tinyexec": "^1.0.0"

package/starter/content/docs/01-getting-started.ar.mdx

@@ -56,20 +56,15 @@ icon: Rocket
 
 ## إضافة صفحة جديدة
 
-ضع ملف `.mdx` في `content/docs/ar/` (وفي `content/docs/en/` للنسخة الإنجليزية):
+ضع ملف `.mdx` في `content/docs/`. للترجمة، أضف ملفاً مجاوراً بلاحقة اللغة (مثل `.ar.mdx`):
 
 <Files>
   <Folder name="content/docs" defaultOpen>
-    <Folder name="ar" defaultOpen>
-      <File name="index.mdx" />
-      <File name="getting-started.mdx" />
-      <File name="صفحتك-الجديدة.mdx" />
-    </Folder>
-    <Folder name="en">
-      <File name="index.mdx" />
-      <File name="getting-started.mdx" />
-      <File name="your-new-page.mdx" />
-    </Folder>
+    <File name="index.mdx" />
+    <File name="getting-started.mdx" />
+    <File name="getting-started.ar.mdx" />
+    <File name="صفحتك-الجديدة.mdx" />
+    <File name="your-new-page.ar.mdx" />
   </Folder>
 </Files>
 
@@ -99,7 +94,7 @@ icon: Rocket
   <Step>
     ### أنشئ مجلد المحتوى
 
-    أنشئ مجلد <code>{'content/docs/fr/'}</code> وضع فيه ملفات <code>.mdx</code> المترجمة.
+    أضف ملفاتك المترجمة كـ `.fr.mdx` مجاورة للملفات الإنجليزية (مثل `getting-started.fr.mdx`).
 
   </Step>
 </Steps>

package/starter/content/docs/01-getting-started.mdx

@@ -58,20 +58,15 @@ icon: Rocket
 
 ## Adding a new page
 
-Drop an `.mdx` file into `content/docs/en/` (and `content/docs/ar/` for the Arabic version):
+Drop an `.mdx` file into `content/docs/`. For translations, add a sibling file with the locale suffix (e.g. `.ar.mdx`):
 
 <Files>
   <Folder name="content/docs" defaultOpen>
-    <Folder name="en" defaultOpen>
-      <File name="index.mdx" />
-      <File name="getting-started.mdx" />
-      <File name="your-new-page.mdx" />
-    </Folder>
-    <Folder name="ar">
-      <File name="index.mdx" />
-      <File name="getting-started.mdx" />
-      <File name="your-new-page.mdx" />
-    </Folder>
+    <File name="index.mdx" />
+    <File name="getting-started.mdx" />
+    <File name="getting-started.ar.mdx" />
+    <File name="your-new-page.mdx" />
+    <File name="your-new-page.ar.mdx" />
   </Folder>
 </Files>
 
@@ -101,7 +96,7 @@ Drop an `.mdx` file into `content/docs/en/` (and `content/docs/ar/` for the Arab
   <Step>
     ### Create the content folder
 
-    Create `content/docs/fr/` and add your translated `.mdx` files.
+    Add your translated files as `.fr.mdx` siblings next to the English files (e.g. `getting-started.fr.mdx`).
 
   </Step>
 </Steps>

package/starter/content/mcp/02-structure.mdx

@@ -1,55 +1,84 @@
 ---
 title: Content Structure
-description: LLM reference — how to organise your content directory, locale folders, and meta.json files.
+description: LLM reference — how to organise your content directory using dot-suffix i18n.
 ---
 
 ```
 content/
-  docs/                    ← main documentation section
-    en/                    ← locale folder (must match a locale in config.locales)
-      meta.json            ← sidebar order and optional section title
-      index.mdx            ← section landing page
-      getting-started.mdx
-      guide/               ← sub-folder creates a nested sidebar group
-        meta.json
-        installation.mdx
-        configuration.mdx
-    ar/                    ← Arabic locale (optional)
-      index.mdx
-      getting-started.mdx
-  api/                     ← API reference section (optional)
-    en/
-      meta.json
-      overview.mdx
-  ui/                      ← UI component showcase (optional)
-    en/
-      meta.json
-      index.mdx
-  changelog/               ← versioned changelog (auto-sorted newest first)
-    en/
-      v2.0.0.mdx
-      v1.0.0.mdx
-  home/                    ← custom landing page (optional, replaces default)
-    en/
-      index.mdx
-```
-
-## meta.json
-
-Controls sidebar ordering and the group title for a folder.
-
-```json
-{
-  "title": "Getting Started",
-  "pages": ["installation", "configuration"]
-}
-```
-
-- `title` — optional label for the sidebar group
-- `pages` — explicit page order; omit a filename to hide that page from the sidebar
-
-If `meta.json` is absent, pages appear in filesystem order.
-
-## Fallback behaviour
-
-If a page exists in `en/` but not in `ar/`, the site automatically falls back to the English version for Arabic visitors.
+  docs/                      ← main documentation section
+    index.mdx                ← section landing page + sidebar title (default locale)
+    index.ar.mdx             ← Arabic translation of the landing page (optional)
+    01-getting-started.mdx   ← numeric prefix controls sidebar order
+    01-getting-started.ar.mdx
+    components/              ← sub-folder creates a nested sidebar group
+      index.mdx              ← group title and optional landing page
+      index.ar.mdx
+      callout.mdx
+      callout.ar.mdx
+  api/                       ← API reference (usually generated via `8n generate:api`)
+    index.mdx                ← optional: section landing page
+    listPets.mdx             ← generated endpoint page
+    showPetById.mdx
+  ui/                        ← UI component showcase (optional)
+    index.mdx
+    badge.mdx
+  changelog/                 ← versioned changelog, sorted newest-first
+    index.mdx
+    v2.0.0.mdx
+    v1.0.0.mdx
+  home/                      ← custom landing page (optional, replaces default)
+    index.mdx
+```
+
+## i18n: dot-suffix
+
+Translations live alongside originals as `.{locale}.mdx` siblings — no locale folders needed.
+
+```
+getting-started.mdx       ← default locale (first entry in config.locales)
+getting-started.ar.mdx    ← Arabic translation
+```
+
+If a translation is missing, the site falls back to the default locale automatically.
+
+For a single-locale site, just add plain `.mdx` files with no suffix — no configuration needed.
+
+## Numeric prefix ordering
+
+Prefix filenames with `{n}-` to control sidebar order. The prefix is stripped from the URL slug.
+
+```
+01-getting-started.mdx  → slug: getting-started, position: 1
+02-configuration.mdx    → slug: configuration, position: 2
+```
+
+## index.mdx
+
+`index.mdx` at any directory level sets the title, icon, and optional landing page for that section or folder.
+
+```mdx
+---
+label: Getting Started   # sidebar/nav label (falls back to title if omitted)
+title: Introduction      # page <title> when the page has body content
+icon: Rocket             # Lucide icon shown in the sidebar
+---
+
+Body content here makes this a real page.
+Omit the body to use it as metadata-only (the section root redirects to the first child).
+```
+
+## Adding a new section
+
+Create a directory under `content/` — it auto-appears in the sidebar and navigation.
+
+```bash
+mkdir content/guides
+# add content/guides/index.mdx with label: Guides
+# add content/guides/01-quickstart.mdx
+```
+
+Remove it by deleting the directory, or hide it without deleting:
+
+```ts title="8n.config.ts"
+sections: { guides: false }
+```

package/starter/content/mcp/03-frontmatter.mdx

@@ -9,32 +9,47 @@ Every `.mdx` file starts with a YAML frontmatter block between `---` delimiters.
 
 ```mdx
 ---
-title: My Page # required — used as the sidebar label and <title>
-description: Short blurb # optional — shown below the heading and in <meta description>
-icon: Rocket # optional — Lucide icon name shown in the sidebar
-full: true # optional — removes the sidebar and TOC for a full-width layout
-redirect: /en/docs/other # optional — immediately redirects to another URL
+title: My Page        # required — used as the page <title>
+label: Short Name     # optional — sidebar/nav label; falls back to title
+description: Blurb    # optional — shown below the heading and in <meta description>
+icon: Rocket          # optional — Lucide icon name shown in the sidebar
+full: true            # optional — removes the sidebar and TOC for a full-width layout
+redirect: /en/docs/other  # optional — immediately redirects to another URL
 ---
 ```
 
+## index.mdx (section or folder root)
+
+```mdx
+---
+label: My Section     # sidebar/nav label for the section or folder
+title: Introduction   # page <title> if the file has body content
+icon: BookOpen        # Lucide icon shown next to the section name
+---
+
+Optional body — makes this file a real landing page.
+Omit the body to treat it as metadata-only; the section root will redirect to the first child page.
+```
+
 ## Changelog pages
 
 ```mdx
 ---
 title: Version 2.1.0
-version: 2.1.0 # semver string — used for sorting
-date: "2025-06-01" # ISO 8601 date
-summary: What changed. # one-liner shown in the changelog list view
+version: 2.1.0        # semver string — used for sorting
+date: "2025-06-01"    # ISO 8601 date (quoted to prevent YAML date parsing)
+summary: What changed.  # one-liner shown in the changelog list view
 ---
 ```
 
-## Home page (`home/[lang]/index.mdx`)
+## Home page (`home/index.mdx`)
 
 Free-form MDX — no required fields. All components and Tailwind utility classes are available.
-You can use frontmatter for `title` and `description` if you want them in `<meta>` tags.
+Use `title` and `description` frontmatter if you want them in `<meta>` tags.
 
 ## Notes
 
 - `title` is the only truly required field on docs/api/ui pages.
+- `label` lets you have a short sidebar name while keeping a longer `title` in the page heading.
 - All string values should be unquoted unless they contain special YAML characters (`:`, `#`, etc.).
 - `icon` accepts any name from the [Lucide icon set](https://lucide.dev/icons/).

package/starter/content/mcp/04-components.mdx

@@ -84,9 +84,10 @@ Annotated file tree diagram.
 ```mdx
 <Files>
   <Folder name="content" defaultOpen>
-    <Folder name="docs/en" defaultOpen>
+    <Folder name="docs" defaultOpen>
       <File name="index.mdx" />
       <File name="getting-started.mdx" />
+      <File name="getting-started.ar.mdx" />
     </Folder>
   </Folder>
 </Files>

package/starter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmedrowaihi/8n-starter",
-  "version": "6.0.53",
+  "version": "6.0.55",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -10,7 +10,6 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "generate:api": "tsx scripts/generate-docs.mts",
     "types:check": "tsc --noEmit",
     "lint": "oxlint",
     "format": "oxfmt",

package/starter/scripts/generate-docs.mts

@@ -1,8 +0,0 @@
-import { generateFiles } from "fumadocs-openapi";
-import { openapi } from "../src/lib/openapi";
-
-void generateFiles({
-  input: openapi,
-  output: "./content/api/en",
-  includeDescription: true,
-});