@vercel/geistdocs 1.28.0 → 1.28.1

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{program as F}from"commander";import{access as je,copyFile as Be}from"fs/p
4
4
  `);throw new AggregateError(s,`Mixedbread search sync did not complete:
5
5
  ${a}`)}return r},It=async({client:e,file:t,pollIntervalMs:n,pollTimeoutMs:r,sleep:s})=>{let i=t,o=Date.now()+r;for(;i.status==="pending"||i.status==="in_progress";){if(Date.now()>=o)throw new Error(`Mixedbread timed out while indexing file ${t.id}.`);await s(n),i=await e.retrieveStoreFile(t.id)}if(i.status!=="completed")throw new Error(`Mixedbread failed to index file ${t.id} (${i.status}).`);return i},Mt=async({client:e,desired:t,pollIntervalMs:n,pollTimeoutMs:r,sleep:s})=>{let i=await e.uploadFile({content:t.document.content,filename:`${L(t.document.id).slice(0,32)}.md`}),o;try{o=await e.createStoreFile({externalId:t.externalId,fileId:i,metadata:{...t.metadata,[g.rawFileId]:i}})}catch(a){try{await e.deleteFile(i)}catch(d){throw new AggregateError([a,d],`Mixedbread failed to attach and clean up raw file ${i}.`)}throw a}return It({client:e,file:o,pollIntervalMs:n,pollTimeoutMs:r,sleep:s})},xe=async({client:e,concurrency:t=ht,manifest:n,pollIntervalMs:r=wt,pollTimeoutMs:s=yt,revision:i,revisionAncestors:o=[],revisionTimestamp:a,sleep:d=Tt})=>{let c=we(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=>Et(p,u,i,o,a)),m=new Map(l.map(p=>[p.document.id,p])),h=(await me(e)).flatMap(p=>{let y=K(p.metadata);return y?.siteId===u?[{file:p,metadata:y}]:[]}),x=new Map,v=new Set;for(let p of h){z(p.metadata,i,a)&&v.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)||v.has(p.document.id)));await fe(_,t,p=>Mt({client:e,desired:p,pollIntervalMs:r,pollTimeoutMs:s,sleep:d}));let b=(await me(e)).flatMap(p=>{let y=K(p.metadata);return y?.siteId===u?[{file:p,metadata:y}]:[]}),A=new Set(b.filter(({metadata:p})=>z(p,i,a)).map(({metadata:p})=>p.documentId)),se=new Set;for(let p of l){if(A.has(p.document.id))continue;let oe=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];oe&&se.add(oe.file.id)}let ie=b.filter(({file:p,metadata:y})=>p.status!=="pending"&&p.status!=="in_progress"&&!z(y,i,a)&&_t({currentRevision:i,currentRevisionAncestors:o,currentRevisionTimestamp:a,desired:m.get(y.documentId),metadata:y})&&!se.has(p.id));return await fe(ie,t,async({file:p,metadata:y})=>{await e.deleteFile(y.rawFileId??p.id),await e.deleteStoreFile(p.id)}),{deleted:ie.length,skipped:l.length-_.length,uploaded:_.length}};var Rt=50,Pt=e=>`vercel integration add mixedbread --name docs-${e||"your-site-id"} --environment production`,be=(e,t)=>vt("git",t,{cwd:e,encoding:"utf8",stdio:["ignore","pipe","ignore"]}).trim(),Dt=e=>{let t=process.env.VERCEL_GIT_COMMIT_SHA?.trim(),n=[];try{n=be(e,["rev-list",`--max-count=${Rt+1}`,t||"HEAD"]).split(`
6
6
  `).filter(Boolean)}catch{n=[]}let r=t||n[0],s;for(let i of Array.from(new Set([r,"HEAD"].filter(Boolean))))try{let o=Number(be(e,["show","-s","--format=%ct",i]));if(Number.isFinite(o)){s=o;break}}catch{}return{revision:r,revisionAncestors:n.filter(i=>i!==r),revisionTimestamp:s}},Se=async({allowNonProduction:e=!1,dir:t=".next"}={})=>{let n=process.cwd();Ft.loadEnvConfig(n,!1);let r=process.env.MXBAI_API_KEY?.trim(),s=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!=!!s)throw new Error("Mixedbread is partially configured. Set both MXBAI_API_KEY and MXBAI_STORE_ID.");let i;try{i=await ye({cwd:n,outputDirectory:t})}catch(a){if(!(r||s)){console.log("Geistdocs search sync skipped: no Mixedbread credentials or static search export were found.");return}throw a}if(i.provider!=="mixedbread"){console.log("Geistdocs search sync skipped: Ask AI uses local retrieval.");return}if(!(r&&s))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:",Pt(i.siteId)].join(`
7
- `));let o=await xe({client:pe({apiBaseUrl:process.env.MXBAI_BASE_URL,apiKey:r,storeId:s}),manifest:i,...Dt(n)});console.log(`Geistdocs search sync complete: ${o.uploaded} uploaded, ${o.deleted} deleted, ${o.skipped} unchanged.`)};import{readFileSync as At,writeFileSync as kt}from"fs";import{mkdir as Ct,readFile as Q,writeFile as $t}from"fs/promises";import{dirname as Ot,extname as Nt,relative as Ie,resolve as j}from"path";import{intro as Ut,isCancel as Lt,log as I,multiselect as Gt,outro as G,spinner as jt}from"@clack/prompts";import{glob as Bt}from"glob";import{Node as D,Project as Vt,SyntaxKind as Jt}from"ts-morph";var Ht="geistdocs.tsx",Xt="content/docs/**/*.mdx",Z=".translation-cache.json",W=8,Ee=()=>({version:1,entries:{}}),Yt=async e=>{let t=await Q(e),{createHash:n}=await import("crypto");return n("sha256").update(t).digest("hex")},Kt=e=>{let t=j(process.cwd(),e);return At(t,"utf8")},_e=e=>D.isObjectLiteralExpression(e)?e.getProperties().flatMap(t=>{if(D.isPropertyAssignment(t)){let n=t.getNameNode();if(D.isIdentifier(n)||D.isStringLiteral(n))return[n.getText().replaceAll(/['"]/g,"")]}return[]}).filter(Boolean):[],qt=e=>{try{let t=new Vt({compilerOptions:{allowJs:!0,jsx:4,module:99,target:10},skipAddingFilesFromTsConfig:!0,useInMemoryFileSystem:!0}),n=Kt(e),i=t.createSourceFile(e,n,{overwrite:!0}).getVariableDeclarations().find(a=>a.getName()==="translations")?.getInitializer();if(!i)return[];if(D.isObjectLiteralExpression(i))return _e(i);let o=i.getFirstDescendantByKind(Jt.ObjectLiteralExpression);return o?_e(o):[]}catch(t){let n=t instanceof Error?t.message:`${t}`;return I.warn(`Failed to read locales from ${e}: ${n}`),[]}},zt=async()=>{let e=await Gt({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 Lt(e)&&(G("Translation cancelled"),process.exit(0)),e},Wt=async e=>(await Bt(e,{cwd:process.cwd(),absolute:!0,nodir:!0})).sort(),Qt=async()=>{let e=j(process.cwd(),Z);try{let t=await Q(e,"utf8"),n=JSON.parse(t);return n.version!==1||!n.entries?Ee():{version:1,entries:n.entries}}catch{return Ee()}},Te=e=>{let t=j(process.cwd(),Z),n=JSON.stringify(e,null,2);kt(t,n,"utf8")},Zt=async e=>{let t=await Promise.all(e.map(async n=>[n,await Yt(n)]));return Object.fromEntries(t)},en=(e,t)=>{let n=Nt(e);return`${e.slice(0,-n.length)}.${t}${n}`},Me=(e,t)=>`${Ie(process.cwd(),e)}::${t}`,tn=(e,t,n,r,s=!1)=>{let i=[],o=0;for(let a of t){let d=n[a];for(let c of e){let u=en(a,c),l=Me(a,c),m=r.entries[l];if(!s&&m?.hash===d){o+=1;continue}i.push({locale:c,sourceFile:a,sourceHash:d,targetFile:u})}}return{tasks:i,skippedCount:o}},nn=async e=>{await Ct(Ot(e),{recursive:!0})},rn=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 i=await r.text();throw new Error(`API request failed (${r.status}): ${i}`)}let s=await r.json();if(!s.translation)throw new Error("API response did not include a translation");return s.translation},sn=async(e,t,n)=>{let r=await Q(e.sourceFile,"utf8"),s=await rn(t,r,e.locale);await nn(e.targetFile),await $t(e.targetFile,s,"utf8"),n.entries[Me(e.sourceFile,e.locale)]={hash:e.sourceHash,updatedAt:new Date().toISOString()}},ve=async(e,t)=>{Ut("Translate MDX content");let n=e??Xt,r=t.url||process.env.GEISTDOCS_TRANSLATE_URL||"https://geistdocs.com/translate",s=qt(t.config??Ht),i=await Wt(n);i.length===0&&(I.error(`No MDX files found matching pattern: ${n}`),G("Translation cancelled"),process.exit(1)),I.info(`Found ${i.length} MDX file(s) matching pattern`),s.length===0&&(s=await zt());let o=j(process.cwd(),Z),a=await Qt();await Te(a),I.info(`Using cache: ${o}`);let d=await Zt(i),{tasks:c,skippedCount:u}=tn(s,i,d,a,t.force);if(c.length===0){I.success("All translations are up to date!"),G(`Skipped ${u} file(s) (unchanged)`);return}let l=[];for(let h=0;h<c.length;h+=W)l.push(c.slice(h,h+W));I.info(`Processing ${c.length} translation(s) in ${l.length} batch(es) of up to ${W}`),u>0&&I.info(`Skipped ${u} translation(s) (unchanged)`);let m=jt();m.start("Translating content...");let f=0;for(let h of l)await Promise.all(h.map(async x=>{await sn(x,r,a),f+=1,m.message(`Translated ${f}/${c.length}: ${Ie(process.cwd(),x.targetFile)}`)})),await Te(a);m.stop("Translation complete!"),G(`Created/updated ${c.length} file(s)`)};import{access as on,copyFile as an,mkdir as De,rm as ne}from"fs/promises";import{dirname as cn,join as M}from"path";import{intro as dn,log as w,outro as B,spinner as Ae}from"@clack/prompts";import{glob as ln}from"glob";var pn=["**/*"],un=["content/docs/**"],ee=".geistdocs-tmp",gn=async(e,t)=>{let n=M(e,t);await ne(n,{recursive:!0,force:!0}),await De(n,{recursive:!0})},te=async e=>await ne(e,{recursive:!0,force:!0}),Fe=async(e,t,n)=>(await ln(e,{cwd:n,nodir:!0,dot:!0,ignore:[".git/**",...t]})).sort(),mn=async e=>{try{return await on(e),!0}catch{return!1}},fn=async(e,t,n)=>{let r=M(t,e),s=M(n,e);return await mn(r)?(await an(r,s),{success:!0}):{success:!1,error:`Source file not found: ${r}`}},hn=async(e,t)=>{let n=M(t,e);return await ne(n,{force:!0}),{success:!0}},Re=20,Pe=async(e,t,n)=>{let r=[];for(let s=0;s<e.length;s+=n){let i=e.slice(s,s+n),o=await Promise.all(i.map(t));r.push(...o)}return r},wn=async(e,t,n,r,s)=>{let i={success:[],deleted:[],failed:[]},o=[...new Set(e.map(d=>cn(M(r,d))))];s.message(`Creating ${o.length} directories...`),await Promise.all(o.map(d=>De(d,{recursive:!0}))),s.message(`Updating ${e.length} files...`);let a=await Pe(e,async d=>{let c=await fn(d,n,r);return{file:d,...c}},Re);for(let{file:d,success:c,error:u}of a)c?i.success.push(d):i.failed.push({file:d,error:u??"Unknown error"});if(t.length>0){s.message(`Deleting ${t.length} files...`);let d=await Pe(t,async c=>{try{return await hn(c,r),{file:c,success:!0}}catch(u){let l=u instanceof Error?u.message:`${u}`;return{file:c,success:!1,error:l}}},Re);for(let c of d)c.success?i.deleted.push(c.file):i.failed.push({file:c.file,error:c.error})}return i},yn=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}`)}},xn=e=>e.includes("canary")?"canary":"latest",bn=async e=>{let t=await fetch(`https://registry.npmjs.org/${encodeURIComponent(E)}`);if(!t.ok)throw new Error(`Failed to resolve ${E}@${e}`);let r=(await t.json())["dist-tags"]?.[e];if(!r)throw new Error(`Could not find dist-tag ${e} for ${E}`);return r},Sn=async e=>{let t=await R(e),n=J(t,E);if(!n)return{currentVersion:n,nextVersion:void 0,updated:!1};let r=xn(n),s=await bn(r);return n===s?{currentVersion:n,nextVersion:s,updateTag:r,updated:!1}:(O(t,E,s),await $(e,t),{currentVersion:n,nextVersion:s,updateTag:r,updated:!0})},En=async(e,t,n)=>{let r=await R(e);if(!de(r,E))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:s,nextVersion:i,updateTag:o,updated:a}=await Sn(e);if(!a)return w.success(s?`@vercel/geistdocs is already at ${i} (${o}).`:"No package version update was needed."),B("Package-based site is already up to date."),!0;w.info(`Bumping ${E} from ${s} to ${i} (${o})`);let d=Ae();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},_n=async(e,t,n,r,s)=>{let i=M(e,ee),o=Ae(),a=s?.sync?i:t;o.start("Preparing template snapshot..."),s?.sync&&(await gn(e,ee),await N(i)),o.message("Scanning for files...");let d=await Fe(n,r,a),c=[];if(s?.sync){o.message("Comparing with local files...");let l=await Fe(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."),s?.sync&&await te(i),B("Update cancelled.");return}w.info(`Patterns: ${n.length}`),w.info(`Files to update: ${d.length}`),s?.sync&&w.info(`Files to delete: ${c.length}`),o.start("Updating files...");let u=await wn(d,c,a,e,o);s?.sync&&(o.message("Cleaning up..."),await te(i)),o.stop("Update complete!"),yn(u),B("Please review and test the changes carefully.")},ke=async(e,t)=>{let n=process.cwd(),r=H(),s=e&&e.length>0?e:pn,i=e&&e.length>0?[]:un;try{if(dn("Let's update your Geistdocs project!"),await En(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 _n(n,r,s,i,t)}catch(o){let a=o instanceof Error?o.message:`${o}`;try{await te(M(n,ee))}catch{}w.error(`Failed to update project: ${a}`),process.exit(1)}};F.name("geistdocs").description("CLI for Geistdocs projects").version("1.28.0","-v, --version","Output the current version");F.command("init").description("Initialize a new Geistdocs project").option("--name <name>","Name of the project").option("--disable-git","Disable git initialization").action(le);F.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(ke);F.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(ve);var Tn=F.command("search").description("Manage the external search index used by Ask AI");Tn.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(Se);await F.parseAsync(process.argv).catch(e=>{console.error(e instanceof Error?e.message:e),process.exitCode=1});
7
+ `));let o=await xe({client:pe({apiBaseUrl:process.env.MXBAI_BASE_URL,apiKey:r,storeId:s}),manifest:i,...Dt(n)});console.log(`Geistdocs search sync complete: ${o.uploaded} uploaded, ${o.deleted} deleted, ${o.skipped} unchanged.`)};import{readFileSync as At,writeFileSync as kt}from"fs";import{mkdir as Ct,readFile as Q,writeFile as $t}from"fs/promises";import{dirname as Ot,extname as Nt,relative as Ie,resolve as j}from"path";import{intro as Ut,isCancel as Lt,log as I,multiselect as Gt,outro as G,spinner as jt}from"@clack/prompts";import{glob as Bt}from"glob";import{Node as D,Project as Vt,SyntaxKind as Jt}from"ts-morph";var Ht="geistdocs.tsx",Xt="content/docs/**/*.mdx",Z=".translation-cache.json",W=8,Ee=()=>({version:1,entries:{}}),Yt=async e=>{let t=await Q(e),{createHash:n}=await import("crypto");return n("sha256").update(t).digest("hex")},Kt=e=>{let t=j(process.cwd(),e);return At(t,"utf8")},_e=e=>D.isObjectLiteralExpression(e)?e.getProperties().flatMap(t=>{if(D.isPropertyAssignment(t)){let n=t.getNameNode();if(D.isIdentifier(n)||D.isStringLiteral(n))return[n.getText().replaceAll(/['"]/g,"")]}return[]}).filter(Boolean):[],qt=e=>{try{let t=new Vt({compilerOptions:{allowJs:!0,jsx:4,module:99,target:10},skipAddingFilesFromTsConfig:!0,useInMemoryFileSystem:!0}),n=Kt(e),i=t.createSourceFile(e,n,{overwrite:!0}).getVariableDeclarations().find(a=>a.getName()==="translations")?.getInitializer();if(!i)return[];if(D.isObjectLiteralExpression(i))return _e(i);let o=i.getFirstDescendantByKind(Jt.ObjectLiteralExpression);return o?_e(o):[]}catch(t){let n=t instanceof Error?t.message:`${t}`;return I.warn(`Failed to read locales from ${e}: ${n}`),[]}},zt=async()=>{let e=await Gt({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 Lt(e)&&(G("Translation cancelled"),process.exit(0)),e},Wt=async e=>(await Bt(e,{cwd:process.cwd(),absolute:!0,nodir:!0})).sort(),Qt=async()=>{let e=j(process.cwd(),Z);try{let t=await Q(e,"utf8"),n=JSON.parse(t);return n.version!==1||!n.entries?Ee():{version:1,entries:n.entries}}catch{return Ee()}},Te=e=>{let t=j(process.cwd(),Z),n=JSON.stringify(e,null,2);kt(t,n,"utf8")},Zt=async e=>{let t=await Promise.all(e.map(async n=>[n,await Yt(n)]));return Object.fromEntries(t)},en=(e,t)=>{let n=Nt(e);return`${e.slice(0,-n.length)}.${t}${n}`},Me=(e,t)=>`${Ie(process.cwd(),e)}::${t}`,tn=(e,t,n,r,s=!1)=>{let i=[],o=0;for(let a of t){let d=n[a];for(let c of e){let u=en(a,c),l=Me(a,c),m=r.entries[l];if(!s&&m?.hash===d){o+=1;continue}i.push({locale:c,sourceFile:a,sourceHash:d,targetFile:u})}}return{tasks:i,skippedCount:o}},nn=async e=>{await Ct(Ot(e),{recursive:!0})},rn=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 i=await r.text();throw new Error(`API request failed (${r.status}): ${i}`)}let s=await r.json();if(!s.translation)throw new Error("API response did not include a translation");return s.translation},sn=async(e,t,n)=>{let r=await Q(e.sourceFile,"utf8"),s=await rn(t,r,e.locale);await nn(e.targetFile),await $t(e.targetFile,s,"utf8"),n.entries[Me(e.sourceFile,e.locale)]={hash:e.sourceHash,updatedAt:new Date().toISOString()}},ve=async(e,t)=>{Ut("Translate MDX content");let n=e??Xt,r=t.url||process.env.GEISTDOCS_TRANSLATE_URL||"https://geistdocs.com/translate",s=qt(t.config??Ht),i=await Wt(n);i.length===0&&(I.error(`No MDX files found matching pattern: ${n}`),G("Translation cancelled"),process.exit(1)),I.info(`Found ${i.length} MDX file(s) matching pattern`),s.length===0&&(s=await zt());let o=j(process.cwd(),Z),a=await Qt();await Te(a),I.info(`Using cache: ${o}`);let d=await Zt(i),{tasks:c,skippedCount:u}=tn(s,i,d,a,t.force);if(c.length===0){I.success("All translations are up to date!"),G(`Skipped ${u} file(s) (unchanged)`);return}let l=[];for(let h=0;h<c.length;h+=W)l.push(c.slice(h,h+W));I.info(`Processing ${c.length} translation(s) in ${l.length} batch(es) of up to ${W}`),u>0&&I.info(`Skipped ${u} translation(s) (unchanged)`);let m=jt();m.start("Translating content...");let f=0;for(let h of l)await Promise.all(h.map(async x=>{await sn(x,r,a),f+=1,m.message(`Translated ${f}/${c.length}: ${Ie(process.cwd(),x.targetFile)}`)})),await Te(a);m.stop("Translation complete!"),G(`Created/updated ${c.length} file(s)`)};import{access as on,copyFile as an,mkdir as De,rm as ne}from"fs/promises";import{dirname as cn,join as M}from"path";import{intro as dn,log as w,outro as B,spinner as Ae}from"@clack/prompts";import{glob as ln}from"glob";var pn=["**/*"],un=["content/docs/**"],ee=".geistdocs-tmp",gn=async(e,t)=>{let n=M(e,t);await ne(n,{recursive:!0,force:!0}),await De(n,{recursive:!0})},te=async e=>await ne(e,{recursive:!0,force:!0}),Fe=async(e,t,n)=>(await ln(e,{cwd:n,nodir:!0,dot:!0,ignore:[".git/**",...t]})).sort(),mn=async e=>{try{return await on(e),!0}catch{return!1}},fn=async(e,t,n)=>{let r=M(t,e),s=M(n,e);return await mn(r)?(await an(r,s),{success:!0}):{success:!1,error:`Source file not found: ${r}`}},hn=async(e,t)=>{let n=M(t,e);return await ne(n,{force:!0}),{success:!0}},Re=20,Pe=async(e,t,n)=>{let r=[];for(let s=0;s<e.length;s+=n){let i=e.slice(s,s+n),o=await Promise.all(i.map(t));r.push(...o)}return r},wn=async(e,t,n,r,s)=>{let i={success:[],deleted:[],failed:[]},o=[...new Set(e.map(d=>cn(M(r,d))))];s.message(`Creating ${o.length} directories...`),await Promise.all(o.map(d=>De(d,{recursive:!0}))),s.message(`Updating ${e.length} files...`);let a=await Pe(e,async d=>{let c=await fn(d,n,r);return{file:d,...c}},Re);for(let{file:d,success:c,error:u}of a)c?i.success.push(d):i.failed.push({file:d,error:u??"Unknown error"});if(t.length>0){s.message(`Deleting ${t.length} files...`);let d=await Pe(t,async c=>{try{return await hn(c,r),{file:c,success:!0}}catch(u){let l=u instanceof Error?u.message:`${u}`;return{file:c,success:!1,error:l}}},Re);for(let c of d)c.success?i.deleted.push(c.file):i.failed.push({file:c.file,error:c.error})}return i},yn=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}`)}},xn=e=>e.includes("canary")?"canary":"latest",bn=async e=>{let t=await fetch(`https://registry.npmjs.org/${encodeURIComponent(E)}`);if(!t.ok)throw new Error(`Failed to resolve ${E}@${e}`);let r=(await t.json())["dist-tags"]?.[e];if(!r)throw new Error(`Could not find dist-tag ${e} for ${E}`);return r},Sn=async e=>{let t=await R(e),n=J(t,E);if(!n)return{currentVersion:n,nextVersion:void 0,updated:!1};let r=xn(n),s=await bn(r);return n===s?{currentVersion:n,nextVersion:s,updateTag:r,updated:!1}:(O(t,E,s),await $(e,t),{currentVersion:n,nextVersion:s,updateTag:r,updated:!0})},En=async(e,t,n)=>{let r=await R(e);if(!de(r,E))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:s,nextVersion:i,updateTag:o,updated:a}=await Sn(e);if(!a)return w.success(s?`@vercel/geistdocs is already at ${i} (${o}).`:"No package version update was needed."),B("Package-based site is already up to date."),!0;w.info(`Bumping ${E} from ${s} to ${i} (${o})`);let d=Ae();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},_n=async(e,t,n,r,s)=>{let i=M(e,ee),o=Ae(),a=s?.sync?i:t;o.start("Preparing template snapshot..."),s?.sync&&(await gn(e,ee),await N(i)),o.message("Scanning for files...");let d=await Fe(n,r,a),c=[];if(s?.sync){o.message("Comparing with local files...");let l=await Fe(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."),s?.sync&&await te(i),B("Update cancelled.");return}w.info(`Patterns: ${n.length}`),w.info(`Files to update: ${d.length}`),s?.sync&&w.info(`Files to delete: ${c.length}`),o.start("Updating files...");let u=await wn(d,c,a,e,o);s?.sync&&(o.message("Cleaning up..."),await te(i)),o.stop("Update complete!"),yn(u),B("Please review and test the changes carefully.")},ke=async(e,t)=>{let n=process.cwd(),r=H(),s=e&&e.length>0?e:pn,i=e&&e.length>0?[]:un;try{if(dn("Let's update your Geistdocs project!"),await En(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 _n(n,r,s,i,t)}catch(o){let a=o instanceof Error?o.message:`${o}`;try{await te(M(n,ee))}catch{}w.error(`Failed to update project: ${a}`),process.exit(1)}};F.name("geistdocs").description("CLI for Geistdocs projects").version("1.28.1","-v, --version","Output the current version");F.command("init").description("Initialize a new Geistdocs project").option("--name <name>","Name of the project").option("--disable-git","Disable git initialization").action(le);F.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(ke);F.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(ve);var Tn=F.command("search").description("Manage the external search index used by Ask AI");Tn.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(Se);await F.parseAsync(process.argv).catch(e=>{console.error(e instanceof Error?e.message:e),process.exitCode=1});
@@ -0,0 +1,2 @@
1
+ export declare const getMarkdownDecision: (request: Request) => import("@vercel/agent-readability").ShouldServeMarkdownResult;
2
+ //# sourceMappingURL=markdown-negotiation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"markdown-negotiation.d.ts","sourceRoot":"","sources":["../../src/internal/markdown-negotiation.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,mBAAmB,GAAI,SAAS,OAAO,kEACgB,CAAC"}
@@ -0,0 +1,3 @@
1
+ import { shouldServeMarkdown } from "@vercel/agent-readability";
2
+ const MARKDOWN_MEDIA_TYPES = ["text/markdown", "text/x-markdown", "text/plain"];
3
+ export const getMarkdownDecision = (request) => shouldServeMarkdown(request, { mediaTypes: MARKDOWN_MEDIA_TYPES });
@@ -1 +1 @@
1
- {"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,UAAU,CAAC;AAQlB,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,iBAAiB,GACjB,WAAW,GACX,IAAI,CAAC;AAET,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,CAAC,EAAE,QAAQ,GAAG,mBAAmB,GAAG,eAAe,CAAC;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,KAAK,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAC;AAEnD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;IACnB,EAAE,EACE,IAAI,MAAM,EAAE,GACZ,CAAC,CAAC,OAAO,EAAE;QACT,eAAe,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,KAAK,IAAI,MAAM,EAAE,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,wBAAwB,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACpD,KAAK,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IAClD,MAAM,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IACnD,MAAM,EAAE,IAAI,CACV,eAAe,EACf,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,iBAAiB,GAAG,cAAc,CACtE,CAAC;IACF,sFAAsF;IACtF,gBAAgB,CAAC,EACb,OAAO,GACP,CAAC,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC;IACnE,cAAc,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAC1C,oBAAoB,CAAC,EAAE,CACrB,KAAK,EAAE,yBAAyB,KAC7B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B;AAoKD,eAAO,MAAM,WAAW,GAAI,8GAQzB,kBAAkB,MAgTL,SAAS,WAAW,EAAE,SAAS,cAAc,sBAoD5D,CAAC"}
1
+ {"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,UAAU,CAAC;AASlB,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,iBAAiB,GACjB,WAAW,GACX,IAAI,CAAC;AAET,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,CAAC,EAAE,QAAQ,GAAG,mBAAmB,GAAG,eAAe,CAAC;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,KAAK,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAC;AAEnD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;IACnB,EAAE,EACE,IAAI,MAAM,EAAE,GACZ,CAAC,CAAC,OAAO,EAAE;QACT,eAAe,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,KAAK,IAAI,MAAM,EAAE,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,wBAAwB,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACpD,KAAK,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IAClD,MAAM,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IACnD,MAAM,EAAE,IAAI,CACV,eAAe,EACf,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,iBAAiB,GAAG,cAAc,CACtE,CAAC;IACF,sFAAsF;IACtF,gBAAgB,CAAC,EACb,OAAO,GACP,CAAC,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC;IACnE,cAAc,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAC1C,oBAAoB,CAAC,EAAE,CACrB,KAAK,EAAE,yBAAyB,KAC7B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC3B;AAoKD,eAAO,MAAM,WAAW,GAAI,8GAQzB,kBAAkB,MAqRL,SAAS,WAAW,EAAE,SAAS,cAAc,sBAoD5D,CAAC"}
package/dist/proxy.js CHANGED
@@ -1,10 +1,10 @@
1
- import { applyMarkdownHeaders, createNotFoundResponse, isAIAgent, } from "@vercel/agent-readability";
1
+ import { applyMarkdownHeaders, createNotFoundResponse, } from "@vercel/agent-readability";
2
2
  import { defineI18n } from "fumadocs-core/i18n";
3
3
  import { createI18nMiddleware } from "fumadocs-core/i18n/middleware";
4
- import { isMarkdownPreferred } from "fumadocs-core/negotiation";
5
4
  import { NextResponse, } from "next/server";
6
5
  import { getPublicPath, normalizeBasePath, } from "./config";
7
6
  import { matchesAppRoute, parseAppRouteManifest, } from "./internal/app-route-manifest";
7
+ import { getMarkdownDecision } from "./internal/markdown-negotiation";
8
8
  import { renderNotFoundMarkdown } from "./internal/not-found";
9
9
  import { localizeHref } from "./localize-href";
10
10
  const MDX_EXTENSION_PATTERN = /\.mdx?$/;
@@ -230,27 +230,16 @@ export const createProxy = ({ additionalMarkdownRoutes, after, before, config, m
230
230
  trackPath,
231
231
  });
232
232
  };
233
- const handleAgentRewrite = (request, context, pathname, language, trackPath) => {
234
- const agentResult = isAIAgent(request);
235
- if (!agentResult.detected || isMarkdownPreferred(request)) {
233
+ const handleNegotiatedMarkdownRequest = (request, context, pathname, language, trackPath, decision) => {
234
+ if (!decision.serve) {
236
235
  return null;
237
236
  }
238
- const response = tryMarkdownRewrite(request, context, pathname, language, {
239
- requestType: "agent-rewrite",
240
- detectionMethod: agentResult.method,
237
+ return tryMarkdownRewrite(request, context, pathname, language, {
238
+ requestType: decision.reason === "agent" ? "agent-rewrite" : "header-negotiated",
239
+ detectionMethod: decision.reason === "agent" ? decision.detection.method : undefined,
241
240
  trackPath,
242
241
  });
243
- if (response) {
244
- return response;
245
- }
246
- return createNotFoundResponse(pathname);
247
242
  };
248
- const handlePreferredMarkdownRequest = (request, context, pathname, language, trackPath) => isMarkdownPreferred(request)
249
- ? tryMarkdownRewrite(request, context, pathname, language, {
250
- requestType: "header-negotiated",
251
- trackPath,
252
- })
253
- : null;
254
243
  const handleMarkdownNegotiation = (request, context, pathname) => {
255
244
  if (!MARKDOWN_REQUEST_METHODS.has(request.method)) {
256
245
  return null;
@@ -264,19 +253,16 @@ export const createProxy = ({ additionalMarkdownRoutes, after, before, config, m
264
253
  if (extensionResponse) {
265
254
  return extensionResponse;
266
255
  }
256
+ const markdownDecision = getMarkdownDecision(request);
267
257
  if (resolveMarkdownRewrite(localized.pathname, localized.language) &&
268
258
  !localized.pathname.includes("/llms.mdx/")) {
269
- const agentResponse = handleAgentRewrite(request, context, localized.pathname, localized.language, pathname);
270
- if (agentResponse) {
271
- return agentResponse;
259
+ const negotiatedResponse = handleNegotiatedMarkdownRequest(request, context, localized.pathname, localized.language, pathname, markdownDecision);
260
+ if (negotiatedResponse) {
261
+ return negotiatedResponse;
272
262
  }
273
263
  }
274
- const preferredResponse = handlePreferredMarkdownRequest(request, context, localized.pathname, localized.language, pathname);
275
- if (preferredResponse) {
276
- return preferredResponse;
277
- }
278
264
  return !RESOURCE_EXTENSION_PATTERN.test(localized.pathname) &&
279
- (isMarkdownPreferred(request) || isAIAgent(request).detected) &&
265
+ markdownDecision.serve &&
280
266
  shouldCreateMarkdownNotFound(localized.pathname, localized.language, pathname)
281
267
  ? createMarkdownNotFound(pathname, localized.language)
282
268
  : null;
@@ -1 +1 @@
1
- {"version":3,"file":"not-found.d.ts","sourceRoot":"","sources":["../../src/routes/not-found.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,WAAW,CAAC;AAIhE,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,IAAI,CACV,eAAe,EACf,UAAU,GAAG,iBAAiB,GAAG,cAAc,CAChD,CAAC;CACH;AASD,eAAO,MAAM,mBAAmB,GAAI,YAAY,0BAA0B;mBAE7D,WAAW,cACR;QAAE,MAAM,EAAE,OAAO,CAAC;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;CA+DrD,CAAC"}
1
+ {"version":3,"file":"not-found.d.ts","sourceRoot":"","sources":["../../src/routes/not-found.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,WAAW,CAAC;AAKhE,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,IAAI,CACV,eAAe,EACf,UAAU,GAAG,iBAAiB,GAAG,cAAc,CAChD,CAAC;CACH;AASD,eAAO,MAAM,mBAAmB,GAAI,YAAY,0BAA0B;mBAE7D,WAAW,cACR;QAAE,MAAM,EAAE,OAAO,CAAC;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;CA+DrD,CAAC"}
@@ -1,6 +1,6 @@
1
- import { createNotFoundResponse, isAIAgent } from "@vercel/agent-readability";
2
- import { isMarkdownPreferred } from "fumadocs-core/negotiation";
1
+ import { createNotFoundResponse } from "@vercel/agent-readability";
3
2
  import { getPublicPath } from "../config";
3
+ import { getMarkdownDecision } from "../internal/markdown-negotiation";
4
4
  import { renderNotFoundMarkdown } from "../internal/not-found";
5
5
  import { localizeHref } from "../localize-href";
6
6
  const escapeHtml = (value) => value
@@ -24,7 +24,7 @@ export const createNotFoundRoute = ({ config }) => {
24
24
  const sitemapUrl = publicPath("/sitemap.md");
25
25
  const llmsUrl = publicPath("/llms.txt");
26
26
  const vary = "Accept, User-Agent, Signature-Agent";
27
- if (isMarkdownPreferred(request) || isAIAgent(request).detected) {
27
+ if (getMarkdownDecision(request).serve) {
28
28
  return createNotFoundResponse(request.nextUrl.pathname, {
29
29
  headers: {
30
30
  "Cache-Control": "private, no-store",
package/docs/agents.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Docs
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 1.28.0 so agents can understand the installed package without web access.
3
+ These docs are bundled with `@vercel/geistdocs` 1.28.1 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` 1.28.0.
3
+ These docs are bundled with `@vercel/geistdocs` 1.28.1.
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
@@ -2414,9 +2414,15 @@ export const config = {
2414
2414
 
2415
2415
  The package keeps `llms.txt`, `sitemap.md`, `agents.md`, MCP discovery, and RSS out of root page-Markdown negotiation. Continue to exclude site-specific application and API routes with the matcher or a `before` hook. A root Markdown page is exposed as `/index.md`, or `<basePath>/index.md` publicly.
2416
2416
 
2417
+ ## Negotiate HTML and Markdown
2418
+
2419
+ Explicit `Accept` preferences determine the response for extensionless mapped URLs. Geistdocs recognizes `text/markdown`, `text/x-markdown`, and `text/plain` as Markdown media types and compares their quality and specificity with HTML media types. An explicit HTML preference or Markdown with `q=0` continues to the app's normal HTML handling.
2420
+
2421
+ Agent detection acts as a fallback when `Accept` is missing or does not distinguish HTML from Markdown. Explicit `.md` and `.mdx` URLs always request Markdown, even when the client usually prefers HTML. Geistdocs does not return `406 Not Acceptable` when Markdown is not selected.
2422
+
2417
2423
  ## Recover unmatched Markdown requests
2418
2424
 
2419
- `createGeistdocs` in `next.config.ts` generates a lightweight manifest from App Router pages and route handlers. When `agent` is enabled, `createProxy` uses this manifest to return a Markdown 404 only when a `GET` or `HEAD` request matches neither a Markdown mapping nor an application route.
2425
+ `createGeistdocs` in `next.config.ts` generates a lightweight manifest from App Router pages and route handlers. When `agent` is enabled, `createProxy` uses this manifest to return a Markdown 404 only when an eligible Markdown `GET` or `HEAD` request matches neither a Markdown mapping nor an application route. Requests that prefer HTML keep the app's normal HTML recovery, including requests from detected agents.
2420
2426
 
2421
2427
  The manifest contains route patterns, not page modules or content. Static, dynamic, catch-all, optional catch-all, grouped, and localized routes continue to Next.js. Root catch-all pages are treated as potentially valid, so the app remains responsible for their 404 behavior. The package's own `[...not-found]` route handler is excluded so it does not claim every path.
2422
2428
 
@@ -2955,7 +2961,7 @@ Set `notFound.getPageMarkdownUrl` as well when suggested pages use a custom app-
2955
2961
 
2956
2962
  ### Unmatched application paths
2957
2963
 
2958
- When `agent` is enabled, `createGeistdocs` scans App Router pages and route handlers during `next dev` and `next build`. `createProxy` uses that generated manifest to distinguish valid application routes from unknown paths. Valid routes continue to the app's HTML or route-handler response. Unknown Markdown or detected-agent `GET` and `HEAD` requests receive a concise 404 with links to the docs, `sitemap.md`, and `llms.txt`.
2964
+ When `agent` is enabled, `createGeistdocs` scans App Router pages and route handlers during `next dev` and `next build`. `createProxy` uses that generated manifest to distinguish valid application routes from unknown paths. Valid routes continue to the app's HTML or route-handler response. Unknown `GET` and `HEAD` requests receive a concise Markdown 404 when the client prefers Markdown or when agent detection applies as a fallback. An explicit HTML preference keeps the app's normal HTML recovery.
2959
2965
 
2960
2966
  Markdown mappings take precedence over generated app routes, so a route that has both HTML and Markdown continues to negotiate Markdown. Dynamic app routes are treated as potentially valid; the app remains responsible for returning its own 404 when a specific slug does not exist.
2961
2967
 
@@ -233,5 +233,5 @@
233
233
  }
234
234
  ],
235
235
  "source": "apps/template/content/docs",
236
- "version": "1.28.0"
236
+ "version": "1.28.1"
237
237
  }
package/docs/pages/md.md CHANGED
@@ -111,7 +111,7 @@ Set `notFound.getPageMarkdownUrl` as well when suggested pages use a custom app-
111
111
 
112
112
  ### Unmatched application paths
113
113
 
114
- When `agent` is enabled, `createGeistdocs` scans App Router pages and route handlers during `next dev` and `next build`. `createProxy` uses that generated manifest to distinguish valid application routes from unknown paths. Valid routes continue to the app's HTML or route-handler response. Unknown Markdown or detected-agent `GET` and `HEAD` requests receive a concise 404 with links to the docs, `sitemap.md`, and `llms.txt`.
114
+ When `agent` is enabled, `createGeistdocs` scans App Router pages and route handlers during `next dev` and `next build`. `createProxy` uses that generated manifest to distinguish valid application routes from unknown paths. Valid routes continue to the app's HTML or route-handler response. Unknown `GET` and `HEAD` requests receive a concise Markdown 404 when the client prefers Markdown or when agent detection applies as a fallback. An explicit HTML preference keeps the app's normal HTML recovery.
115
115
 
116
116
  Markdown mappings take precedence over generated app routes, so a route that has both HTML and Markdown continues to negotiate Markdown. Dynamic app routes are treated as potentially valid; the app remains responsible for returning its own 404 when a specific slug does not exist.
117
117
 
@@ -192,9 +192,15 @@ export const config = {
192
192
 
193
193
  The package keeps `llms.txt`, `sitemap.md`, `agents.md`, MCP discovery, and RSS out of root page-Markdown negotiation. Continue to exclude site-specific application and API routes with the matcher or a `before` hook. A root Markdown page is exposed as `/index.md`, or `<basePath>/index.md` publicly.
194
194
 
195
+ ## Negotiate HTML and Markdown
196
+
197
+ Explicit `Accept` preferences determine the response for extensionless mapped URLs. Geistdocs recognizes `text/markdown`, `text/x-markdown`, and `text/plain` as Markdown media types and compares their quality and specificity with HTML media types. An explicit HTML preference or Markdown with `q=0` continues to the app's normal HTML handling.
198
+
199
+ Agent detection acts as a fallback when `Accept` is missing or does not distinguish HTML from Markdown. Explicit `.md` and `.mdx` URLs always request Markdown, even when the client usually prefers HTML. Geistdocs does not return `406 Not Acceptable` when Markdown is not selected.
200
+
195
201
  ## Recover unmatched Markdown requests
196
202
 
197
- `createGeistdocs` in `next.config.ts` generates a lightweight manifest from App Router pages and route handlers. When `agent` is enabled, `createProxy` uses this manifest to return a Markdown 404 only when a `GET` or `HEAD` request matches neither a Markdown mapping nor an application route.
203
+ `createGeistdocs` in `next.config.ts` generates a lightweight manifest from App Router pages and route handlers. When `agent` is enabled, `createProxy` uses this manifest to return a Markdown 404 only when an eligible Markdown `GET` or `HEAD` request matches neither a Markdown mapping nor an application route. Requests that prefer HTML keep the app's normal HTML recovery, including requests from detected agents.
198
204
 
199
205
  The manifest contains route patterns, not page modules or content. Static, dynamic, catch-all, optional catch-all, grouped, and localized routes continue to Next.js. Root catch-all pages are treated as potentially valid, so the app remains responsible for their 404 behavior. The package's own `[...not-found]` route handler is excluded so it does not claim every path.
200
206
 
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": "1.28.0",
4
+ "version": "1.28.1",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -109,7 +109,7 @@ Set `notFound.getPageMarkdownUrl` as well when suggested pages use a custom app-
109
109
 
110
110
  ### Unmatched application paths
111
111
 
112
- When `agent` is enabled, `createGeistdocs` scans App Router pages and route handlers during `next dev` and `next build`. `createProxy` uses that generated manifest to distinguish valid application routes from unknown paths. Valid routes continue to the app's HTML or route-handler response. Unknown Markdown or detected-agent `GET` and `HEAD` requests receive a concise 404 with links to the docs, `sitemap.md`, and `llms.txt`.
112
+ When `agent` is enabled, `createGeistdocs` scans App Router pages and route handlers during `next dev` and `next build`. `createProxy` uses that generated manifest to distinguish valid application routes from unknown paths. Valid routes continue to the app's HTML or route-handler response. Unknown `GET` and `HEAD` requests receive a concise Markdown 404 when the client prefers Markdown or when agent detection applies as a fallback. An explicit HTML preference keeps the app's normal HTML recovery.
113
113
 
114
114
  Markdown mappings take precedence over generated app routes, so a route that has both HTML and Markdown continues to negotiate Markdown. Dynamic app routes are treated as potentially valid; the app remains responsible for returning its own 404 when a specific slug does not exist.
115
115
 
@@ -65,7 +65,7 @@ const proxy = createProxy({
65
65
 
66
66
  ## Markdown 路由映射
67
67
 
68
- `markdownRoutes` 将公开页面 URL 映射到返回 Markdown 的 App Router handler。包仍然通过 route helpers 服务 `/llms.txt` 和单页 Markdown;proxy 使用这些映射处理 `.md`、`.mdx`、`Accept: text/markdown` 和 AI-agent 请求。
68
+ `markdownRoutes` 将公开页面 URL 映射到返回 Markdown 的 App Router handler。包仍然通过 route helpers 服务 `/llms.txt` 和单页 Markdown;proxy 使用这些映射处理 `.md`、`.mdx`、`Accept: text/markdown` 和 AI-agent 请求。对于没有扩展名的 URL,明确的 `Accept` 偏好优先于 agent 检测。请求 HTML 或使用 `q=0` 拒绝 Markdown 时,proxy 会继续正常的 HTML 处理。
69
69
 
70
70
  ```ts title="proxy.ts"
71
71
  const proxy = createProxy({
@@ -190,9 +190,15 @@ export const config = {
190
190
 
191
191
  The package keeps `llms.txt`, `sitemap.md`, `agents.md`, MCP discovery, and RSS out of root page-Markdown negotiation. Continue to exclude site-specific application and API routes with the matcher or a `before` hook. A root Markdown page is exposed as `/index.md`, or `<basePath>/index.md` publicly.
192
192
 
193
+ ## Negotiate HTML and Markdown
194
+
195
+ Explicit `Accept` preferences determine the response for extensionless mapped URLs. Geistdocs recognizes `text/markdown`, `text/x-markdown`, and `text/plain` as Markdown media types and compares their quality and specificity with HTML media types. An explicit HTML preference or Markdown with `q=0` continues to the app's normal HTML handling.
196
+
197
+ Agent detection acts as a fallback when `Accept` is missing or does not distinguish HTML from Markdown. Explicit `.md` and `.mdx` URLs always request Markdown, even when the client usually prefers HTML. Geistdocs does not return `406 Not Acceptable` when Markdown is not selected.
198
+
193
199
  ## Recover unmatched Markdown requests
194
200
 
195
- `createGeistdocs` in `next.config.ts` generates a lightweight manifest from App Router pages and route handlers. When `agent` is enabled, `createProxy` uses this manifest to return a Markdown 404 only when a `GET` or `HEAD` request matches neither a Markdown mapping nor an application route.
201
+ `createGeistdocs` in `next.config.ts` generates a lightweight manifest from App Router pages and route handlers. When `agent` is enabled, `createProxy` uses this manifest to return a Markdown 404 only when an eligible Markdown `GET` or `HEAD` request matches neither a Markdown mapping nor an application route. Requests that prefer HTML keep the app's normal HTML recovery, including requests from detected agents.
196
202
 
197
203
  The manifest contains route patterns, not page modules or content. Static, dynamic, catch-all, optional catch-all, grouped, and localized routes continue to Next.js. Root catch-all pages are treated as potentially valid, so the app remains responsible for their 404 behavior. The package's own `[...not-found]` route handler is excluded so it does not claim every path.
198
204
 
@@ -18,7 +18,7 @@
18
18
  "@streamdown/code": "^1.0.1",
19
19
  "@vercel/agent-readability": "^0.7.0",
20
20
  "@vercel/analytics": "^1.6.1",
21
- "@vercel/geistdocs": "1.28.0",
21
+ "@vercel/geistdocs": "1.28.1",
22
22
  "@vercel/speed-insights": "^1.3.1",
23
23
  "ai": "^6.0.132",
24
24
  "class-variance-authority": "^0.7.1",