#!/usr/bin/env node /** * Generates Mintlify-compatible MDX files from a GraphQL introspection schema JSON. * * Usage: node generate-mdx.js [--schema ] [--out ] * * Defaults: * --schema ./graphql/schema.json * --out ./mdx-docs */ const fs = require("fs"); const path = require("path"); // --------------------------------------------------------------------------- // CLI args // --------------------------------------------------------------------------- const args = process.argv.slice(2); function flag(name, fallback) { const idx = args.indexOf(name); return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback; } const SCHEMA_PATH = path.resolve(flag("--schema", "./graphql/schema.json")); const OUT_DIR = path.resolve(flag("--out", "./mdx-docs")); // --------------------------------------------------------------------------- // Load schema // --------------------------------------------------------------------------- const raw = JSON.parse(fs.readFileSync(SCHEMA_PATH, "utf-8")); const schema = raw.data ? raw.data.__schema : raw.__schema || raw; const typeMap = {}; for (const t of schema.types) { typeMap[t.name] = t; } // --------------------------------------------------------------------------- // Helpers // --------------------------------------------------------------------------- const BUILTIN = new Set([ "String", "Int", "Float", "Boolean", "ID", "__Schema", "__Type", "__Field", "__InputValue", "__EnumValue", "__Directive", "__TypeKind", "__DirectiveLocation", ]); function isInternal(name) { return name.startsWith("__"); } function slugify(name) { return name .replace(/([a-z])([A-Z])/g, "$1-$2") .replace(/_/g, "-") .toLowerCase(); } function resolveType(typeObj) { if (!typeObj) return { name: "unknown", wrapper: "" }; if (typeObj.kind === "NON_NULL") { const inner = resolveType(typeObj.ofType); return { ...inner, wrapper: inner.wrapper + "!" }; } if (typeObj.kind === "LIST") { const inner = resolveType(typeObj.ofType); return { ...inner, wrapper: "[" + inner.wrapper + "]" }; } return { name: typeObj.name || "unknown", kind: typeObj.kind, wrapper: "" }; } function formatType(typeObj) { const r = resolveType(typeObj); const base = r.name; if (r.wrapper.includes("[")) { return `[${base}${r.wrapper.replace("[", "").replace("]", "")}]`; } return `${base}${r.wrapper}`; } function typeLink(typeObj, basePath) { const r = resolveType(typeObj); const t = typeMap[r.name]; if (!t || BUILTIN.has(r.name) || isInternal(r.name)) return `\`${formatType(typeObj)}\``; const dir = kindToDir(t.kind); const slug = slugify(r.name); const display = formatType(typeObj); return `[\`${display}\`](/${basePath}/${dir}/${slug})`; } function kindToDir(kind) { const map = { OBJECT: "objects", INPUT_OBJECT: "inputs", ENUM: "enums", INTERFACE: "interfaces", UNION: "unions", SCALAR: "scalars", }; return map[kind] || "types"; } function escapeDescription(desc) { if (!desc) return ""; return desc .replace(//g, ">") .replace(/\{/g, "\\{") .replace(/\}/g, "\\}"); } function mkdirp(dir) { fs.mkdirSync(dir, { recursive: true }); } function writeMdx(filePath, content) { mkdirp(path.dirname(filePath)); fs.writeFileSync(filePath, content, "utf-8"); } // Category labels const CATEGORY_LABELS = { objects: "Objects", inputs: "Input types", enums: "Enums", interfaces: "Interfaces", unions: "Unions", scalars: "Scalars", }; // --------------------------------------------------------------------------- // MDX content builders // --------------------------------------------------------------------------- const BASE = "GraphQL_test/mdx-docs"; function buildFieldsTable(fields, basePath) { if (!fields || fields.length === 0) return ""; let md = "| Name | Type | Description |\n"; md += "| ---- | ---- | ----------- |\n"; for (const f of fields) { const deprecated = f.isDeprecated ? " *(deprecated)* " : ""; const desc = escapeDescription(f.description || ""); const depReason = f.isDeprecated && f.deprecationReason ? ` **Deprecated:** ${escapeDescription(f.deprecationReason)}` : ""; md += `| \`${f.name}\` | ${typeLink(f.type, basePath)} | ${desc}${deprecated}${depReason} |\n`; } return md; } function buildInputFieldsTable(fields, basePath) { if (!fields || fields.length === 0) return ""; let md = "| Name | Type | Description |\n"; md += "| ---- | ---- | ----------- |\n"; for (const f of fields) { const desc = escapeDescription(f.description || ""); const defVal = f.defaultValue != null ? ` Default: \`${f.defaultValue}\`` : ""; md += `| \`${f.name}\` | ${typeLink(f.type, basePath)} | ${desc}${defVal} |\n`; } return md; } function buildArgsTable(args, basePath) { if (!args || args.length === 0) return ""; let md = "| Argument | Type | Description |\n"; md += "| -------- | ---- | ----------- |\n"; for (const a of args) { const desc = escapeDescription(a.description || ""); const defVal = a.defaultValue != null ? ` Default: \`${a.defaultValue}\`` : ""; md += `| \`${a.name}\` | ${typeLink(a.type, basePath)} | ${desc}${defVal} |\n`; } return md; } function buildEnumTable(values) { if (!values || values.length === 0) return ""; let md = "| Value | Description |\n"; md += "| ----- | ----------- |\n"; for (const v of values) { const deprecated = v.isDeprecated ? " *(deprecated)* " : ""; const desc = escapeDescription(v.description || ""); const depReason = v.isDeprecated && v.deprecationReason ? ` **Deprecated:** ${escapeDescription(v.deprecationReason)}` : ""; md += `| \`${v.name}\` | ${desc}${deprecated}${depReason} |\n`; } return md; } // --------------------------------------------------------------------------- // Page generators // --------------------------------------------------------------------------- function generateObjectPage(type) { const slug = slugify(type.name); const desc = escapeDescription(type.description || ""); const interfaces = type.interfaces && type.interfaces.length > 0 ? `\n**Implements:** ${type.interfaces.map((i) => typeLink({ kind: "INTERFACE", name: i.name }, BASE)).join(", ")}\n` : ""; // Separate fields with args (like sub-queries) const simpleFields = []; const fieldsWithArgs = []; for (const f of type.fields || []) { if (f.args && f.args.length > 0) { fieldsWithArgs.push(f); } else { simpleFields.push(f); } } let content = `--- title: "${type.name}" description: "${(type.description || "").split("\n")[0].replace(/"/g, '\\"')}" --- ${desc ? `${desc}\n` : ""}${interfaces} ## Fields ${buildFieldsTable(simpleFields, BASE)}`; if (fieldsWithArgs.length > 0) { content += `\n## Fields with arguments\n`; for (const f of fieldsWithArgs) { const fDesc = escapeDescription(f.description || ""); content += `\n### \`${f.name}\`\n\n${fDesc}\n\n`; content += `**Type:** ${typeLink(f.type, BASE)}\n\n`; content += buildArgsTable(f.args, BASE); } } return { slug, content }; } function generateInputPage(type) { const slug = slugify(type.name); const desc = escapeDescription(type.description || ""); const content = `--- title: "${type.name}" description: "${(type.description || "").split("\n")[0].replace(/"/g, '\\"')}" --- ${desc ? `${desc}\n` : ""} ## Input fields ${buildInputFieldsTable(type.inputFields, BASE)}`; return { slug, content }; } function generateEnumPage(type) { const slug = slugify(type.name); const desc = escapeDescription(type.description || ""); const content = `--- title: "${type.name}" description: "${(type.description || "").split("\n")[0].replace(/"/g, '\\"')}" --- ${desc ? `${desc}\n` : ""} ## Values ${buildEnumTable(type.enumValues)}`; return { slug, content }; } function generateInterfacePage(type) { const slug = slugify(type.name); const desc = escapeDescription(type.description || ""); const implementations = type.possibleTypes && type.possibleTypes.length > 0 ? `\n**Implemented by:** ${type.possibleTypes.map((t) => typeLink({ kind: "OBJECT", name: t.name }, BASE)).join(", ")}\n` : ""; const content = `--- title: "${type.name}" description: "${(type.description || "").split("\n")[0].replace(/"/g, '\\"')}" --- ${desc ? `${desc}\n` : ""}${implementations} ## Fields ${buildFieldsTable(type.fields, BASE)}`; return { slug, content }; } function generateUnionPage(type) { const slug = slugify(type.name); const desc = escapeDescription(type.description || ""); const members = type.possibleTypes && type.possibleTypes.length > 0 ? type.possibleTypes.map((t) => `- ${typeLink({ kind: "OBJECT", name: t.name }, BASE)}`).join("\n") : ""; const content = `--- title: "${type.name}" description: "${(type.description || "").split("\n")[0].replace(/"/g, '\\"')}" --- ${desc ? `${desc}\n` : ""} ## Possible types ${members} `; return { slug, content }; } function generateScalarPage(type) { const slug = slugify(type.name); const desc = escapeDescription(type.description || ""); const content = `--- title: "${type.name}" description: "${(type.description || "").split("\n")[0].replace(/"/g, '\\"')}" --- ${desc ? `${desc}\n` : ""}`; return { slug, content }; } function generateQueryPage(field) { const slug = slugify(field.name); const desc = escapeDescription(field.description || ""); let content = `--- title: "${field.name}" description: "${(field.description || "").split("\n")[0].replace(/"/g, '\\"')}" --- ${desc ? `${desc}\n` : ""} **Return type:** ${typeLink(field.type, BASE)} \`\`\`graphql query { ${field.name}${field.args && field.args.length > 0 ? `(${field.args.map((a) => `${a.name}: ${formatType(a.type)}`).join(", ")})` : ""} { ... } } \`\`\` `; if (field.args && field.args.length > 0) { content += `\n## Arguments\n\n${buildArgsTable(field.args, BASE)}`; } return { slug, content }; } function generateMutationPage(field) { const slug = slugify(field.name); const desc = escapeDescription(field.description || ""); const deprecated = field.isDeprecated ? `\n**Deprecated:** ${escapeDescription(field.deprecationReason || "This mutation is deprecated.")}\n` : ""; let content = `--- title: "${field.name}" description: "${(field.description || "").split("\n")[0].replace(/"/g, '\\"')}" --- ${deprecated}${desc ? `${desc}\n` : ""} **Return type:** ${typeLink(field.type, BASE)} \`\`\`graphql mutation { ${field.name}${field.args && field.args.length > 0 ? `(${field.args.map((a) => `${a.name}: ${formatType(a.type)}`).join(", ")})` : ""} { ok } } \`\`\` `; if (field.args && field.args.length > 0) { content += `\n## Arguments\n\n${buildArgsTable(field.args, BASE)}`; } return { slug, content }; } // --------------------------------------------------------------------------- // Generate index page // --------------------------------------------------------------------------- function generateIndexPage(queries, mutations) { let content = `--- title: "GraphQL API Reference" description: "Complete reference for the GraphQL API schema" --- ## Overview This section contains auto-generated documentation for the GraphQL API schema. Read operations for fetching data Write operations for modifying data ## Types Object types Input types Enumeration types Interface types Union types Scalar types `; return content; } function generateCategoryIndex(category, label, items) { let content = `--- title: "${label}" description: "All ${label.toLowerCase()} in the GraphQL schema" --- | Name | Description | | ---- | ----------- | `; for (const item of items) { const name = item.name || item; const desc = (item.description || "").split("\n")[0].replace(/"/g, '\\"'); const slug = slugify(name); content += `| [\`${name}\`](/${BASE}/${category}/${slug}) | ${escapeDescription(desc)} |\n`; } return content; } // --------------------------------------------------------------------------- // Main // --------------------------------------------------------------------------- function main() { console.log(`Reading schema from ${SCHEMA_PATH}`); console.log(`Output directory: ${OUT_DIR}`); // Categorise types const objects = []; const inputs = []; const enums = []; const interfaces = []; const unions = []; const scalars = []; for (const type of schema.types) { if (isInternal(type.name)) continue; if (type.name === "Query" || type.name === "Mutation") continue; switch (type.kind) { case "OBJECT": objects.push(type); break; case "INPUT_OBJECT": inputs.push(type); break; case "ENUM": enums.push(type); break; case "INTERFACE": interfaces.push(type); break; case "UNION": unions.push(type); break; case "SCALAR": if (!BUILTIN.has(type.name)) scalars.push(type); break; } } const queryType = typeMap[schema.queryType?.name]; const mutationType = typeMap[schema.mutationType?.name]; const queries = queryType?.fields || []; const mutations = mutationType?.fields || []; // Track generated pages for docs.json navigation const nav = { queries: [], mutations: [], objects: [], inputs: [], enums: [], interfaces: [], unions: [], scalars: [], }; // Index page writeMdx(path.join(OUT_DIR, "index.mdx"), generateIndexPage(queries, mutations)); // Queries for (const q of queries) { const { slug, content } = generateQueryPage(q); writeMdx(path.join(OUT_DIR, "queries", `${slug}.mdx`), content); nav.queries.push(`${BASE}/queries/${slug}`); } writeMdx(path.join(OUT_DIR, "queries", "index.mdx"), generateCategoryIndex("queries", "Queries", queries)); // Mutations for (const m of mutations) { const { slug, content } = generateMutationPage(m); writeMdx(path.join(OUT_DIR, "mutations", `${slug}.mdx`), content); nav.mutations.push(`${BASE}/mutations/${slug}`); } writeMdx(path.join(OUT_DIR, "mutations", "index.mdx"), generateCategoryIndex("mutations", "Mutations", mutations)); // Objects for (const t of objects) { const { slug, content } = generateObjectPage(t); writeMdx(path.join(OUT_DIR, "objects", `${slug}.mdx`), content); nav.objects.push(`${BASE}/objects/${slug}`); } writeMdx(path.join(OUT_DIR, "objects", "index.mdx"), generateCategoryIndex("objects", "Objects", objects)); // Inputs for (const t of inputs) { const { slug, content } = generateInputPage(t); writeMdx(path.join(OUT_DIR, "inputs", `${slug}.mdx`), content); nav.inputs.push(`${BASE}/inputs/${slug}`); } writeMdx(path.join(OUT_DIR, "inputs", "index.mdx"), generateCategoryIndex("inputs", "Input Types", inputs)); // Enums for (const t of enums) { const { slug, content } = generateEnumPage(t); writeMdx(path.join(OUT_DIR, "enums", `${slug}.mdx`), content); nav.enums.push(`${BASE}/enums/${slug}`); } writeMdx(path.join(OUT_DIR, "enums", "index.mdx"), generateCategoryIndex("enums", "Enums", enums)); // Interfaces for (const t of interfaces) { const { slug, content } = generateInterfacePage(t); writeMdx(path.join(OUT_DIR, "interfaces", `${slug}.mdx`), content); nav.interfaces.push(`${BASE}/interfaces/${slug}`); } if (interfaces.length > 0) { writeMdx(path.join(OUT_DIR, "interfaces", "index.mdx"), generateCategoryIndex("interfaces", "Interfaces", interfaces)); } // Unions for (const t of unions) { const { slug, content } = generateUnionPage(t); writeMdx(path.join(OUT_DIR, "unions", `${slug}.mdx`), content); nav.unions.push(`${BASE}/unions/${slug}`); } if (unions.length > 0) { writeMdx(path.join(OUT_DIR, "unions", "index.mdx"), generateCategoryIndex("unions", "Unions", unions)); } // Scalars for (const t of scalars) { const { slug, content } = generateScalarPage(t); writeMdx(path.join(OUT_DIR, "scalars", `${slug}.mdx`), content); nav.scalars.push(`${BASE}/scalars/${slug}`); } if (scalars.length > 0) { writeMdx(path.join(OUT_DIR, "scalars", "index.mdx"), generateCategoryIndex("scalars", "Scalars", scalars)); } // Write navigation snippet for docs.json const navSnippet = { tab: "GraphQL API", pages: [ `${BASE}/index`, { group: "Queries", pages: [`${BASE}/queries/index`, ...nav.queries], }, { group: "Mutations", pages: [`${BASE}/mutations/index`, ...nav.mutations], }, { group: "Objects", pages: [`${BASE}/objects/index`, ...nav.objects], }, { group: "Input Types", pages: [`${BASE}/inputs/index`, ...nav.inputs], }, { group: "Enums", pages: [`${BASE}/enums/index`, ...nav.enums], }, ], }; if (nav.interfaces.length > 0) { navSnippet.pages.push({ group: "Interfaces", pages: [`${BASE}/interfaces/index`, ...nav.interfaces], }); } if (nav.unions.length > 0) { navSnippet.pages.push({ group: "Unions", pages: [`${BASE}/unions/index`, ...nav.unions], }); } if (nav.scalars.length > 0) { navSnippet.pages.push({ group: "Scalars", pages: [`${BASE}/scalars/index`, ...nav.scalars], }); } const navPath = path.join(OUT_DIR, "_nav.json"); fs.writeFileSync(navPath, JSON.stringify(navSnippet, null, 2), "utf-8"); const totalFiles = 1 + // index queries.length + 1 + mutations.length + 1 + objects.length + 1 + inputs.length + 1 + enums.length + 1 + interfaces.length + (interfaces.length > 0 ? 1 : 0) + unions.length + (unions.length > 0 ? 1 : 0) + scalars.length + (scalars.length > 0 ? 1 : 0); console.log(`\nGenerated ${totalFiles} MDX files.`); console.log(`Navigation snippet written to ${navPath}`); console.log(`\nAdd the contents of _nav.json to your docs.json "navigation.tabs" array.`); } main();