@vercel/geistdocs 2.9.9 → 2.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli/index.js CHANGED
@@ -4,4 +4,4 @@ import{Option as Rn,program as A}from"commander";import{access as Ke,copyFile as
4
4
  `);throw new AggregateError(i,`Mixedbread search sync did not complete:
5
5
  ${a}`)}return r},Ft=async({client:e,file:t,pollIntervalMs:n,pollTimeoutMs:r,sleep:i})=>{let s=t,o=Date.now()+r;for(;s.status==="pending"||s.status==="in_progress";){if(Date.now()>=o)throw new Error(`Mixedbread timed out while indexing file ${t.id}.`);await i(n),s=await e.retrieveStoreFile(t.id)}if(s.status!=="completed")throw new Error(`Mixedbread failed to index file ${t.id} (${s.status}).`);return s},Dt=async({client:e,desired:t,pollIntervalMs:n,pollTimeoutMs:r,sleep:i})=>{let s=await e.uploadFile({content:t.document.content,filename:`${U(t.document.id).slice(0,32)}.md`}),o;try{o=await e.createStoreFile({externalId:t.externalId,fileId:s,metadata:{...t.metadata,[g.rawFileId]:s}})}catch(a){try{await e.deleteFile(s)}catch(d){throw new AggregateError([a,d],`Mixedbread failed to attach and clean up raw file ${s}.`)}throw a}return Ft({client:e,file:o,pollIntervalMs:n,pollTimeoutMs:r,sleep:i})},Ie=async({client:e,concurrency:t=St,manifest:n,pollIntervalMs:r=_t,pollTimeoutMs:i=Tt,revision:s,revisionAncestors:o=[],revisionTimestamp:a,sleep:d=Rt})=>{let c=_e(n);if(c.provider!=="mixedbread")return{deleted:0,skipped:c.documents.length,uploaded:0};let u=c.siteId?.trim();if(!u)throw new Error("Mixedbread retrieval requires a non-empty siteId in geistdocs.tsx.");if(c.documents.length===0)throw new Error("The Geistdocs search export is empty. Refusing to remove indexed documents.");let l=c.documents.map(p=>At(p,u,s,o,a)),m=new Map(l.map(p=>[p.document.id,p])),h=(await be(e)).flatMap(p=>{let y=q(p.metadata);return y?.siteId===u?[{file:p,metadata:y}]:[]}),x=new Map,P=new Set;for(let p of h){W(p.metadata,s,a)&&P.add(p.metadata.documentId);let y=m.get(p.metadata.documentId);y&&p.metadata.contentHash===y.hash&&p.file.status==="completed"&&!x.has(p.metadata.documentId)&&x.set(p.metadata.documentId,p)}let _=l.filter(p=>!(x.has(p.document.id)||P.has(p.document.id)));await Ee(_,t,p=>Dt({client:e,desired:p,pollIntervalMs:r,pollTimeoutMs:i,sleep:d}));let b=(await be(e)).flatMap(p=>{let y=q(p.metadata);return y?.siteId===u?[{file:p,metadata:y}]:[]}),D=new Set(b.filter(({metadata:p})=>W(p,s,a)).map(({metadata:p})=>p.documentId)),ie=new Set;for(let p of l){if(D.has(p.document.id))continue;let ae=b.filter(({file:V,metadata:k})=>V.status==="completed"&&k.documentId===p.document.id&&k.contentHash===p.hash).sort((V,k)=>V.file.id.localeCompare(k.file.id))[0];ae&&ie.add(ae.file.id)}let oe=b.filter(({file:p,metadata:y})=>p.status!=="pending"&&p.status!=="in_progress"&&!W(y,s,a)&&Mt({currentRevision:s,currentRevisionAncestors:o,currentRevisionTimestamp:a,desired:m.get(y.documentId),metadata:y})&&!ie.has(p.id));return await Ee(oe,t,async({file:p,metadata:y})=>{await e.deleteFile(y.rawFileId??p.id),await e.deleteStoreFile(p.id)}),{deleted:oe.length,skipped:l.length-_.length,uploaded:_.length}};var Ot=50,$t=e=>`vercel integration add mixedbread --name docs-${e||"your-site-id"} --environment production`,ve=(e,t)=>kt("git",t,{cwd:e,encoding:"utf8",stdio:["ignore","pipe","ignore"]}).trim(),Nt=e=>{let t=process.env.VERCEL_GIT_COMMIT_SHA?.trim(),n=[];try{n=ve(e,["rev-list",`--max-count=${Ot+1}`,t||"HEAD"]).split(`
6
6
  `).filter(Boolean)}catch{n=[]}let r=t||n[0],i;for(let s of Array.from(new Set([r,"HEAD"].filter(Boolean))))try{let o=Number(ve(e,["show","-s","--format=%ct",s]));if(Number.isFinite(o)){i=o;break}}catch{}return{revision:r,revisionAncestors:n.filter(s=>s!==r),revisionTimestamp:i}},Pe=async({allowNonProduction:e=!1,dir:t=".next"}={})=>{let n=process.cwd();Ct.loadEnvConfig(n,!1);let r=process.env.MXBAI_API_KEY?.trim(),i=process.env.MXBAI_STORE_ID?.trim();if(process.env.VERCEL_ENV!=="production"&&!e){console.log("Geistdocs search sync skipped: this is not a production Vercel build.");return}if(!!r!=!!i)throw new Error("Mixedbread is partially configured. Set both MXBAI_API_KEY and MXBAI_STORE_ID.");let s;try{s=await Te({cwd:n,outputDirectory:t})}catch(a){if(!(r||i)){console.log("Geistdocs search sync skipped: no Mixedbread credentials or static search export were found.");return}throw a}if(s.provider!=="mixedbread"){console.log("Geistdocs search sync skipped: Ask AI uses local retrieval.");return}if(!(r&&i))throw new Error(["Mixedbread retrieval is enabled, but MXBAI_API_KEY or MXBAI_STORE_ID is missing.","From the root of this site's repository, linked to the correct Vercel project, run:",$t(s.siteId)].join(`
7
- `));let o=await Ie({client:we({apiBaseUrl:process.env.MXBAI_BASE_URL,apiKey:r,storeId:i}),manifest:s,...Nt(n)});console.log(`Geistdocs search sync complete: ${o.uploaded} uploaded, ${o.deleted} deleted, ${o.skipped} unchanged.`)};import{readFileSync as Gt,writeFileSync as Ut}from"fs";import{mkdir as Lt,readFile as Z,writeFile as jt}from"fs/promises";import{dirname as Bt,extname as Vt,relative as Fe,resolve as j}from"path";import{intro as Jt,isCancel as Ht,log as I,multiselect as Xt,outro as L,spinner as Kt}from"@clack/prompts";import{glob as Yt}from"glob";import{Node as F,Project as qt,SyntaxKind as zt}from"ts-morph";var Wt="geistdocs.tsx",Qt="content/docs/**/*.mdx",ee=".translation-cache.json",Q=8,Ae=()=>({version:1,entries:{}}),Zt=async e=>{let t=await Z(e),{createHash:n}=await import("crypto");return n("sha256").update(t).digest("hex")},en=e=>{let t=j(process.cwd(),e);return Gt(t,"utf8")},Me=e=>F.isObjectLiteralExpression(e)?e.getProperties().flatMap(t=>{if(F.isPropertyAssignment(t)){let n=t.getNameNode();if(F.isIdentifier(n)||F.isStringLiteral(n))return[n.getText().replaceAll(/['"]/g,"")]}return[]}).filter(Boolean):[],tn=e=>{try{let t=new qt({compilerOptions:{allowJs:!0,jsx:4,module:99,target:10},skipAddingFilesFromTsConfig:!0,useInMemoryFileSystem:!0}),n=en(e),s=t.createSourceFile(e,n,{overwrite:!0}).getVariableDeclarations().find(a=>a.getName()==="translations")?.getInitializer();if(!s)return[];if(F.isObjectLiteralExpression(s))return Me(s);let o=s.getFirstDescendantByKind(zt.ObjectLiteralExpression);return o?Me(o):[]}catch(t){let n=t instanceof Error?t.message:`${t}`;return I.warn(`Failed to read locales from ${e}: ${n}`),[]}},nn=async()=>{let e=await Xt({message:"Which locales should be translated?",options:[{value:"cn",label:"Chinese (cn)"},{value:"jp",label:"Japanese (jp)"},{value:"es",label:"Spanish (es)"},{value:"fr",label:"French (fr)"},{value:"de",label:"German (de)"}],required:!0});return Ht(e)&&(L("Translation cancelled"),process.exit(0)),e},rn=async e=>(await Yt(e,{cwd:process.cwd(),absolute:!0,nodir:!0})).sort(),sn=async()=>{let e=j(process.cwd(),ee);try{let t=await Z(e,"utf8"),n=JSON.parse(t);return n.version!==1||!n.entries?Ae():{version:1,entries:n.entries}}catch{return Ae()}},Re=e=>{let t=j(process.cwd(),ee),n=JSON.stringify(e,null,2);Ut(t,n,"utf8")},on=async e=>{let t=await Promise.all(e.map(async n=>[n,await Zt(n)]));return Object.fromEntries(t)},an=(e,t)=>{let n=Vt(e);return`${e.slice(0,-n.length)}.${t}${n}`},De=(e,t)=>`${Fe(process.cwd(),e)}::${t}`,cn=(e,t,n,r,i=!1)=>{let s=[],o=0;for(let a of t){let d=n[a];for(let c of e){let u=an(a,c),l=De(a,c),m=r.entries[l];if(!i&&m?.hash===d){o+=1;continue}s.push({locale:c,sourceFile:a,sourceHash:d,targetFile:u})}}return{tasks:s,skippedCount:o}},dn=async e=>{await Lt(Bt(e),{recursive:!0})},ln=async(e,t,n)=>{let r=await fetch(e,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({content:t,locale:n})});if(!r.ok){let s=await r.text();throw new Error(`API request failed (${r.status}): ${s}`)}let i=await r.json();if(!i.translation)throw new Error("API response did not include a translation");return i.translation},pn=async(e,t,n)=>{let r=await Z(e.sourceFile,"utf8"),i=await ln(t,r,e.locale);await dn(e.targetFile),await jt(e.targetFile,i,"utf8"),n.entries[De(e.sourceFile,e.locale)]={hash:e.sourceHash,updatedAt:new Date().toISOString()}},ke=async(e,t)=>{Jt("Translate MDX content");let n=e??Qt,r=t.url||process.env.GEISTDOCS_TRANSLATE_URL||"https://geistdocs.com/translate",i=tn(t.config??Wt),s=await rn(n);s.length===0&&(I.error(`No MDX files found matching pattern: ${n}`),L("Translation cancelled"),process.exit(1)),I.info(`Found ${s.length} MDX file(s) matching pattern`),i.length===0&&(i=await nn());let o=j(process.cwd(),ee),a=await sn();await Re(a),I.info(`Using cache: ${o}`);let d=await on(s),{tasks:c,skippedCount:u}=cn(i,s,d,a,t.force);if(c.length===0){I.success("All translations are up to date!"),L(`Skipped ${u} file(s) (unchanged)`);return}let l=[];for(let h=0;h<c.length;h+=Q)l.push(c.slice(h,h+Q));I.info(`Processing ${c.length} translation(s) in ${l.length} batch(es) of up to ${Q}`),u>0&&I.info(`Skipped ${u} translation(s) (unchanged)`);let m=Kt();m.start("Translating content...");let f=0;for(let h of l)await Promise.all(h.map(async x=>{await pn(x,r,a),f+=1,m.message(`Translated ${f}/${c.length}: ${Fe(process.cwd(),x.targetFile)}`)})),await Re(a);m.stop("Translation complete!"),L(`Created/updated ${c.length} file(s)`)};import{access as un,copyFile as gn,mkdir as Ne,rm as re}from"fs/promises";import{dirname as mn,join as v}from"path";import{intro as fn,log as w,outro as B,spinner as Ge}from"@clack/prompts";import{glob as hn}from"glob";var wn=["**/*"],yn=["content/docs/**"],te=".geistdocs-tmp",xn=async(e,t)=>{let n=v(e,t);await re(n,{recursive:!0,force:!0}),await Ne(n,{recursive:!0})},ne=async e=>await re(e,{recursive:!0,force:!0}),Ce=async(e,t,n)=>(await hn(e,{cwd:n,nodir:!0,dot:!0,ignore:[".git/**",...t]})).sort(),bn=async e=>{try{return await un(e),!0}catch{return!1}},En=async(e,t,n)=>{let r=v(t,e),i=v(n,e);return await bn(r)?(await gn(r,i),{success:!0}):{success:!1,error:`Source file not found: ${r}`}},Sn=async(e,t)=>{let n=v(t,e);return await re(n,{force:!0}),{success:!0}},Oe=20,$e=async(e,t,n)=>{let r=[];for(let i=0;i<e.length;i+=n){let s=e.slice(i,i+n),o=await Promise.all(s.map(t));r.push(...o)}return r},_n=async(e,t,n,r,i)=>{let s={success:[],deleted:[],failed:[]},o=[...new Set(e.map(d=>mn(v(r,d))))];i.message(`Creating ${o.length} directories...`),await Promise.all(o.map(d=>Ne(d,{recursive:!0}))),i.message(`Updating ${e.length} files...`);let a=await $e(e,async d=>{let c=await En(d,n,r);return{file:d,...c}},Oe);for(let{file:d,success:c,error:u}of a)c?s.success.push(d):s.failed.push({file:d,error:u??"Unknown error"});if(t.length>0){i.message(`Deleting ${t.length} files...`);let d=await $e(t,async c=>{try{return await Sn(c,r),{file:c,success:!0}}catch(u){let l=u instanceof Error?u.message:`${u}`;return{file:c,success:!1,error:l}}},Oe);for(let c of d)c.success?s.deleted.push(c.file):s.failed.push({file:c.file,error:c.error})}return s},Tn=e=>{if(e.success.length>0){w.success(`Successfully updated ${e.success.length} files:`);for(let t of e.success)w.info(` \u2713 ${t}`)}if(e.deleted.length>0){w.success(`Deleted ${e.deleted.length} files:`);for(let t of e.deleted)w.info(` \u{1F5D1} ${t}`)}if(e.failed.length>0){w.warn(`Failed to update ${e.failed.length} files:`);for(let{file:t,error:n}of e.failed)w.error(` \u2717 ${t}: ${n}`)}},In=e=>e.includes("canary")?"canary":"latest",vn=async e=>{let t=await fetch(`https://registry.npmjs.org/${encodeURIComponent(S)}`);if(!t.ok)throw new Error(`Failed to resolve ${S}@${e}`);let r=(await t.json())["dist-tags"]?.[e];if(!r)throw new Error(`Could not find dist-tag ${e} for ${S}`);return r},Pn=async e=>{let t=await M(e),n=J(t,S);if(!n)return{currentVersion:n,nextVersion:void 0,updated:!1};let r=In(n),i=await vn(r);return n===i?{currentVersion:n,nextVersion:i,updateTag:r,updated:!1}:($(t,S,i),await O(e,t),{currentVersion:n,nextVersion:i,updateTag:r,updated:!0})},An=async(e,t,n)=>{let r=await M(e);if(!le(r,S))return!1;t&&t.length>0&&w.warn("Ignoring file patterns for a package-based site. This update will bump the package version instead."),n?.sync&&w.warn("Ignoring --sync for a package-based site. Runtime updates now come from the package version.");let{currentVersion:i,nextVersion:s,updateTag:o,updated:a}=await Pn(e);if(!a)return w.success(i?`@vercel/geistdocs is already at ${s} (${o}).`:"No package version update was needed."),B("Package-based site is already up to date."),!0;w.info(`Bumping ${S} from ${i} to ${s} (${o})`);let d=Ge();return d.start("Installing updated package version..."),await T("pnpm",["install"],{cwd:e}),d.stop("Package update complete!"),B("Please review and test the upgraded package version."),!0},Mn=async(e,t,n,r,i)=>{let s=v(e,te),o=Ge(),a=i?.sync?s:t;o.start("Preparing template snapshot..."),i?.sync&&(await xn(e,te),await N(s)),o.message("Scanning for files...");let d=await Ce(n,r,a),c=[];if(i?.sync){o.message("Comparing with local files...");let l=await Ce(n,r,e),m=new Set(d);c=l.filter(f=>!m.has(f))}if(o.stop(`Found ${d.length} files to update`),d.length===0&&c.length===0){w.warn("No files matched the patterns. Nothing to update."),i?.sync&&await ne(s),B("Update cancelled.");return}w.info(`Patterns: ${n.length}`),w.info(`Files to update: ${d.length}`),i?.sync&&w.info(`Files to delete: ${c.length}`),o.start("Updating files...");let u=await _n(d,c,a,e,o);i?.sync&&(o.message("Cleaning up..."),await ne(s)),o.stop("Update complete!"),Tn(u),B("Please review and test the changes carefully.")},Ue=async(e,t)=>{let n=process.cwd(),r=H(),i=e&&e.length>0?e:wn,s=e&&e.length>0?[]:yn;try{if(fn("Let's update your Geistdocs project!"),await An(n,e,t))return;w.info("Template source: bundled package snapshot"),e&&e.length>0&&w.info(`Updating specific files: ${e.join(", ")}`),t?.sync&&w.info("Sync mode enabled: will delete files removed from template"),await Mn(n,r,i,s,t)}catch(o){let a=o instanceof Error?o.message:`${o}`;try{await ne(v(n,te))}catch{}w.error(`Failed to update project: ${a}`),process.exit(1)}};A.name("geistdocs").description("CLI for Geistdocs projects").version("2.9.9","-v, --version","Output the current version");A.command("init").description("Initialize a new Geistdocs project").option("--name <name>","Name of the project").addOption(new Rn("--brand <brand>","Navbar brand").choices(["vercel","labs"]).default("vercel")).option("--disable-git","Disable git initialization").action(he);A.command("update [files...]").description("Update a Geistdocs project (optionally specify files/patterns to update)").option("--sync","Delete local files that no longer exist in the template").action(Ue);A.command("translate [pattern]").description("Translate MDX file(s) to one or more locales (default: content/docs/**/*.mdx)").option("--config <path>","Path to config file to load locales from (defaults to geistdocs.tsx)").option("--url <url>","Custom translation API URL (defaults to GEISTDOCS_TRANSLATE_URL or https://geistdocs.com/translate)").option("--force","Force re-translation of all files, ignoring cache").action(ke);var Fn=A.command("search").description("Manage the external search index used by Ask AI");Fn.command("sync").description("Sync the latest static docs export to Mixedbread").option("--dir <path>","Next.js output directory",".next").option("--allow-non-production","Run outside a production Vercel build").action(Pe);await A.parseAsync(process.argv).catch(e=>{console.error(e instanceof Error?e.message:e),process.exitCode=1});
7
+ `));let o=await Ie({client:we({apiBaseUrl:process.env.MXBAI_BASE_URL,apiKey:r,storeId:i}),manifest:s,...Nt(n)});console.log(`Geistdocs search sync complete: ${o.uploaded} uploaded, ${o.deleted} deleted, ${o.skipped} unchanged.`)};import{readFileSync as Gt,writeFileSync as Ut}from"fs";import{mkdir as Lt,readFile as Z,writeFile as jt}from"fs/promises";import{dirname as Bt,extname as Vt,relative as Fe,resolve as j}from"path";import{intro as Jt,isCancel as Ht,log as I,multiselect as Xt,outro as L,spinner as Kt}from"@clack/prompts";import{glob as Yt}from"glob";import{Node as F,Project as qt,SyntaxKind as zt}from"ts-morph";var Wt="geistdocs.tsx",Qt="content/docs/**/*.mdx",ee=".translation-cache.json",Q=8,Ae=()=>({version:1,entries:{}}),Zt=async e=>{let t=await Z(e),{createHash:n}=await import("crypto");return n("sha256").update(t).digest("hex")},en=e=>{let t=j(process.cwd(),e);return Gt(t,"utf8")},Me=e=>F.isObjectLiteralExpression(e)?e.getProperties().flatMap(t=>{if(F.isPropertyAssignment(t)){let n=t.getNameNode();if(F.isIdentifier(n)||F.isStringLiteral(n))return[n.getText().replaceAll(/['"]/g,"")]}return[]}).filter(Boolean):[],tn=e=>{try{let t=new qt({compilerOptions:{allowJs:!0,jsx:4,module:99,target:10},skipAddingFilesFromTsConfig:!0,useInMemoryFileSystem:!0}),n=en(e),s=t.createSourceFile(e,n,{overwrite:!0}).getVariableDeclarations().find(a=>a.getName()==="translations")?.getInitializer();if(!s)return[];if(F.isObjectLiteralExpression(s))return Me(s);let o=s.getFirstDescendantByKind(zt.ObjectLiteralExpression);return o?Me(o):[]}catch(t){let n=t instanceof Error?t.message:`${t}`;return I.warn(`Failed to read locales from ${e}: ${n}`),[]}},nn=async()=>{let e=await Xt({message:"Which locales should be translated?",options:[{value:"cn",label:"Chinese (cn)"},{value:"jp",label:"Japanese (jp)"},{value:"es",label:"Spanish (es)"},{value:"fr",label:"French (fr)"},{value:"de",label:"German (de)"}],required:!0});return Ht(e)&&(L("Translation cancelled"),process.exit(0)),e},rn=async e=>(await Yt(e,{cwd:process.cwd(),absolute:!0,nodir:!0})).sort(),sn=async()=>{let e=j(process.cwd(),ee);try{let t=await Z(e,"utf8"),n=JSON.parse(t);return n.version!==1||!n.entries?Ae():{version:1,entries:n.entries}}catch{return Ae()}},Re=e=>{let t=j(process.cwd(),ee),n=JSON.stringify(e,null,2);Ut(t,n,"utf8")},on=async e=>{let t=await Promise.all(e.map(async n=>[n,await Zt(n)]));return Object.fromEntries(t)},an=(e,t)=>{let n=Vt(e);return`${e.slice(0,-n.length)}.${t}${n}`},De=(e,t)=>`${Fe(process.cwd(),e)}::${t}`,cn=(e,t,n,r,i=!1)=>{let s=[],o=0;for(let a of t){let d=n[a];for(let c of e){let u=an(a,c),l=De(a,c),m=r.entries[l];if(!i&&m?.hash===d){o+=1;continue}s.push({locale:c,sourceFile:a,sourceHash:d,targetFile:u})}}return{tasks:s,skippedCount:o}},dn=async e=>{await Lt(Bt(e),{recursive:!0})},ln=async(e,t,n)=>{let r=await fetch(e,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({content:t,locale:n})});if(!r.ok){let s=await r.text();throw new Error(`API request failed (${r.status}): ${s}`)}let i=await r.json();if(!i.translation)throw new Error("API response did not include a translation");return i.translation},pn=async(e,t,n)=>{let r=await Z(e.sourceFile,"utf8"),i=await ln(t,r,e.locale);await dn(e.targetFile),await jt(e.targetFile,i,"utf8"),n.entries[De(e.sourceFile,e.locale)]={hash:e.sourceHash,updatedAt:new Date().toISOString()}},ke=async(e,t)=>{Jt("Translate MDX content");let n=e??Qt,r=t.url||process.env.GEISTDOCS_TRANSLATE_URL||"https://geistdocs.com/translate",i=tn(t.config??Wt),s=await rn(n);s.length===0&&(I.error(`No MDX files found matching pattern: ${n}`),L("Translation cancelled"),process.exit(1)),I.info(`Found ${s.length} MDX file(s) matching pattern`),i.length===0&&(i=await nn());let o=j(process.cwd(),ee),a=await sn();await Re(a),I.info(`Using cache: ${o}`);let d=await on(s),{tasks:c,skippedCount:u}=cn(i,s,d,a,t.force);if(c.length===0){I.success("All translations are up to date!"),L(`Skipped ${u} file(s) (unchanged)`);return}let l=[];for(let h=0;h<c.length;h+=Q)l.push(c.slice(h,h+Q));I.info(`Processing ${c.length} translation(s) in ${l.length} batch(es) of up to ${Q}`),u>0&&I.info(`Skipped ${u} translation(s) (unchanged)`);let m=Kt();m.start("Translating content...");let f=0;for(let h of l)await Promise.all(h.map(async x=>{await pn(x,r,a),f+=1,m.message(`Translated ${f}/${c.length}: ${Fe(process.cwd(),x.targetFile)}`)})),await Re(a);m.stop("Translation complete!"),L(`Created/updated ${c.length} file(s)`)};import{access as un,copyFile as gn,mkdir as Ne,rm as re}from"fs/promises";import{dirname as mn,join as v}from"path";import{intro as fn,log as w,outro as B,spinner as Ge}from"@clack/prompts";import{glob as hn}from"glob";var wn=["**/*"],yn=["content/docs/**"],te=".geistdocs-tmp",xn=async(e,t)=>{let n=v(e,t);await re(n,{recursive:!0,force:!0}),await Ne(n,{recursive:!0})},ne=async e=>await re(e,{recursive:!0,force:!0}),Ce=async(e,t,n)=>(await hn(e,{cwd:n,nodir:!0,dot:!0,ignore:[".git/**",...t]})).sort(),bn=async e=>{try{return await un(e),!0}catch{return!1}},En=async(e,t,n)=>{let r=v(t,e),i=v(n,e);return await bn(r)?(await gn(r,i),{success:!0}):{success:!1,error:`Source file not found: ${r}`}},Sn=async(e,t)=>{let n=v(t,e);return await re(n,{force:!0}),{success:!0}},Oe=20,$e=async(e,t,n)=>{let r=[];for(let i=0;i<e.length;i+=n){let s=e.slice(i,i+n),o=await Promise.all(s.map(t));r.push(...o)}return r},_n=async(e,t,n,r,i)=>{let s={success:[],deleted:[],failed:[]},o=[...new Set(e.map(d=>mn(v(r,d))))];i.message(`Creating ${o.length} directories...`),await Promise.all(o.map(d=>Ne(d,{recursive:!0}))),i.message(`Updating ${e.length} files...`);let a=await $e(e,async d=>{let c=await En(d,n,r);return{file:d,...c}},Oe);for(let{file:d,success:c,error:u}of a)c?s.success.push(d):s.failed.push({file:d,error:u??"Unknown error"});if(t.length>0){i.message(`Deleting ${t.length} files...`);let d=await $e(t,async c=>{try{return await Sn(c,r),{file:c,success:!0}}catch(u){let l=u instanceof Error?u.message:`${u}`;return{file:c,success:!1,error:l}}},Oe);for(let c of d)c.success?s.deleted.push(c.file):s.failed.push({file:c.file,error:c.error})}return s},Tn=e=>{if(e.success.length>0){w.success(`Successfully updated ${e.success.length} files:`);for(let t of e.success)w.info(` \u2713 ${t}`)}if(e.deleted.length>0){w.success(`Deleted ${e.deleted.length} files:`);for(let t of e.deleted)w.info(` \u{1F5D1} ${t}`)}if(e.failed.length>0){w.warn(`Failed to update ${e.failed.length} files:`);for(let{file:t,error:n}of e.failed)w.error(` \u2717 ${t}: ${n}`)}},In=e=>e.includes("canary")?"canary":"latest",vn=async e=>{let t=await fetch(`https://registry.npmjs.org/${encodeURIComponent(S)}`);if(!t.ok)throw new Error(`Failed to resolve ${S}@${e}`);let r=(await t.json())["dist-tags"]?.[e];if(!r)throw new Error(`Could not find dist-tag ${e} for ${S}`);return r},Pn=async e=>{let t=await M(e),n=J(t,S);if(!n)return{currentVersion:n,nextVersion:void 0,updated:!1};let r=In(n),i=await vn(r);return n===i?{currentVersion:n,nextVersion:i,updateTag:r,updated:!1}:($(t,S,i),await O(e,t),{currentVersion:n,nextVersion:i,updateTag:r,updated:!0})},An=async(e,t,n)=>{let r=await M(e);if(!le(r,S))return!1;t&&t.length>0&&w.warn("Ignoring file patterns for a package-based site. This update will bump the package version instead."),n?.sync&&w.warn("Ignoring --sync for a package-based site. Runtime updates now come from the package version.");let{currentVersion:i,nextVersion:s,updateTag:o,updated:a}=await Pn(e);if(!a)return w.success(i?`@vercel/geistdocs is already at ${s} (${o}).`:"No package version update was needed."),B("Package-based site is already up to date."),!0;w.info(`Bumping ${S} from ${i} to ${s} (${o})`);let d=Ge();return d.start("Installing updated package version..."),await T("pnpm",["install"],{cwd:e}),d.stop("Package update complete!"),B("Please review and test the upgraded package version."),!0},Mn=async(e,t,n,r,i)=>{let s=v(e,te),o=Ge(),a=i?.sync?s:t;o.start("Preparing template snapshot..."),i?.sync&&(await xn(e,te),await N(s)),o.message("Scanning for files...");let d=await Ce(n,r,a),c=[];if(i?.sync){o.message("Comparing with local files...");let l=await Ce(n,r,e),m=new Set(d);c=l.filter(f=>!m.has(f))}if(o.stop(`Found ${d.length} files to update`),d.length===0&&c.length===0){w.warn("No files matched the patterns. Nothing to update."),i?.sync&&await ne(s),B("Update cancelled.");return}w.info(`Patterns: ${n.length}`),w.info(`Files to update: ${d.length}`),i?.sync&&w.info(`Files to delete: ${c.length}`),o.start("Updating files...");let u=await _n(d,c,a,e,o);i?.sync&&(o.message("Cleaning up..."),await ne(s)),o.stop("Update complete!"),Tn(u),B("Please review and test the changes carefully.")},Ue=async(e,t)=>{let n=process.cwd(),r=H(),i=e&&e.length>0?e:wn,s=e&&e.length>0?[]:yn;try{if(fn("Let's update your Geistdocs project!"),await An(n,e,t))return;w.info("Template source: bundled package snapshot"),e&&e.length>0&&w.info(`Updating specific files: ${e.join(", ")}`),t?.sync&&w.info("Sync mode enabled: will delete files removed from template"),await Mn(n,r,i,s,t)}catch(o){let a=o instanceof Error?o.message:`${o}`;try{await ne(v(n,te))}catch{}w.error(`Failed to update project: ${a}`),process.exit(1)}};A.name("geistdocs").description("CLI for Geistdocs projects").version("2.11.0","-v, --version","Output the current version");A.command("init").description("Initialize a new Geistdocs project").option("--name <name>","Name of the project").addOption(new Rn("--brand <brand>","Navbar brand").choices(["vercel","labs"]).default("vercel")).option("--disable-git","Disable git initialization").action(he);A.command("update [files...]").description("Update a Geistdocs project (optionally specify files/patterns to update)").option("--sync","Delete local files that no longer exist in the template").action(Ue);A.command("translate [pattern]").description("Translate MDX file(s) to one or more locales (default: content/docs/**/*.mdx)").option("--config <path>","Path to config file to load locales from (defaults to geistdocs.tsx)").option("--url <url>","Custom translation API URL (defaults to GEISTDOCS_TRANSLATE_URL or https://geistdocs.com/translate)").option("--force","Force re-translation of all files, ignoring cache").action(ke);var Fn=A.command("search").description("Manage the external search index used by Ask AI");Fn.command("sync").description("Sync the latest static docs export to Mixedbread").option("--dir <path>","Next.js output directory",".next").option("--allow-non-production","Run outside a production Vercel build").action(Pe);await A.parseAsync(process.argv).catch(e=>{console.error(e instanceof Error?e.message:e),process.exitCode=1});
@@ -0,0 +1,29 @@
1
+ import type { ReactNode } from "react";
2
+ export interface TypeTableParameter {
3
+ description: ReactNode;
4
+ name: string;
5
+ }
6
+ export interface TypeTableNode {
7
+ default?: ReactNode;
8
+ deprecated?: boolean;
9
+ /** Additional description of the field. */
10
+ description?: ReactNode;
11
+ parameters?: TypeTableParameter[];
12
+ required?: boolean;
13
+ returns?: ReactNode;
14
+ /** The short type signature. */
15
+ type: ReactNode;
16
+ /** The full type signature. */
17
+ typeDescription?: ReactNode;
18
+ /** Optional link for the type. */
19
+ typeDescriptionLink?: string;
20
+ }
21
+ /**
22
+ * A table of props or fields, rendered as a Geist table with every value
23
+ * visible, so the page HTML carries the full reference. Accepts the same
24
+ * `type` object as the Fumadocs `TypeTable`.
25
+ */
26
+ export declare const TypeTable: ({ type, }: {
27
+ type: Record<string, TypeTableNode>;
28
+ }) => import("react/jsx-runtime").JSX.Element;
29
+ //# sourceMappingURL=type-table.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"type-table.d.ts","sourceRoot":"","sources":["../../src/components/type-table.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAMvC,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,SAAS,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2CAA2C;IAC3C,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAClC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,gCAAgC;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB,+BAA+B;IAC/B,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B,kCAAkC;IAClC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAyDD;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,WAEvB;IACD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CACrC,4CA+CA,CAAC"}
@@ -0,0 +1,24 @@
1
+ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
2
+ import { cn } from "#geistdocs-ui/utils";
3
+ import { getDocsLinkClassName } from "../internal/docs-link-class-name";
4
+ import { LocalizedLink } from "../internal/localized-link";
5
+ import { Table } from "./table";
6
+ // MDX passes types and defaults as strings; they read as code. Authors can
7
+ // still pass formatted React nodes, which render as given.
8
+ const asCode = (value) => typeof value === "string" ? _jsx("code", { children: value }) : value;
9
+ // App-local links follow the active language, as MDX links do.
10
+ const TypeLink = ({ children, href }) => href.startsWith("/") ? (_jsx(LocalizedLink, { className: getDocsLinkClassName(), href: href, children: children })) : (_jsx("a", { className: getDocsLinkClassName(), href: href, children: children }));
11
+ const Detail = ({ children, label, }) => (_jsxs("p", { className: "mt-2 mb-0 first:mt-0", children: [_jsxs("span", { className: "text-gray-900", children: [label, ": "] }), children] }));
12
+ const DescriptionCell = ({ item: { description, parameters = [], returns, typeDescription }, }) => (_jsxs("td", { children: [description ? _jsx("div", { className: "[&>p]:my-0", children: description }) : null, typeDescription ? (_jsx(Detail, { label: "Type", children: asCode(typeDescription) })) : null, parameters.length > 0 ? (_jsx(Detail, { label: "Parameters", children: parameters.map((parameter, index) => (_jsxs("span", { children: [index > 0 ? ", " : null, _jsx("code", { children: parameter.name }), parameter.description ? _jsxs(_Fragment, { children: [" (", parameter.description, ")"] }) : null] }, parameter.name))) })) : null, returns ? _jsx(Detail, { label: "Returns", children: asCode(returns) }) : null] }));
13
+ /**
14
+ * A table of props or fields, rendered as a Geist table with every value
15
+ * visible, so the page HTML carries the full reference. Accepts the same
16
+ * `type` object as the Fumadocs `TypeTable`.
17
+ */
18
+ export const TypeTable = ({ type, }) => {
19
+ const entries = Object.entries(type);
20
+ const hasDefaults = entries.some(([, item]) => item.default);
21
+ return (
22
+ // Descriptions wrap across lines, so every cell starts at the row's top.
23
+ _jsxs(Table, { className: "[&_tbody_td]:align-top", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: "Prop" }), _jsx("th", { children: "Type" }), hasDefaults ? _jsx("th", { children: "Default" }) : null, _jsx("th", { children: "Description" })] }) }), _jsx("tbody", { children: entries.map(([name, item]) => (_jsxs("tr", { children: [_jsxs("td", { className: "whitespace-nowrap", children: [_jsxs("code", { className: cn(item.deprecated && "text-gray-900 line-through"), children: [name, item.required ? "" : "?"] }), item.deprecated ? (_jsx("span", { className: "ml-2 text-gray-900 text-xs", children: "Deprecated" })) : null] }), _jsx("td", { children: item.typeDescriptionLink ? (_jsx(TypeLink, { href: item.typeDescriptionLink, children: asCode(item.type) })) : (asCode(item.type)) }), hasDefaults ? (_jsx("td", { children: item.default ? asCode(item.default) : null })) : null, _jsx(DescriptionCell, { item: item })] }, name))) })] }));
24
+ };
@@ -1 +1 @@
1
- {"version":3,"file":"localized-link.d.ts","sourceRoot":"","sources":["../../src/internal/localized-link.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAI7D,UAAU,kBAAmB,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;IAC1E,QAAQ,EAAE,SAAS,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAM/C,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,oBAAoB,kBAAkB,4CAInE,CAAC"}
1
+ {"version":3,"file":"localized-link.d.ts","sourceRoot":"","sources":["../../src/internal/localized-link.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAI7D,UAAU,kBAAmB,SAAQ,oBAAoB,CAAC,iBAAiB,CAAC;IAC1E,QAAQ,EAAE,SAAS,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAQ/C,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,oBAAoB,kBAAkB,4CAInE,CAAC"}
@@ -9,9 +9,11 @@ import { useGeistdocsConfig } from "./config-context";
9
9
  * `localizeHref` for the prefixing rules.
10
10
  */
11
11
  export const useLocalizedHref = (href) => {
12
+ // `useParams` returns null outside the App Router (for example, a server
13
+ // render with no route); the link then keeps the default language.
12
14
  const params = useParams();
13
15
  const { defaultLanguage = "en" } = useGeistdocsConfig();
14
- const language = typeof params.lang === "string" ? params.lang : undefined;
16
+ const language = typeof params?.lang === "string" ? params.lang : undefined;
15
17
  return localizeHref(href, language, defaultLanguage);
16
18
  };
17
19
  export const LocalizedLink = ({ href, ...props }) => {
@@ -1,9 +1,42 @@
1
1
  import { type PluggableList } from "unified";
2
+ /** A prop value the exporter can read without evaluating JavaScript. */
3
+ export type MarkdownPropValue = boolean | null | number | string | MarkdownPropValue[] | {
4
+ [key: string]: MarkdownPropValue;
5
+ };
6
+ /** One MDX element handed to a site's Markdown serializer. */
7
+ export interface MarkdownComponentElement {
8
+ /** Markdown converted from the element's children; empty when it has none. */
9
+ children: string;
10
+ /** Whether the element sits inside a paragraph rather than on its own lines. */
11
+ inline: boolean;
12
+ /** The component name as authored, such as `TSDoc` or `Docs.Callout`. */
13
+ name: string;
14
+ /**
15
+ * Props whose values are static literals: strings, numbers, booleans,
16
+ * `null`, and arrays or objects built only from those. Props that need
17
+ * JavaScript to evaluate (identifiers, calls, spreads) are left out.
18
+ */
19
+ props: Record<string, MarkdownPropValue>;
20
+ }
21
+ /**
22
+ * Return Markdown to write in place of the element (an empty string removes
23
+ * it), or `undefined` / `null` to keep the built-in conversion.
24
+ */
25
+ export type MarkdownComponentSerializer<Context = unknown> = (element: MarkdownComponentElement, context: Context) => string | null | undefined | Promise<string | null | undefined>;
26
+ export interface MdxToMarkdownOptions<Context = unknown> {
27
+ /** Markdown serializers for site components, keyed by component name. */
28
+ components?: Record<string, MarkdownComponentSerializer<Context>>;
29
+ /** Syntax plugins the site uses in `source.config.ts`, such as `remark-math`. */
30
+ remarkPlugins?: PluggableList;
31
+ }
2
32
  /**
3
33
  * Create a converter from authored MDX to component-free, agent-readable Markdown.
4
- * Pass the syntax plugins the site uses in `source.config.ts`, such as `remark-math`.
34
+ * Pass the syntax plugins the site uses in `source.config.ts`, such as
35
+ * `remark-math`, either directly or as `remarkPlugins` beside `components`,
36
+ * the Markdown serializers for site components. The converter passes its
37
+ * second argument to each serializer as context.
5
38
  */
6
- export declare const createMdxToMarkdown: (remarkPlugins?: PluggableList) => (source: string) => Promise<string>;
39
+ export declare const createMdxToMarkdown: <Context = undefined>(options?: PluggableList | MdxToMarkdownOptions<Context>) => (source: string, context?: Context) => Promise<string>;
7
40
  /** Convert authored MDX into component-free, agent-readable Markdown. */
8
- export declare const mdxToMarkdown: (source: string) => Promise<string>;
41
+ export declare const mdxToMarkdown: (source: string, context?: undefined) => Promise<string>;
9
42
  //# sourceMappingURL=mdx-to-markdown.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"mdx-to-markdown.d.ts","sourceRoot":"","sources":["../../src/internal/mdx-to-markdown.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,aAAa,EAAW,MAAM,SAAS,CAAC;AA43CtD;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,gBAAgB,aAAa,MAGjD,QAAQ,MAAM,oBAe7B,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,aAAa,WAlBF,MAAM,oBAkBoB,CAAC"}
1
+ {"version":3,"file":"mdx-to-markdown.d.ts","sourceRoot":"","sources":["../../src/internal/mdx-to-markdown.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,aAAa,EAA2B,MAAM,SAAS,CAAC;AAkCtE,wEAAwE;AACxE,MAAM,MAAM,iBAAiB,GACzB,OAAO,GACP,IAAI,GACJ,MAAM,GACN,MAAM,GACN,iBAAiB,EAAE,GACnB;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAEzC,8DAA8D;AAC9D,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,MAAM,EAAE,OAAO,CAAC;IAChB,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,MAAM,2BAA2B,CAAC,OAAO,GAAG,OAAO,IAAI,CAC3D,OAAO,EAAE,wBAAwB,EACjC,OAAO,EAAE,OAAO,KACb,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEpE,MAAM,WAAW,oBAAoB,CAAC,OAAO,GAAG,OAAO;IACrD,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,OAAO,CAAC,CAAC,CAAC;IAClE,iFAAiF;IACjF,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAklDD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,GAAG,SAAS,EACrD,UAAU,aAAa,GAAG,oBAAoB,CAAC,OAAO,CAAC,MAUzC,QAAQ,MAAM,EAAE,UAAU,OAAO,oBAgBhD,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,aAAa,WAnBF,MAAM,yCAmBoB,CAAC"}
@@ -40,6 +40,18 @@ function expressionString(node) {
40
40
  }
41
41
  return undefined;
42
42
  }
43
+ // Types are usually one string. Generated OpenAPI 3.1 references write a
44
+ // union as an array of strings (`["string", "null"]`), shown as `string | null`.
45
+ // An array with any non-literal member is unknown, so no partial union is shown.
46
+ const expressionType = (node) => {
47
+ if (node?.type !== "ArrayExpression") {
48
+ return expressionString(node);
49
+ }
50
+ const members = (node.elements ?? []).map((element) => element ? expressionString(element) : undefined);
51
+ return members.length > 0 && members.every(Boolean)
52
+ ? members.join(" | ")
53
+ : undefined;
54
+ };
43
55
  const expressionBoolean = (node) => node?.type === "Literal" && typeof node.value === "boolean"
44
56
  ? node.value
45
57
  : undefined;
@@ -305,7 +317,7 @@ const typeTableNodes = (node) => {
305
317
  }
306
318
  const name = propertyName(property);
307
319
  const value = property.value;
308
- const type = expressionString(objectProperty(value, "type"));
320
+ const type = expressionType(objectProperty(value, "type"));
309
321
  const description = expressionString(objectProperty(value, "description"));
310
322
  return name && (type || description)
311
323
  ? [
@@ -410,7 +422,7 @@ const describedLabel = (label, description) => {
410
422
  // The page shows the type name over its parameters but not the description,
411
423
  // so the export does the same.
412
424
  const parameterGroupItems = (group) => {
413
- const type = expressionString(objectProperty(group, "type"));
425
+ const type = expressionType(objectProperty(group, "type"));
414
426
  const nested = parameterItems(objectElements(objectProperty(group, "parameters")));
415
427
  if (!type) {
416
428
  return nested;
@@ -422,7 +434,7 @@ const parameterGroupItems = (group) => {
422
434
  function parameterItems(entries) {
423
435
  return entries.flatMap((entry) => {
424
436
  const name = expressionString(objectProperty(entry, "name"));
425
- const type = expressionString(objectProperty(entry, "type"));
437
+ const type = expressionType(objectProperty(entry, "type"));
426
438
  const description = expressionString(objectProperty(entry, "description"));
427
439
  const optional = objectProperty(entry, "isOptional");
428
440
  const nested = objectElements(objectProperty(entry, "properties")).flatMap(parameterGroupItems);
@@ -495,7 +507,7 @@ const apiVariantItems = (entry) => objectElements(objectProperty(entry, "variant
495
507
  function apiParameterItems(entries) {
496
508
  return entries.flatMap((entry) => {
497
509
  const name = expressionString(objectProperty(entry, "name"));
498
- const type = expressionString(objectProperty(entry, "type"));
510
+ const type = expressionType(objectProperty(entry, "type"));
499
511
  const description = expressionString(objectProperty(entry, "description"));
500
512
  const required = expressionBoolean(objectProperty(entry, "required"));
501
513
  const deprecated = expressionBoolean(objectProperty(entry, "deprecated"));
@@ -793,8 +805,10 @@ const endpointDisplayNodes = (node) => {
793
805
  const fullPath = path
794
806
  ? `${versionPrefix ?? (VERSIONED_PATH.test(path) ? "" : "/v1")}${path}`
795
807
  : undefined;
796
- const label = method?.toUpperCase() === "DELETE" ? "DEL" : method?.toUpperCase();
797
- return method && path ? [heading([inlineCode(`${label}${fullPath}`)])] : [];
808
+ // The page badge abbreviates DELETE to DEL; agents need the HTTP method.
809
+ return method && path
810
+ ? [heading([inlineCode(`${method.toUpperCase()} ${fullPath}`)])]
811
+ : [];
798
812
  };
799
813
  const themeAwareImageNodes = (node) => {
800
814
  const light = getAttributeExpression(node, "light");
@@ -1061,16 +1075,196 @@ const cleanNode = (node) => {
1061
1075
  const cleanChildren = (parent) => {
1062
1076
  parent.children = (parent.children ?? []).flatMap(cleanNode);
1063
1077
  };
1064
- const cleanMdx = () => (tree) => {
1065
- cleanChildren(tree);
1078
+ const UNKNOWN_VALUE = Symbol("unknown");
1079
+ // Evaluate only literal JavaScript. Anything that needs scope or execution
1080
+ // (identifiers, calls, spreads, interpolated templates) is unknown, and an
1081
+ // array or object that contains an unknown part is unknown as a whole so a
1082
+ // serializer never sees a partial shape.
1083
+ const staticArray = (node) => {
1084
+ const values = [];
1085
+ for (const element of node.elements ?? []) {
1086
+ const value = element ? staticValue(element) : UNKNOWN_VALUE;
1087
+ if (value === UNKNOWN_VALUE) {
1088
+ return UNKNOWN_VALUE;
1089
+ }
1090
+ values.push(value);
1091
+ }
1092
+ return values;
1093
+ };
1094
+ const staticObject = (node) => {
1095
+ const entries = [];
1096
+ for (const property of node.properties ?? []) {
1097
+ if (property.type !== "Property" || property.computed) {
1098
+ return UNKNOWN_VALUE;
1099
+ }
1100
+ const key = propertyName(property);
1101
+ const value = staticValue(property.value);
1102
+ if (key === undefined || value === UNKNOWN_VALUE) {
1103
+ return UNKNOWN_VALUE;
1104
+ }
1105
+ entries.push([key, value]);
1106
+ }
1107
+ // fromEntries defines own properties, so a `__proto__` key stays data.
1108
+ return Object.fromEntries(entries);
1109
+ };
1110
+ function staticValue(node) {
1111
+ if (!node) {
1112
+ return UNKNOWN_VALUE;
1113
+ }
1114
+ if (node.type === "Literal") {
1115
+ const { value } = node;
1116
+ return value === null ||
1117
+ typeof value === "boolean" ||
1118
+ typeof value === "number" ||
1119
+ typeof value === "string"
1120
+ ? value
1121
+ : UNKNOWN_VALUE;
1122
+ }
1123
+ if (node.type === "TemplateLiteral") {
1124
+ return expressionString(node) ?? UNKNOWN_VALUE;
1125
+ }
1126
+ if (node.type === "ArrayExpression") {
1127
+ return staticArray(node);
1128
+ }
1129
+ if (node.type === "ObjectExpression") {
1130
+ return staticObject(node);
1131
+ }
1132
+ if (node.type === "UnaryExpression" &&
1133
+ node.operator === "-" &&
1134
+ node.argument?.type === "Literal" &&
1135
+ typeof node.argument.value === "number") {
1136
+ return -node.argument.value;
1137
+ }
1138
+ return UNKNOWN_VALUE;
1139
+ }
1140
+ const attributeValue = (value) => {
1141
+ // A bare attribute (`<Badge new />`) is `true`, as in JSX.
1142
+ if (value === null || value === undefined) {
1143
+ return true;
1144
+ }
1145
+ if (typeof value === "string") {
1146
+ return value;
1147
+ }
1148
+ const statement = value.data?.estree?.body[0];
1149
+ return statement?.type === "ExpressionStatement"
1150
+ ? staticValue(statement.expression)
1151
+ : UNKNOWN_VALUE;
1152
+ };
1153
+ // JSX applies props left to right: a later attribute replaces an earlier one,
1154
+ // and a spread can replace any prop before it, so those are no longer known.
1155
+ const staticProps = (node) => {
1156
+ const props = new Map();
1157
+ for (const attribute of node.attributes ?? []) {
1158
+ if (attribute.type === "mdxJsxExpressionAttribute") {
1159
+ props.clear();
1160
+ continue;
1161
+ }
1162
+ if (attribute.type !== "mdxJsxAttribute" || !attribute.name) {
1163
+ continue;
1164
+ }
1165
+ const value = attributeValue(attribute.value);
1166
+ if (value === UNKNOWN_VALUE) {
1167
+ props.delete(attribute.name);
1168
+ }
1169
+ else {
1170
+ props.set(attribute.name, value);
1171
+ }
1172
+ }
1173
+ return Object.fromEntries(props);
1174
+ };
1175
+ const serializerFor = (node, components) => isJsxElement(node) && node.name && Object.hasOwn(components, node.name)
1176
+ ? components[node.name]
1177
+ : undefined;
1178
+ const childrenMarkdown = (node, state) => {
1179
+ // Convert a copy: when the serializer defers to the built-in conversion,
1180
+ // the original children must still be intact for it.
1181
+ const children = structuredClone(node.children ?? []).flatMap(cleanNode);
1182
+ const blocks = node.type === "mdxJsxTextElement"
1183
+ ? [{ children, type: "paragraph" }]
1184
+ : blockChildren({ children, type: node.type }, true);
1185
+ return state.stringify(blocks).trim();
1186
+ };
1187
+ const serializeElement = async (node, serializer, state) => {
1188
+ const name = node.name ?? "";
1189
+ const inline = node.type === "mdxJsxTextElement";
1190
+ let markdown;
1191
+ try {
1192
+ markdown = await serializer({
1193
+ children: childrenMarkdown(node, state),
1194
+ inline,
1195
+ name,
1196
+ props: staticProps(node),
1197
+ }, state.context);
1198
+ }
1199
+ catch (error) {
1200
+ throw new Error(`The Markdown serializer for <${name}> failed.`, {
1201
+ cause: error,
1202
+ });
1203
+ }
1204
+ if (markdown === null || markdown === undefined) {
1205
+ return undefined;
1206
+ }
1207
+ const nodes = state.parseMarkdown(markdown);
1208
+ // Inline output stays in its sentence when it is a single paragraph.
1209
+ if (inline && nodes.length === 1 && nodes[0].type === "paragraph") {
1210
+ return nodes[0].children ?? [];
1211
+ }
1212
+ return nodes;
1066
1213
  };
1067
- const createProcessor = (remarkPlugins = []) => unified()
1214
+ // Innermost elements first, so a serializer's `children` already contains
1215
+ // the output of serializers registered for the components nested inside it.
1216
+ const serializeComponents = async (parent, state) => {
1217
+ if (!parent.children) {
1218
+ return;
1219
+ }
1220
+ const children = [];
1221
+ for (const child of parent.children) {
1222
+ await serializeComponents(child, state);
1223
+ const serializer = serializerFor(child, state.components);
1224
+ const replacement = serializer
1225
+ ? await serializeElement(child, serializer, state)
1226
+ : undefined;
1227
+ if (replacement) {
1228
+ children.push(...replacement);
1229
+ }
1230
+ else {
1231
+ children.push(child);
1232
+ }
1233
+ }
1234
+ parent.children = children;
1235
+ };
1236
+ function cleanMdx(options) {
1237
+ const components = options.components ?? {};
1238
+ if (Object.keys(components).length === 0) {
1239
+ return (tree) => {
1240
+ cleanChildren(tree);
1241
+ };
1242
+ }
1243
+ const fragmentParser = unified()
1244
+ .use(remarkParse)
1245
+ .use(remarkGfm)
1246
+ .use(options.remarkPlugins);
1247
+ return async (tree, file) => {
1248
+ await serializeComponents(tree, {
1249
+ components,
1250
+ context: file.data.geistdocsMarkdownContext,
1251
+ parseMarkdown: (markdown) => fragmentParser.runSync(fragmentParser.parse(markdown))
1252
+ .children,
1253
+ stringify: (nodes) => String(this.stringify({
1254
+ children: nodes,
1255
+ type: "root",
1256
+ })),
1257
+ });
1258
+ cleanChildren(tree);
1259
+ };
1260
+ }
1261
+ const createProcessor = (remarkPlugins = [], components) => unified()
1068
1262
  .use(remarkParse)
1069
1263
  .use(remarkGfm)
1070
1264
  .use(remarkPlugins)
1071
1265
  .use(remarkMdx)
1072
1266
  .use(remarkFrontmatter, ["yaml"])
1073
- .use(cleanMdx)
1267
+ .use(cleanMdx, { components, remarkPlugins })
1074
1268
  .use(remarkStringify, {
1075
1269
  bullet: "-",
1076
1270
  fences: true,
@@ -1129,15 +1323,22 @@ const escapeOffendingText = (source, error) => {
1129
1323
  const MAX_ESCAPES = 100;
1130
1324
  /**
1131
1325
  * Create a converter from authored MDX to component-free, agent-readable Markdown.
1132
- * Pass the syntax plugins the site uses in `source.config.ts`, such as `remark-math`.
1326
+ * Pass the syntax plugins the site uses in `source.config.ts`, such as
1327
+ * `remark-math`, either directly or as `remarkPlugins` beside `components`,
1328
+ * the Markdown serializers for site components. The converter passes its
1329
+ * second argument to each serializer as context.
1133
1330
  */
1134
- export const createMdxToMarkdown = (remarkPlugins) => {
1135
- const processor = createProcessor(remarkPlugins);
1136
- return async (source) => {
1331
+ export const createMdxToMarkdown = (options) => {
1332
+ const { components, remarkPlugins } = Array.isArray(options)
1333
+ ? { components: undefined, remarkPlugins: options }
1334
+ : (options ?? {});
1335
+ const processor = createProcessor(remarkPlugins, components);
1336
+ return async (source, context) => {
1137
1337
  let input = source;
1138
1338
  for (let attempt = 0; attempt <= MAX_ESCAPES; attempt += 1) {
1139
1339
  try {
1140
- return String(await processor.process(input)).trim();
1340
+ const data = { geistdocsMarkdownContext: context };
1341
+ return String(await processor.process({ data, value: input })).trim();
1141
1342
  }
1142
1343
  catch (error) {
1143
1344
  const escaped = escapeOffendingText(input, error);
package/dist/mdx.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"mdx.d.ts","sourceRoot":"","sources":["../src/mdx.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AA8B/C,OAAO,EAGL,KAAK,4BAA4B,IAAI,mBAAmB,EAGzD,MAAM,iBAAiB,CAAC;AAEzB,eAAO,MAAM,2BAA2B,8EAAe,CAAC;AACxD,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAAoB,CAAC;AAC5D,eAAO,MAAM,mBAAmB;;;;;;;gCAAa,CAAC;AAC9C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;CAAa,CAAC;AAC1C,MAAM,MAAM,4BAA4B,GAAG,mBAAmB,CAAC;AAE/D,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC;AAEnD,eAAO,MAAM,yBAAyB,GACpC,aAAa,sBAAsB,KAClC,sBA6DD,CAAC;AAEH,eAAO,MAAM,mBAAmB,GAC9B,aAAa,sBAAsB,KAClC,sBAA+D,CAAC;AAEnE,eAAO,MAAM,2BAA2B,GACtC,GAAG,eAAe,KAAK,CAAC,sBAAsB,GAAG,SAAS,CAAC,KAC1D,sBACkD,CAAC"}
1
+ {"version":3,"file":"mdx.d.ts","sourceRoot":"","sources":["../src/mdx.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AA+B/C,OAAO,EAGL,KAAK,4BAA4B,IAAI,mBAAmB,EAGzD,MAAM,iBAAiB,CAAC;AAEzB,eAAO,MAAM,2BAA2B,8EAAe,CAAC;AACxD,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAAoB,CAAC;AAC5D,eAAO,MAAM,mBAAmB;;;;;;;gCAAa,CAAC;AAC9C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;CAAa,CAAC;AAC1C,MAAM,MAAM,4BAA4B,GAAG,mBAAmB,CAAC;AAE/D,MAAM,MAAM,sBAAsB,GAAG,aAAa,CAAC;AAEnD,eAAO,MAAM,yBAAyB,GACpC,aAAa,sBAAsB,KAClC,sBA6DD,CAAC;AAEH,eAAO,MAAM,mBAAmB,GAC9B,aAAa,sBAAsB,KAClC,sBAA+D,CAAC;AAEnE,eAAO,MAAM,2BAA2B,GACtC,GAAG,eAAe,KAAK,CAAC,sBAAsB,GAAG,SAAS,CAAC,KAC1D,sBACkD,CAAC"}
package/dist/mdx.js CHANGED
@@ -1,5 +1,4 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
- import { TypeTable } from "fumadocs-ui/components/type-table";
3
2
  import defaultMdxComponents from "fumadocs-ui/mdx";
4
3
  import Link from "next/link";
5
4
  import { Tabs } from "#geistdocs-ui/components/tabs";
@@ -17,6 +16,7 @@ import { Mermaid } from "./components/mermaid";
17
16
  import { Step, Steps } from "./components/steps";
18
17
  import { Table } from "./components/table";
19
18
  import { TabContent, TabsWithChildren } from "./components/tabs-with-children";
19
+ import { TypeTable } from "./components/type-table";
20
20
  import { Video } from "./components/video";
21
21
  import { LocalizedLink } from "./internal/localized-link";
22
22
  import { geistdocsFrontmatterSchema as frontmatterSchema, geistdocsMetaSchema as metaSchema, geistShikiTheme as shikiTheme, defineGeistdocsSourceConfig as sourceConfig, } from "./source-config";
package/dist/source.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import { type InferPageType, loader } from "fumadocs-core/source";
2
2
  import type { PluggableList } from "unified";
3
3
  import { type GeistdocsConfig, type GeistdocsPageSurface } from "./config.js";
4
+ import { type MarkdownComponentElement, type MarkdownComponentSerializer, type MarkdownPropValue } from "./internal/mdx-to-markdown.js";
4
5
  import { type GeistdocsVersionPaths } from "./internal/version-paths.js";
5
6
  export type { GeistdocsVersionPaths } from "./internal/version-paths.js";
6
7
  type LoaderOptions = Parameters<typeof loader>[0];
@@ -36,7 +37,23 @@ export interface GeistdocsMarkdownContext {
36
37
  }
37
38
  export type GeistdocsMarkdownFrontmatterValue = boolean | Date | number | readonly string[] | string | null | undefined;
38
39
  export type GeistdocsMarkdownFrontmatter = Record<string, GeistdocsMarkdownFrontmatterValue>;
40
+ /** A prop value Markdown serializers receive: literals only, never evaluated. */
41
+ export type GeistdocsMarkdownPropValue = MarkdownPropValue;
42
+ /** The MDX element a Markdown serializer converts. */
43
+ export type GeistdocsMarkdownComponentElement = MarkdownComponentElement;
44
+ /**
45
+ * Convert one site component to Markdown for the page's Markdown export.
46
+ * Return Markdown to write in its place (an empty string removes it), or
47
+ * `undefined` to keep the built-in conversion.
48
+ */
49
+ export type GeistdocsMarkdownComponentSerializer = MarkdownComponentSerializer<GeistdocsMarkdownContext>;
39
50
  export interface GeistdocsMarkdownOptions {
51
+ /**
52
+ * Markdown serializers for components the exporter cannot read, keyed by
53
+ * the component name used in MDX. A serializer for a built-in component
54
+ * name replaces its built-in conversion.
55
+ */
56
+ components?: Record<string, GeistdocsMarkdownComponentSerializer>;
40
57
  /** Add or override fields in the generated Markdown frontmatter. */
41
58
  frontmatter?: (defaults: Readonly<GeistdocsMarkdownFrontmatter>, context: GeistdocsMarkdownContext) => GeistdocsMarkdownFrontmatter | Promise<GeistdocsMarkdownFrontmatter>;
42
59
  /**
@@ -45,6 +62,12 @@ export interface GeistdocsMarkdownOptions {
45
62
  remarkPlugins?: PluggableList;
46
63
  transform?: (markdown: string, context: GeistdocsMarkdownContext) => Promise<string> | string;
47
64
  }
65
+ export interface GeistdocsSlugsContext {
66
+ /** Content file path relative to the content directory, including any language suffix, such as `errors/NOT_FOUND.mdx` or `guide.cn.mdx`. */
67
+ path: string;
68
+ /** Default slugs derived from the path, without folder groups or a trailing `index`. */
69
+ slugs: string[];
70
+ }
48
71
  export interface CreateSourceOptions {
49
72
  baseUrl?: string;
50
73
  config: Pick<GeistdocsConfig, "agent" | "basePath" | "defaultLanguage" | "siteUrl" | "translations"> & Partial<Pick<GeistdocsConfig, "title">>;
@@ -52,6 +75,12 @@ export interface CreateSourceOptions {
52
75
  id?: string;
53
76
  label?: string;
54
77
  markdown?: GeistdocsMarkdownOptions;
78
+ /**
79
+ * Transform each page's URL slugs, for example to lowercase them. Returned
80
+ * slugs apply everywhere page URLs appear: routes, the page tree, Markdown
81
+ * routes, the sitemap, and `llms.txt`. Two pages may not share a URL.
82
+ */
83
+ slugs?: (context: GeistdocsSlugsContext) => string[];
55
84
  }
56
85
  export interface GeistdocsSourceDefinition extends Omit<CreateSourceOptions, "config"> {
57
86
  id: string;
@@ -71,7 +100,7 @@ export interface CreateVersionedSourcesOptions {
71
100
  current: string;
72
101
  versions: GeistdocsVersionedSourceDefinition[];
73
102
  }
74
- export declare const createSource: ({ docs, config, baseUrl, id, label, markdown, }: CreateSourceOptions) => {
103
+ export declare const createSource: ({ docs, config, baseUrl, id, label, markdown, slugs, }: CreateSourceOptions) => {
75
104
  baseUrl: string;
76
105
  routingConfig: {
77
106
  agent: import("./config.js").GeistdocsAgentReadinessConfig | undefined;
@@ -1 +1 @@
1
- {"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../src/source.ts"],"names":[],"mappings":"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"}
package/dist/source.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { defineI18n } from "fumadocs-core/i18n";
2
2
  import { loader, } from "fumadocs-core/source";
3
3
  import { getPublicPath, withBasePath, } from "./config.js";
4
- import { createMdxToMarkdown } from "./internal/mdx-to-markdown.js";
4
+ import { createMdxToMarkdown, } from "./internal/mdx-to-markdown.js";
5
5
  import { stripVersionRoutePrefix, } from "./internal/version-paths.js";
6
6
  const MARKDOWN_LINK_PATTERN = /(\]\()(\/(?!\/)[^)\s]*)/g;
7
7
  const ROOT_ATTRIBUTE_PATTERN = /(\b(?:href|src)=["'])(\/(?!\/)[^"']*)/g;
@@ -57,6 +57,37 @@ const prefixMarkdownLinks = (markdown, basePath) => {
57
57
  ...prefixContentLinks(lines.slice(frontmatterEnd + 1), basePath),
58
58
  ].join("\n");
59
59
  };
60
+ const createSlugsPlugin = (transform) => {
61
+ // Each locale's storage inherits fallback pages from the default locale by
62
+ // reference, so transform every page object once.
63
+ const transformed = new WeakSet();
64
+ return {
65
+ name: "geistdocs:slugs",
66
+ // Runs after Fumadocs assigns the default slugs, so `index` pages and
67
+ // folder groups resolve before the transform sees them.
68
+ enforce: "post",
69
+ transformStorage({ storage }) {
70
+ const pathsByUrl = new Map();
71
+ for (const key of storage.getFiles()) {
72
+ const file = storage.read(key);
73
+ if (file?.format !== "page") {
74
+ continue;
75
+ }
76
+ if (!transformed.has(file)) {
77
+ // Storage keys drop the locale; `file.path` is the content file path.
78
+ file.slugs = transform({ path: file.path, slugs: [...file.slugs] });
79
+ transformed.add(file);
80
+ }
81
+ const url = file.slugs.join("/");
82
+ const existing = pathsByUrl.get(url);
83
+ if (existing) {
84
+ throw new Error(`Geistdocs slugs: ${existing} and ${file.path} both resolve to "/${url}".`);
85
+ }
86
+ pathsByUrl.set(url, file.path);
87
+ }
88
+ },
89
+ };
90
+ };
60
91
  const getLanguages = (config) => {
61
92
  const defaultLanguage = config.defaultLanguage ?? "en";
62
93
  const languages = Object.keys(config.translations ?? {});
@@ -118,7 +149,7 @@ const pageTreeTransformer = {
118
149
  };
119
150
  },
120
151
  };
121
- export const createSource = ({ docs, config, baseUrl = "/docs", id, label, markdown, }) => {
152
+ export const createSource = ({ docs, config, baseUrl = "/docs", id, label, markdown, slugs, }) => {
122
153
  const { defaultLanguage, languages } = getLanguages(config);
123
154
  const i18n = defineI18n({
124
155
  defaultLanguage,
@@ -131,6 +162,7 @@ export const createSource = ({ docs, config, baseUrl = "/docs", id, label, markd
131
162
  pageTree: {
132
163
  transformers: [pageTreeTransformer],
133
164
  },
165
+ plugins: slugs ? [createSlugsPlugin(slugs)] : undefined,
134
166
  source: docs.toFumadocsSource(),
135
167
  });
136
168
  const getPageImage = (page) => {
@@ -140,10 +172,16 @@ export const createSource = ({ docs, config, baseUrl = "/docs", id, label, markd
140
172
  url: getPublicPath(`/og/${segments.join("/")}`, config.basePath),
141
173
  };
142
174
  };
143
- const mdxToMarkdown = createMdxToMarkdown(markdown?.remarkPlugins);
175
+ const mdxToMarkdown = createMdxToMarkdown({
176
+ components: markdown?.components,
177
+ remarkPlugins: markdown?.remarkPlugins,
178
+ });
144
179
  const getPageMarkdown = async (page) => {
145
180
  const data = page.data;
146
- const content = await mdxToMarkdown(await data.getText("processed"));
181
+ const context = {
182
+ page: page,
183
+ };
184
+ const content = await mdxToMarkdown(await data.getText("processed"), context);
147
185
  const { title, description, badge, product, type, summary, prerequisites, related, navTitle, internal, noindex, canonical, tags, keywords, excludeFrom, lastModified, } = data;
148
186
  const sitemapPath = "/sitemap.md";
149
187
  const llmsPath = "/llms.txt";
@@ -176,9 +214,6 @@ export const createSource = ({ docs, config, baseUrl = "/docs", id, label, markd
176
214
  prerequisites,
177
215
  related,
178
216
  };
179
- const context = {
180
- page: page,
181
- };
182
217
  const overrides = markdown?.frontmatter
183
218
  ? await markdown.frontmatter(defaults, context)
184
219
  : {};
package/docs/agents.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Docs
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 2.9.9 so agents can understand the installed package without web access.
3
+ These docs are bundled with `@vercel/geistdocs` 2.11.0 so agents can understand the installed package without web access.
4
4
  They are generated from `apps/template/content/docs` during the package build.
5
5
 
6
6
  ## How to use these files
package/docs/llms.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Documentation
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 2.9.9.
3
+ These docs are bundled with `@vercel/geistdocs` 2.11.0.
4
4
  They describe how to build package-backed Geistdocs sites and how to use the package APIs from generated project adapters.
5
5
 
6
6
  ## Documentation Index
@@ -1402,6 +1402,20 @@ export default defineGeistdocsSourceConfig();
1402
1402
 
1403
1403
  To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/"` in `createSource`. Root-mounted docs need explicit `markdownRoutes`; Geistdocs does not infer a broad `/*path` mapping because it can capture homepages and non-docs app routes.
1404
1404
 
1405
+ ## Page URLs
1406
+
1407
+ Page URLs come from content file paths. To change them without renaming files, pass `slugs` to `createSource`. It receives the file `path` and the default `slugs`, with folder groups and a trailing `index` already removed, and returns the slugs to use:
1408
+
1409
+ ```ts title="lib/geistdocs/source.ts"
1410
+ export const geistdocsSource = createSource({
1411
+ docs,
1412
+ config,
1413
+ slugs: ({ slugs }) => slugs.map((slug) => slug.toLowerCase()),
1414
+ });
1415
+ ```
1416
+
1417
+ With this transform, `errors/NOT_FOUND.mdx` is served at `/docs/errors/not_found`. The function runs once per content file: a translated file's `path` keeps its language suffix (`guide.cn.mdx`), and a page that falls back to the default language uses the default-language result. The new URLs apply to routes, the page tree, Markdown routes, the sitemap, and `llms.txt`. Geistdocs throws when two pages resolve to the same URL. Redirect links that use the old URLs, for example with a `before` hook in `createProxy`.
1418
+
1405
1419
  ## Next.js base paths
1406
1420
 
1407
1421
  When Next.js mounts the application below a path, set the same value in `next.config.ts` and Geistdocs config:
@@ -1998,6 +2012,58 @@ Tables can also include inline code, as commonly used for file references:
1998
2012
  | `.env.local` | Local environment variables |
1999
2013
  | `tsconfig.json` | Configuration file for TypeScript |
2000
2014
 
2015
+ ### Type Tables
2016
+
2017
+ Document component props or configuration options with `TypeTable`. Pass a `type` object keyed by prop name, and Geistdocs renders it as a table with Prop, Type, Default, and Description columns. The Default column appears only when at least one row has a default.
2018
+
2019
+ ```mdx
2020
+ <TypeTable
2021
+ type={{
2022
+ children: {
2023
+ type: "string",
2024
+ description: "The Markdown content to render",
2025
+ required: true,
2026
+ },
2027
+ parseIncompleteMarkdown: {
2028
+ type: "boolean",
2029
+ default: "true",
2030
+ description: "Enable remend preprocessor for unterminated Markdown blocks",
2031
+ },
2032
+ shikiTheme: {
2033
+ type: "[ThemeInput, ThemeInput]",
2034
+ typeDescriptionLink: "https://shiki.style/themes",
2035
+ default: "['github-light', 'github-dark']",
2036
+ description: "Light and dark themes for code syntax highlighting",
2037
+ },
2038
+ }}
2039
+ />
2040
+ ```
2041
+
2042
+ This renders as:
2043
+
2044
+ <TypeTable
2045
+ type={{
2046
+ children: {
2047
+ type: "string",
2048
+ description: "The Markdown content to render",
2049
+ required: true,
2050
+ },
2051
+ parseIncompleteMarkdown: {
2052
+ type: "boolean",
2053
+ default: "true",
2054
+ description: "Enable remend preprocessor for unterminated Markdown blocks",
2055
+ },
2056
+ shikiTheme: {
2057
+ type: "[ThemeInput, ThemeInput]",
2058
+ typeDescriptionLink: "https://shiki.style/themes",
2059
+ default: "['github-light', 'github-dark']",
2060
+ description: "Light and dark themes for code syntax highlighting",
2061
+ },
2062
+ }}
2063
+ />
2064
+
2065
+ Optional props show a `?` after their name; set `required: true` to remove it. Set `deprecated: true` to mark a prop as deprecated, and `typeDescriptionLink` to link its type. Every value is part of the page HTML, so readers, search, and agents see the full reference.
2066
+
2001
2067
  ### Task Lists
2002
2068
 
2003
2069
  Create interactive task lists:
@@ -3557,7 +3623,7 @@ The response includes:
3557
3623
  - Frontmatter with page metadata and discovery links
3558
3624
  - Page content with presentation-only MDX components removed
3559
3625
 
3560
- All MDX components are processed and converted to plain Markdown equivalents.
3626
+ Geistdocs converts its built-in MDX components to plain Markdown equivalents. Components your site defines need a Markdown serializer, described in [Convert site components](#convert-site-components).
3561
3627
 
3562
3628
  ### Customize frontmatter
3563
3629
 
@@ -3598,6 +3664,43 @@ export const geistdocsSource = createSource({
3598
3664
 
3599
3665
  Plugins run before Geistdocs converts MDX components to Markdown. Use plugins that add syntax, and keep tree transforms in `source.config.ts` so they apply to the rendered page and its export together.
3600
3666
 
3667
+ ### Convert site components
3668
+
3669
+ Geistdocs reads MDX without running your React components, so a component your site defines exports only the content written between its tags. A self-closing component such as `<TSDoc definition={...} />` or `<FluidComputeCallout />` exports nothing. Register a serializer for each one with `markdown.components`, keyed by the name you use in MDX, and return the Markdown to write in its place:
3670
+
3671
+ ```ts title="lib/geistdocs/source.ts"
3672
+ // Your site's own generator for the type tables TSDoc renders.
3673
+ import { renderTypeTable } from "@/lib/tsdoc";
3674
+
3675
+ export const geistdocsSource = createSource({
3676
+ config,
3677
+ docs,
3678
+ markdown: {
3679
+ components: {
3680
+ FluidComputeCallout: () => "> Enable Fluid compute before deploying.",
3681
+ TSDoc: async ({ props }) =>
3682
+ renderTypeTable(props.definition, props.showSections),
3683
+ Author: ({ props }) => `[${props.name}](${props.link})`,
3684
+ Authors: ({ children, props }) => `${props.date} by ${children}`,
3685
+ },
3686
+ },
3687
+ });
3688
+ ```
3689
+
3690
+ Each serializer receives the element and the export context:
3691
+
3692
+ | Field | Type | Description |
3693
+ | --- | --- | --- |
3694
+ | `name` | `string` | The component name as written in MDX, such as `TSDoc` or `Docs.Callout`. |
3695
+ | `props` | `Record<string, GeistdocsMarkdownPropValue>` | Props whose values are literals: strings, numbers, booleans, `null`, and arrays or objects built only from those. A bare prop such as `interactive` is `true`. |
3696
+ | `children` | `string` | The element's children, already converted to Markdown. Empty for self-closing elements. |
3697
+ | `inline` | `boolean` | `true` when the element sits inside a sentence rather than on its own lines. |
3698
+ | `context.page` | `object` | The page being exported, with its `data`, `path`, `slugs`, and `url`. |
3699
+
3700
+ Geistdocs never evaluates JavaScript, so props that need it, such as identifiers (`data={benchmark}`), function calls, and interpolated template literals, are left out of `props`. A spread (`{...shared}`) removes the props written before it, because the spread could replace them. Read data your component imports, such as a JSON file or a generated type table, from the serializer instead.
3701
+
3702
+ Return a Markdown string to replace the element, an empty string to remove it, or `undefined` to keep Geistdocs' built-in conversion. Serializers can be `async`. Nested elements convert from the innermost out, so `children` already contains the output of serializers for the components inside it. When an inline element returns a single paragraph, that text stays in its sentence. A serializer registered for a built-in component name, such as `Callout`, replaces the built-in conversion; return `undefined` for the cases the built-in conversion should handle. When a serializer throws, the export fails with an error that names the component.
3703
+
3601
3704
  ## Missing documentation pages
3602
3705
 
3603
3706
  When a Markdown request does not match a page, Geistdocs returns an agent-readable `Page Not Found` response. It compares the requested path with visible page paths and titles, then links up to five likely matches with their descriptions. If no match is useful, the response links to `/llms.txt` instead.
@@ -467,5 +467,5 @@
467
467
  }
468
468
  ],
469
469
  "source": "apps/template/content/docs",
470
- "version": "2.9.9"
470
+ "version": "2.11.0"
471
471
  }
@@ -263,6 +263,20 @@ export default defineGeistdocsSourceConfig();
263
263
 
264
264
  To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/"` in `createSource`. Root-mounted docs need explicit `markdownRoutes`; Geistdocs does not infer a broad `/*path` mapping because it can capture homepages and non-docs app routes.
265
265
 
266
+ ## Page URLs
267
+
268
+ Page URLs come from content file paths. To change them without renaming files, pass `slugs` to `createSource`. It receives the file `path` and the default `slugs`, with folder groups and a trailing `index` already removed, and returns the slugs to use:
269
+
270
+ ```ts title="lib/geistdocs/source.ts"
271
+ export const geistdocsSource = createSource({
272
+ docs,
273
+ config,
274
+ slugs: ({ slugs }) => slugs.map((slug) => slug.toLowerCase()),
275
+ });
276
+ ```
277
+
278
+ With this transform, `errors/NOT_FOUND.mdx` is served at `/docs/errors/not_found`. The function runs once per content file: a translated file's `path` keeps its language suffix (`guide.cn.mdx`), and a page that falls back to the default language uses the default-language result. The new URLs apply to routes, the page tree, Markdown routes, the sitemap, and `llms.txt`. Geistdocs throws when two pages resolve to the same URL. Redirect links that use the old URLs, for example with a `before` hook in `createProxy`.
279
+
266
280
  ## Next.js base paths
267
281
 
268
282
  When Next.js mounts the application below a path, set the same value in `next.config.ts` and Geistdocs config:
package/docs/pages/md.md CHANGED
@@ -90,7 +90,7 @@ The response includes:
90
90
  - Frontmatter with page metadata and discovery links
91
91
  - Page content with presentation-only MDX components removed
92
92
 
93
- All MDX components are processed and converted to plain Markdown equivalents.
93
+ Geistdocs converts its built-in MDX components to plain Markdown equivalents. Components your site defines need a Markdown serializer, described in [Convert site components](#convert-site-components).
94
94
 
95
95
  ### Customize frontmatter
96
96
 
@@ -131,6 +131,43 @@ export const geistdocsSource = createSource({
131
131
 
132
132
  Plugins run before Geistdocs converts MDX components to Markdown. Use plugins that add syntax, and keep tree transforms in `source.config.ts` so they apply to the rendered page and its export together.
133
133
 
134
+ ### Convert site components
135
+
136
+ Geistdocs reads MDX without running your React components, so a component your site defines exports only the content written between its tags. A self-closing component such as `<TSDoc definition={...} />` or `<FluidComputeCallout />` exports nothing. Register a serializer for each one with `markdown.components`, keyed by the name you use in MDX, and return the Markdown to write in its place:
137
+
138
+ ```ts title="lib/geistdocs/source.ts"
139
+ // Your site's own generator for the type tables TSDoc renders.
140
+ import { renderTypeTable } from "@/lib/tsdoc";
141
+
142
+ export const geistdocsSource = createSource({
143
+ config,
144
+ docs,
145
+ markdown: {
146
+ components: {
147
+ FluidComputeCallout: () => "> Enable Fluid compute before deploying.",
148
+ TSDoc: async ({ props }) =>
149
+ renderTypeTable(props.definition, props.showSections),
150
+ Author: ({ props }) => `[${props.name}](${props.link})`,
151
+ Authors: ({ children, props }) => `${props.date} by ${children}`,
152
+ },
153
+ },
154
+ });
155
+ ```
156
+
157
+ Each serializer receives the element and the export context:
158
+
159
+ | Field | Type | Description |
160
+ | --- | --- | --- |
161
+ | `name` | `string` | The component name as written in MDX, such as `TSDoc` or `Docs.Callout`. |
162
+ | `props` | `Record<string, GeistdocsMarkdownPropValue>` | Props whose values are literals: strings, numbers, booleans, `null`, and arrays or objects built only from those. A bare prop such as `interactive` is `true`. |
163
+ | `children` | `string` | The element's children, already converted to Markdown. Empty for self-closing elements. |
164
+ | `inline` | `boolean` | `true` when the element sits inside a sentence rather than on its own lines. |
165
+ | `context.page` | `object` | The page being exported, with its `data`, `path`, `slugs`, and `url`. |
166
+
167
+ Geistdocs never evaluates JavaScript, so props that need it, such as identifiers (`data={benchmark}`), function calls, and interpolated template literals, are left out of `props`. A spread (`{...shared}`) removes the props written before it, because the spread could replace them. Read data your component imports, such as a JSON file or a generated type table, from the serializer instead.
168
+
169
+ Return a Markdown string to replace the element, an empty string to remove it, or `undefined` to keep Geistdocs' built-in conversion. Serializers can be `async`. Nested elements convert from the innermost out, so `children` already contains the output of serializers for the components inside it. When an inline element returns a single paragraph, that text stays in its sentence. A serializer registered for a built-in component name, such as `Callout`, replaces the built-in conversion; return `undefined` for the cases the built-in conversion should handle. When a serializer throws, the export fails with an error that names the component.
170
+
134
171
  ## Missing documentation pages
135
172
 
136
173
  When a Markdown request does not match a page, Geistdocs returns an agent-readable `Page Not Found` response. It compares the requested path with visible page paths and titles, then links up to five likely matches with their descriptions. If no match is useful, the response links to `/llms.txt` instead.
@@ -376,6 +376,58 @@ Tables can also include inline code, as commonly used for file references:
376
376
  | `.env.local` | Local environment variables |
377
377
  | `tsconfig.json` | Configuration file for TypeScript |
378
378
 
379
+ ### Type Tables
380
+
381
+ Document component props or configuration options with `TypeTable`. Pass a `type` object keyed by prop name, and Geistdocs renders it as a table with Prop, Type, Default, and Description columns. The Default column appears only when at least one row has a default.
382
+
383
+ ```mdx
384
+ <TypeTable
385
+ type={{
386
+ children: {
387
+ type: "string",
388
+ description: "The Markdown content to render",
389
+ required: true,
390
+ },
391
+ parseIncompleteMarkdown: {
392
+ type: "boolean",
393
+ default: "true",
394
+ description: "Enable remend preprocessor for unterminated Markdown blocks",
395
+ },
396
+ shikiTheme: {
397
+ type: "[ThemeInput, ThemeInput]",
398
+ typeDescriptionLink: "https://shiki.style/themes",
399
+ default: "['github-light', 'github-dark']",
400
+ description: "Light and dark themes for code syntax highlighting",
401
+ },
402
+ }}
403
+ />
404
+ ```
405
+
406
+ This renders as:
407
+
408
+ <TypeTable
409
+ type={{
410
+ children: {
411
+ type: "string",
412
+ description: "The Markdown content to render",
413
+ required: true,
414
+ },
415
+ parseIncompleteMarkdown: {
416
+ type: "boolean",
417
+ default: "true",
418
+ description: "Enable remend preprocessor for unterminated Markdown blocks",
419
+ },
420
+ shikiTheme: {
421
+ type: "[ThemeInput, ThemeInput]",
422
+ typeDescriptionLink: "https://shiki.style/themes",
423
+ default: "['github-light', 'github-dark']",
424
+ description: "Light and dark themes for code syntax highlighting",
425
+ },
426
+ }}
427
+ />
428
+
429
+ Optional props show a `?` after their name; set `required: true` to remove it. Set `deprecated: true` to mark a prop as deprecated, and `typeDescriptionLink` to link its type. Every value is part of the page HTML, so readers, search, and agents see the full reference.
430
+
379
431
  ### Task Lists
380
432
 
381
433
  Create interactive task lists:
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@vercel/geistdocs",
3
3
  "description": "Runtime and CLI for Geistdocs projects.",
4
- "version": "2.9.9",
4
+ "version": "2.11.0",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
package/shared-theme.css CHANGED
@@ -121,7 +121,7 @@ button:not(:disabled, [aria-disabled="true"]) {
121
121
  }
122
122
 
123
123
  @media (width >= 80rem) {
124
- #nd-page {
124
+ #nd-page:not([data-full="true"]) {
125
125
  max-width: 780px;
126
126
  transform: translateX(-20px);
127
127
  }
@@ -261,6 +261,20 @@ export default defineGeistdocsSourceConfig();
261
261
 
262
262
  To serve docs from the site root, use `route: "/"` in `content` and `baseUrl: "/"` in `createSource`. Root-mounted docs need explicit `markdownRoutes`; Geistdocs does not infer a broad `/*path` mapping because it can capture homepages and non-docs app routes.
263
263
 
264
+ ## Page URLs
265
+
266
+ Page URLs come from content file paths. To change them without renaming files, pass `slugs` to `createSource`. It receives the file `path` and the default `slugs`, with folder groups and a trailing `index` already removed, and returns the slugs to use:
267
+
268
+ ```ts title="lib/geistdocs/source.ts"
269
+ export const geistdocsSource = createSource({
270
+ docs,
271
+ config,
272
+ slugs: ({ slugs }) => slugs.map((slug) => slug.toLowerCase()),
273
+ });
274
+ ```
275
+
276
+ With this transform, `errors/NOT_FOUND.mdx` is served at `/docs/errors/not_found`. The function runs once per content file: a translated file's `path` keeps its language suffix (`guide.cn.mdx`), and a page that falls back to the default language uses the default-language result. The new URLs apply to routes, the page tree, Markdown routes, the sitemap, and `llms.txt`. Geistdocs throws when two pages resolve to the same URL. Redirect links that use the old URLs, for example with a `before` hook in `createProxy`.
277
+
264
278
  ## Next.js base paths
265
279
 
266
280
  When Next.js mounts the application below a path, set the same value in `next.config.ts` and Geistdocs config:
@@ -88,7 +88,7 @@ The response includes:
88
88
  - Frontmatter with page metadata and discovery links
89
89
  - Page content with presentation-only MDX components removed
90
90
 
91
- All MDX components are processed and converted to plain Markdown equivalents.
91
+ Geistdocs converts its built-in MDX components to plain Markdown equivalents. Components your site defines need a Markdown serializer, described in [Convert site components](#convert-site-components).
92
92
 
93
93
  ### Customize frontmatter
94
94
 
@@ -129,6 +129,43 @@ export const geistdocsSource = createSource({
129
129
 
130
130
  Plugins run before Geistdocs converts MDX components to Markdown. Use plugins that add syntax, and keep tree transforms in `source.config.ts` so they apply to the rendered page and its export together.
131
131
 
132
+ ### Convert site components
133
+
134
+ Geistdocs reads MDX without running your React components, so a component your site defines exports only the content written between its tags. A self-closing component such as `<TSDoc definition={...} />` or `<FluidComputeCallout />` exports nothing. Register a serializer for each one with `markdown.components`, keyed by the name you use in MDX, and return the Markdown to write in its place:
135
+
136
+ ```ts title="lib/geistdocs/source.ts"
137
+ // Your site's own generator for the type tables TSDoc renders.
138
+ import { renderTypeTable } from "@/lib/tsdoc";
139
+
140
+ export const geistdocsSource = createSource({
141
+ config,
142
+ docs,
143
+ markdown: {
144
+ components: {
145
+ FluidComputeCallout: () => "> Enable Fluid compute before deploying.",
146
+ TSDoc: async ({ props }) =>
147
+ renderTypeTable(props.definition, props.showSections),
148
+ Author: ({ props }) => `[${props.name}](${props.link})`,
149
+ Authors: ({ children, props }) => `${props.date} by ${children}`,
150
+ },
151
+ },
152
+ });
153
+ ```
154
+
155
+ Each serializer receives the element and the export context:
156
+
157
+ | Field | Type | Description |
158
+ | --- | --- | --- |
159
+ | `name` | `string` | The component name as written in MDX, such as `TSDoc` or `Docs.Callout`. |
160
+ | `props` | `Record<string, GeistdocsMarkdownPropValue>` | Props whose values are literals: strings, numbers, booleans, `null`, and arrays or objects built only from those. A bare prop such as `interactive` is `true`. |
161
+ | `children` | `string` | The element's children, already converted to Markdown. Empty for self-closing elements. |
162
+ | `inline` | `boolean` | `true` when the element sits inside a sentence rather than on its own lines. |
163
+ | `context.page` | `object` | The page being exported, with its `data`, `path`, `slugs`, and `url`. |
164
+
165
+ Geistdocs never evaluates JavaScript, so props that need it, such as identifiers (`data={benchmark}`), function calls, and interpolated template literals, are left out of `props`. A spread (`{...shared}`) removes the props written before it, because the spread could replace them. Read data your component imports, such as a JSON file or a generated type table, from the serializer instead.
166
+
167
+ Return a Markdown string to replace the element, an empty string to remove it, or `undefined` to keep Geistdocs' built-in conversion. Serializers can be `async`. Nested elements convert from the innermost out, so `children` already contains the output of serializers for the components inside it. When an inline element returns a single paragraph, that text stays in its sentence. A serializer registered for a built-in component name, such as `Callout`, replaces the built-in conversion; return `undefined` for the cases the built-in conversion should handle. When a serializer throws, the export fails with an error that names the component.
168
+
132
169
  ## Missing documentation pages
133
170
 
134
171
  When a Markdown request does not match a page, Geistdocs returns an agent-readable `Page Not Found` response. It compares the requested path with visible page paths and titles, then links up to five likely matches with their descriptions. If no match is useful, the response links to `/llms.txt` instead.
@@ -117,6 +117,58 @@ Geistdocs 支持 GFM 扩展,包括表格、任务列表和自动链接。
117
117
  | GFM | GitHub extensions | Supported |
118
118
  | MDX | JSX in Markdown | Supported |
119
119
 
120
+ ### 类型表格
121
+
122
+ 使用 `TypeTable` 记录组件属性或配置选项。传入以属性名为键的 `type` 对象,Geistdocs 会将其渲染为包含 Prop、Type、Default 和 Description 列的表格。只有当至少一行包含默认值时,才会显示 Default 列。
123
+
124
+ ```mdx
125
+ <TypeTable
126
+ type={{
127
+ children: {
128
+ type: "string",
129
+ description: "The Markdown content to render",
130
+ required: true,
131
+ },
132
+ parseIncompleteMarkdown: {
133
+ type: "boolean",
134
+ default: "true",
135
+ description: "Enable remend preprocessor for unterminated Markdown blocks",
136
+ },
137
+ shikiTheme: {
138
+ type: "[ThemeInput, ThemeInput]",
139
+ typeDescriptionLink: "https://shiki.style/themes",
140
+ default: "['github-light', 'github-dark']",
141
+ description: "Light and dark themes for code syntax highlighting",
142
+ },
143
+ }}
144
+ />
145
+ ```
146
+
147
+ 渲染效果如下:
148
+
149
+ <TypeTable
150
+ type={{
151
+ children: {
152
+ type: "string",
153
+ description: "The Markdown content to render",
154
+ required: true,
155
+ },
156
+ parseIncompleteMarkdown: {
157
+ type: "boolean",
158
+ default: "true",
159
+ description: "Enable remend preprocessor for unterminated Markdown blocks",
160
+ },
161
+ shikiTheme: {
162
+ type: "[ThemeInput, ThemeInput]",
163
+ typeDescriptionLink: "https://shiki.style/themes",
164
+ default: "['github-light', 'github-dark']",
165
+ description: "Light and dark themes for code syntax highlighting",
166
+ },
167
+ }}
168
+ />
169
+
170
+ 可选属性会在名称后显示 `?`;设置 `required: true` 可将其移除。设置 `deprecated: true` 可将属性标记为已弃用,设置 `typeDescriptionLink` 可为其类型添加链接。所有值都包含在页面 HTML 中,读者、搜索和智能体都能看到完整的参考信息。
171
+
120
172
  ### 任务列表
121
173
 
122
174
  创建交互式任务列表:
@@ -380,6 +380,58 @@ Tables can also include inline code, as commonly used for file references:
380
380
  | `.env.local` | Local environment variables |
381
381
  | `tsconfig.json` | Configuration file for TypeScript |
382
382
 
383
+ ### Type Tables
384
+
385
+ Document component props or configuration options with `TypeTable`. Pass a `type` object keyed by prop name, and Geistdocs renders it as a table with Prop, Type, Default, and Description columns. The Default column appears only when at least one row has a default.
386
+
387
+ ```mdx
388
+ <TypeTable
389
+ type={{
390
+ children: {
391
+ type: "string",
392
+ description: "The Markdown content to render",
393
+ required: true,
394
+ },
395
+ parseIncompleteMarkdown: {
396
+ type: "boolean",
397
+ default: "true",
398
+ description: "Enable remend preprocessor for unterminated Markdown blocks",
399
+ },
400
+ shikiTheme: {
401
+ type: "[ThemeInput, ThemeInput]",
402
+ typeDescriptionLink: "https://shiki.style/themes",
403
+ default: "['github-light', 'github-dark']",
404
+ description: "Light and dark themes for code syntax highlighting",
405
+ },
406
+ }}
407
+ />
408
+ ```
409
+
410
+ This renders as:
411
+
412
+ <TypeTable
413
+ type={{
414
+ children: {
415
+ type: "string",
416
+ description: "The Markdown content to render",
417
+ required: true,
418
+ },
419
+ parseIncompleteMarkdown: {
420
+ type: "boolean",
421
+ default: "true",
422
+ description: "Enable remend preprocessor for unterminated Markdown blocks",
423
+ },
424
+ shikiTheme: {
425
+ type: "[ThemeInput, ThemeInput]",
426
+ typeDescriptionLink: "https://shiki.style/themes",
427
+ default: "['github-light', 'github-dark']",
428
+ description: "Light and dark themes for code syntax highlighting",
429
+ },
430
+ }}
431
+ />
432
+
433
+ Optional props show a `?` after their name; set `required: true` to remove it. Set `deprecated: true` to mark a prop as deprecated, and `typeDescriptionLink` to link its type. Every value is part of the page HTML, so readers, search, and agents see the full reference.
434
+
383
435
  ### Task Lists
384
436
 
385
437
  Create interactive task lists:
@@ -17,7 +17,7 @@
17
17
  "@streamdown/code": "^1.0.1",
18
18
  "@vercel/agent-readability": "^0.7.0",
19
19
  "@vercel/analytics": "^1.6.1",
20
- "@vercel/geistdocs": "2.9.9",
20
+ "@vercel/geistdocs": "2.11.0",
21
21
  "@vercel/speed-insights": "^1.3.1",
22
22
  "ai": "^6.0.132",
23
23
  "clsx": "^2.1.1",