@vercel/geistdocs 1.15.3 → 1.15.4

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
@@ -1,3 +1,3 @@
1
1
  #!/usr/bin/env node
2
2
  import{program as T}from"commander";import{access as ce,copyFile as le}from"fs/promises";import{join as pe}from"path";import{cancel as de,intro as ge,isCancel as ue,log as fe,outro as me,spinner as he,text as we}from"@clack/prompts";import{spawn as te}from"child_process";import{readFileSync as se}from"fs";import{cp as ne,readFile as ae,rename as re,writeFile as ie}from"fs/promises";import{join as $}from"path";import{fileURLToPath as oe}from"url";var g="@vercel/geistdocs",m=(e,t=[],s={})=>new Promise((n,a)=>{let r=te(e,t,{stdio:"inherit",...s});r.on("error",a),r.on("close",i=>{if(i===0){n();return}a(new Error(`Command failed with exit code ${i}: ${[e,...t].join(" ")}`))})}),A=["dependencies","devDependencies","optionalDependencies","peerDependencies"],_=()=>JSON.parse(se(new URL("../../package.json",import.meta.url),"utf8")).version,P=async e=>{let t=$(e,"package.json"),s=await ae(t,"utf8");return JSON.parse(s)},x=async(e,t)=>{let s=$(e,"package.json");await ie(s,`${JSON.stringify(t,null,2)}
3
- `,"utf8")},R=(e,t)=>{for(let s of A){let n=e[s];if(n&&t in n)return n[t]}},V=(e,t)=>!!R(e,t),b=(e,t,s)=>{let n=!1;for(let a of A){let r=e[a];r&&t in r&&(r[t]=s,n=!0)}return n},j=()=>oe(new URL("../../template",import.meta.url)),F=async e=>{await ne(j(),e,{recursive:!0});let t=$(e,".gitignore"),s=$(e,"_gitignore");try{await re(s,t)}catch{}};var ye=async e=>{await F(e)},Pe=async e=>{try{return await ce(e),!0}catch{return!1}},ve=async()=>{await Pe(".env.example")&&await le(".env.example",".env.local")},Te=async e=>{let t=await P(e),s=_();return b(t,g,s)?(await x(e,t),!0):!1},ke=async e=>{await m("pnpm",["install"],{cwd:e,env:process.env,stdio:"inherit"})},$e=async e=>{await m("git",["init"],{cwd:e,env:process.env,stdio:"inherit"}),await m("git",["add","."],{cwd:e,env:process.env,stdio:"inherit"}),await m("git",["commit","-m","\u2728 Initial commit"],{cwd:e,env:process.env,stdio:"inherit"})},xe=async()=>{let e=await we({message:"What is your project named?",placeholder:"my-app",validate(t){if(t.length===0)return"Please enter a project name."}});return ue(e)&&(de("Operation cancelled."),process.exit(0)),e.toString()},G=async e=>{try{ge("Let's start a Geistdocs project!");let t=process.cwd(),s=e.name||await xe(),n=he(),a=pe(t,s);n.start("Copying bundled template..."),await ye(s),n.message("Setting up environment variables..."),process.chdir(a),await ve(),n.message("Rewriting package dependency versions..."),await Te(a),n.message("Installing dependencies..."),await ke(a),e.disableGit||(n.message("Initializing Git repository..."),await $e(a)),n.stop("Project initialized successfully!"),me("Run `pnpm dev` to start the development server.")}catch(t){let s=t instanceof Error?t.message:`Failed to initialize project: ${t}`;fe.error(s),process.exit(1)}};import{readFileSync as be,writeFileSync as Fe}from"fs";import{mkdir as De,readFile as N,writeFile as Se}from"fs/promises";import{dirname as Ce,extname as Re,relative as M,resolve as S}from"path";import{intro as je,isCancel as Ee,log as h,multiselect as Ne,outro as D,spinner as Ue}from"@clack/prompts";import{glob as Oe}from"glob";import{Node as v,Project as Ie,SyntaxKind as Je}from"ts-morph";var Le="geistdocs.tsx",Ae="content/docs/**/*.mdx",U=".translation-cache.json",E=8,B=()=>({version:1,entries:{}}),_e=async e=>{let t=await N(e),{createHash:s}=await import("crypto");return s("sha256").update(t).digest("hex")},Ve=e=>{let t=S(process.cwd(),e);return be(t,"utf8")},z=e=>v.isObjectLiteralExpression(e)?e.getProperties().flatMap(t=>{if(v.isPropertyAssignment(t)){let s=t.getNameNode();if(v.isIdentifier(s)||v.isStringLiteral(s))return[s.getText().replaceAll(/['"]/g,"")]}return[]}).filter(Boolean):[],Ge=e=>{try{let t=new Ie({compilerOptions:{allowJs:!0,jsx:4,module:99,target:10},skipAddingFilesFromTsConfig:!0,useInMemoryFileSystem:!0}),s=Ve(e),r=t.createSourceFile(e,s,{overwrite:!0}).getVariableDeclarations().find(l=>l.getName()==="translations")?.getInitializer();if(!r)return[];if(v.isObjectLiteralExpression(r))return z(r);let i=r.getFirstDescendantByKind(Je.ObjectLiteralExpression);return i?z(i):[]}catch(t){let s=t instanceof Error?t.message:`${t}`;return h.warn(`Failed to read locales from ${e}: ${s}`),[]}},Be=async()=>{let e=await Ne({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 Ee(e)&&(D("Translation cancelled"),process.exit(0)),e},ze=async e=>(await Oe(e,{cwd:process.cwd(),absolute:!0,nodir:!0})).sort(),He=async()=>{let e=S(process.cwd(),U);try{let t=await N(e,"utf8"),s=JSON.parse(t);return s.version!==1||!s.entries?B():{version:1,entries:s.entries}}catch{return B()}},H=e=>{let t=S(process.cwd(),U),s=JSON.stringify(e,null,2);Fe(t,s,"utf8")},Me=async e=>{let t=await Promise.all(e.map(async s=>[s,await _e(s)]));return Object.fromEntries(t)},Ke=(e,t)=>{let s=Re(e);return`${e.slice(0,-s.length)}.${t}${s}`},K=(e,t)=>`${M(process.cwd(),e)}::${t}`,qe=(e,t,s,n,a=!1)=>{let r=[],i=0;for(let l of t){let c=s[l];for(let o of e){let d=Ke(l,o),u=K(l,o),f=n.entries[u];if(!a&&f?.hash===c){i+=1;continue}r.push({locale:o,sourceFile:l,sourceHash:c,targetFile:d})}}return{tasks:r,skippedCount:i}},Xe=async e=>{await De(Ce(e),{recursive:!0})},We=async(e,t,s)=>{let n=await fetch(e,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({content:t,locale:s})});if(!n.ok){let r=await n.text();throw new Error(`API request failed (${n.status}): ${r}`)}let a=await n.json();if(!a.translation)throw new Error("API response did not include a translation");return a.translation},Ye=async(e,t,s)=>{let n=await N(e.sourceFile,"utf8"),a=await We(t,n,e.locale);await Xe(e.targetFile),await Se(e.targetFile,a,"utf8"),s.entries[K(e.sourceFile,e.locale)]={hash:e.sourceHash,updatedAt:new Date().toISOString()}},q=async(e,t)=>{je("Translate MDX content");let s=e??Ae,n=t.url||process.env.GEISTDOCS_TRANSLATE_URL||"https://geistdocs.com/translate",a=Ge(t.config??Le),r=await ze(s);r.length===0&&(h.error(`No MDX files found matching pattern: ${s}`),D("Translation cancelled"),process.exit(1)),h.info(`Found ${r.length} MDX file(s) matching pattern`),a.length===0&&(a=await Be());let i=S(process.cwd(),U),l=await He();await H(l),h.info(`Using cache: ${i}`);let c=await Me(r),{tasks:o,skippedCount:d}=qe(a,r,c,l,t.force);if(o.length===0){h.success("All translations are up to date!"),D(`Skipped ${d} file(s) (unchanged)`);return}let u=[];for(let y=0;y<o.length;y+=E)u.push(o.slice(y,y+E));h.info(`Processing ${o.length} translation(s) in ${u.length} batch(es) of up to ${E}`),d>0&&h.info(`Skipped ${d} translation(s) (unchanged)`);let f=Ue();f.start("Translating content...");let k=0;for(let y of u)await Promise.all(y.map(async L=>{await Ye(L,n,l),k+=1,f.message(`Translated ${k}/${o.length}: ${M(process.cwd(),L.targetFile)}`)})),await H(l);f.stop("Translation complete!"),D(`Created/updated ${o.length} file(s)`)};import{access as Ze,copyFile as Qe,mkdir as Z,rm as J}from"fs/promises";import{dirname as et,join as w}from"path";import{intro as tt,log as p,outro as C,spinner as Q}from"@clack/prompts";import{glob as st}from"glob";var nt=["**/*"],at=["content/docs/**"],O=".geistdocs-tmp",rt=async(e,t)=>{let s=w(e,t);await J(s,{recursive:!0,force:!0}),await Z(s,{recursive:!0})},I=async e=>await J(e,{recursive:!0,force:!0}),X=async(e,t,s)=>(await st(e,{cwd:s,nodir:!0,dot:!0,ignore:[".git/**",...t]})).sort(),it=async e=>{try{return await Ze(e),!0}catch{return!1}},ot=async(e,t,s)=>{let n=w(t,e),a=w(s,e);return await it(n)?(await Qe(n,a),{success:!0}):{success:!1,error:`Source file not found: ${n}`}},ct=async(e,t)=>{let s=w(t,e);return await J(s,{force:!0}),{success:!0}},W=20,Y=async(e,t,s)=>{let n=[];for(let a=0;a<e.length;a+=s){let r=e.slice(a,a+s),i=await Promise.all(r.map(t));n.push(...i)}return n},lt=async(e,t,s,n,a)=>{let r={success:[],deleted:[],failed:[]},i=[...new Set(e.map(c=>et(w(n,c))))];a.message(`Creating ${i.length} directories...`),await Promise.all(i.map(c=>Z(c,{recursive:!0}))),a.message(`Updating ${e.length} files...`);let l=await Y(e,async c=>{let o=await ot(c,s,n);return{file:c,...o}},W);for(let{file:c,success:o,error:d}of l)o?r.success.push(c):r.failed.push({file:c,error:d??"Unknown error"});if(t.length>0){a.message(`Deleting ${t.length} files...`);let c=await Y(t,async o=>{try{return await ct(o,n),{file:o,success:!0}}catch(d){let u=d instanceof Error?d.message:`${d}`;return{file:o,success:!1,error:u}}},W);for(let o of c)o.success?r.deleted.push(o.file):r.failed.push({file:o.file,error:o.error})}return r},pt=e=>{if(e.success.length>0){p.success(`Successfully updated ${e.success.length} files:`);for(let t of e.success)p.info(` \u2713 ${t}`)}if(e.deleted.length>0){p.success(`Deleted ${e.deleted.length} files:`);for(let t of e.deleted)p.info(` \u{1F5D1} ${t}`)}if(e.failed.length>0){p.warn(`Failed to update ${e.failed.length} files:`);for(let{file:t,error:s}of e.failed)p.error(` \u2717 ${t}: ${s}`)}},dt=e=>e.includes("canary")?"canary":"latest",gt=async e=>{let t=await fetch(`https://registry.npmjs.org/${encodeURIComponent(g)}`);if(!t.ok)throw new Error(`Failed to resolve ${g}@${e}`);let n=(await t.json())["dist-tags"]?.[e];if(!n)throw new Error(`Could not find dist-tag ${e} for ${g}`);return n},ut=async e=>{let t=await P(e),s=R(t,g);if(!s)return{currentVersion:s,nextVersion:void 0,updated:!1};let n=dt(s),a=await gt(n);return s===a?{currentVersion:s,nextVersion:a,updateTag:n,updated:!1}:(b(t,g,a),await x(e,t),{currentVersion:s,nextVersion:a,updateTag:n,updated:!0})},ft=async(e,t,s)=>{let n=await P(e);if(!V(n,g))return!1;t&&t.length>0&&p.warn("Ignoring file patterns for a package-based site. This update will bump the package version instead."),s?.sync&&p.warn("Ignoring --sync for a package-based site. Runtime updates now come from the package version.");let{currentVersion:a,nextVersion:r,updateTag:i,updated:l}=await ut(e);if(!l)return p.success(a?`@vercel/geistdocs is already at ${r} (${i}).`:"No package version update was needed."),C("Package-based site is already up to date."),!0;p.info(`Bumping ${g} from ${a} to ${r} (${i})`);let c=Q();return c.start("Installing updated package version..."),await m("pnpm",["install"],{cwd:e}),c.stop("Package update complete!"),C("Please review and test the upgraded package version."),!0},mt=async(e,t,s,n,a)=>{let r=w(e,O),i=Q(),l=a?.sync?r:t;i.start("Preparing template snapshot..."),a?.sync&&(await rt(e,O),await F(r)),i.message("Scanning for files...");let c=await X(s,n,l),o=[];if(a?.sync){i.message("Comparing with local files...");let u=await X(s,n,e),f=new Set(c);o=u.filter(k=>!f.has(k))}if(i.stop(`Found ${c.length} files to update`),c.length===0&&o.length===0){p.warn("No files matched the patterns. Nothing to update."),a?.sync&&await I(r),C("Update cancelled.");return}p.info(`Patterns: ${s.length}`),p.info(`Files to update: ${c.length}`),a?.sync&&p.info(`Files to delete: ${o.length}`),i.start("Updating files...");let d=await lt(c,o,l,e,i);a?.sync&&(i.message("Cleaning up..."),await I(r)),i.stop("Update complete!"),pt(d),C("Please review and test the changes carefully.")},ee=async(e,t)=>{let s=process.cwd(),n=j(),a=e&&e.length>0?e:nt,r=e&&e.length>0?[]:at;try{if(tt("Let's update your Geistdocs project!"),await ft(s,e,t))return;p.info("Template source: bundled package snapshot"),e&&e.length>0&&p.info(`Updating specific files: ${e.join(", ")}`),t?.sync&&p.info("Sync mode enabled: will delete files removed from template"),await mt(s,n,a,r,t)}catch(i){let l=i instanceof Error?i.message:`${i}`;try{await I(w(s,O))}catch{}p.error(`Failed to update project: ${l}`),process.exit(1)}};T.name("geistdocs").description("CLI for Geistdocs projects").version("1.15.3","-v, --version","Output the current version");T.command("init").description("Initialize a new Geistdocs project").option("--name <name>","Name of the project").option("--disable-git","Disable git initialization").action(G);T.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(ee);T.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(q);T.parse(process.argv);
3
+ `,"utf8")},R=(e,t)=>{for(let s of A){let n=e[s];if(n&&t in n)return n[t]}},V=(e,t)=>!!R(e,t),b=(e,t,s)=>{let n=!1;for(let a of A){let r=e[a];r&&t in r&&(r[t]=s,n=!0)}return n},j=()=>oe(new URL("../../template",import.meta.url)),F=async e=>{await ne(j(),e,{recursive:!0});let t=$(e,".gitignore"),s=$(e,"_gitignore");try{await re(s,t)}catch{}};var ye=async e=>{await F(e)},Pe=async e=>{try{return await ce(e),!0}catch{return!1}},ve=async()=>{await Pe(".env.example")&&await le(".env.example",".env.local")},Te=async e=>{let t=await P(e),s=_();return b(t,g,s)?(await x(e,t),!0):!1},ke=async e=>{await m("pnpm",["install"],{cwd:e,env:process.env,stdio:"inherit"})},$e=async e=>{await m("git",["init"],{cwd:e,env:process.env,stdio:"inherit"}),await m("git",["add","."],{cwd:e,env:process.env,stdio:"inherit"}),await m("git",["commit","-m","\u2728 Initial commit"],{cwd:e,env:process.env,stdio:"inherit"})},xe=async()=>{let e=await we({message:"What is your project named?",placeholder:"my-app",validate(t){if(t.length===0)return"Please enter a project name."}});return ue(e)&&(de("Operation cancelled."),process.exit(0)),e.toString()},G=async e=>{try{ge("Let's start a Geistdocs project!");let t=process.cwd(),s=e.name||await xe(),n=he(),a=pe(t,s);n.start("Copying bundled template..."),await ye(s),n.message("Setting up environment variables..."),process.chdir(a),await ve(),n.message("Rewriting package dependency versions..."),await Te(a),n.message("Installing dependencies..."),await ke(a),e.disableGit||(n.message("Initializing Git repository..."),await $e(a)),n.stop("Project initialized successfully!"),me("Run `pnpm dev` to start the development server.")}catch(t){let s=t instanceof Error?t.message:`Failed to initialize project: ${t}`;fe.error(s),process.exit(1)}};import{readFileSync as be,writeFileSync as Fe}from"fs";import{mkdir as De,readFile as N,writeFile as Se}from"fs/promises";import{dirname as Ce,extname as Re,relative as M,resolve as S}from"path";import{intro as je,isCancel as Ee,log as h,multiselect as Ne,outro as D,spinner as Ue}from"@clack/prompts";import{glob as Oe}from"glob";import{Node as v,Project as Ie,SyntaxKind as Je}from"ts-morph";var Le="geistdocs.tsx",Ae="content/docs/**/*.mdx",U=".translation-cache.json",E=8,B=()=>({version:1,entries:{}}),_e=async e=>{let t=await N(e),{createHash:s}=await import("crypto");return s("sha256").update(t).digest("hex")},Ve=e=>{let t=S(process.cwd(),e);return be(t,"utf8")},z=e=>v.isObjectLiteralExpression(e)?e.getProperties().flatMap(t=>{if(v.isPropertyAssignment(t)){let s=t.getNameNode();if(v.isIdentifier(s)||v.isStringLiteral(s))return[s.getText().replaceAll(/['"]/g,"")]}return[]}).filter(Boolean):[],Ge=e=>{try{let t=new Ie({compilerOptions:{allowJs:!0,jsx:4,module:99,target:10},skipAddingFilesFromTsConfig:!0,useInMemoryFileSystem:!0}),s=Ve(e),r=t.createSourceFile(e,s,{overwrite:!0}).getVariableDeclarations().find(l=>l.getName()==="translations")?.getInitializer();if(!r)return[];if(v.isObjectLiteralExpression(r))return z(r);let i=r.getFirstDescendantByKind(Je.ObjectLiteralExpression);return i?z(i):[]}catch(t){let s=t instanceof Error?t.message:`${t}`;return h.warn(`Failed to read locales from ${e}: ${s}`),[]}},Be=async()=>{let e=await Ne({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 Ee(e)&&(D("Translation cancelled"),process.exit(0)),e},ze=async e=>(await Oe(e,{cwd:process.cwd(),absolute:!0,nodir:!0})).sort(),He=async()=>{let e=S(process.cwd(),U);try{let t=await N(e,"utf8"),s=JSON.parse(t);return s.version!==1||!s.entries?B():{version:1,entries:s.entries}}catch{return B()}},H=e=>{let t=S(process.cwd(),U),s=JSON.stringify(e,null,2);Fe(t,s,"utf8")},Me=async e=>{let t=await Promise.all(e.map(async s=>[s,await _e(s)]));return Object.fromEntries(t)},Ke=(e,t)=>{let s=Re(e);return`${e.slice(0,-s.length)}.${t}${s}`},K=(e,t)=>`${M(process.cwd(),e)}::${t}`,qe=(e,t,s,n,a=!1)=>{let r=[],i=0;for(let l of t){let c=s[l];for(let o of e){let d=Ke(l,o),u=K(l,o),f=n.entries[u];if(!a&&f?.hash===c){i+=1;continue}r.push({locale:o,sourceFile:l,sourceHash:c,targetFile:d})}}return{tasks:r,skippedCount:i}},Xe=async e=>{await De(Ce(e),{recursive:!0})},We=async(e,t,s)=>{let n=await fetch(e,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({content:t,locale:s})});if(!n.ok){let r=await n.text();throw new Error(`API request failed (${n.status}): ${r}`)}let a=await n.json();if(!a.translation)throw new Error("API response did not include a translation");return a.translation},Ye=async(e,t,s)=>{let n=await N(e.sourceFile,"utf8"),a=await We(t,n,e.locale);await Xe(e.targetFile),await Se(e.targetFile,a,"utf8"),s.entries[K(e.sourceFile,e.locale)]={hash:e.sourceHash,updatedAt:new Date().toISOString()}},q=async(e,t)=>{je("Translate MDX content");let s=e??Ae,n=t.url||process.env.GEISTDOCS_TRANSLATE_URL||"https://geistdocs.com/translate",a=Ge(t.config??Le),r=await ze(s);r.length===0&&(h.error(`No MDX files found matching pattern: ${s}`),D("Translation cancelled"),process.exit(1)),h.info(`Found ${r.length} MDX file(s) matching pattern`),a.length===0&&(a=await Be());let i=S(process.cwd(),U),l=await He();await H(l),h.info(`Using cache: ${i}`);let c=await Me(r),{tasks:o,skippedCount:d}=qe(a,r,c,l,t.force);if(o.length===0){h.success("All translations are up to date!"),D(`Skipped ${d} file(s) (unchanged)`);return}let u=[];for(let y=0;y<o.length;y+=E)u.push(o.slice(y,y+E));h.info(`Processing ${o.length} translation(s) in ${u.length} batch(es) of up to ${E}`),d>0&&h.info(`Skipped ${d} translation(s) (unchanged)`);let f=Ue();f.start("Translating content...");let k=0;for(let y of u)await Promise.all(y.map(async L=>{await Ye(L,n,l),k+=1,f.message(`Translated ${k}/${o.length}: ${M(process.cwd(),L.targetFile)}`)})),await H(l);f.stop("Translation complete!"),D(`Created/updated ${o.length} file(s)`)};import{access as Ze,copyFile as Qe,mkdir as Z,rm as J}from"fs/promises";import{dirname as et,join as w}from"path";import{intro as tt,log as p,outro as C,spinner as Q}from"@clack/prompts";import{glob as st}from"glob";var nt=["**/*"],at=["content/docs/**"],O=".geistdocs-tmp",rt=async(e,t)=>{let s=w(e,t);await J(s,{recursive:!0,force:!0}),await Z(s,{recursive:!0})},I=async e=>await J(e,{recursive:!0,force:!0}),X=async(e,t,s)=>(await st(e,{cwd:s,nodir:!0,dot:!0,ignore:[".git/**",...t]})).sort(),it=async e=>{try{return await Ze(e),!0}catch{return!1}},ot=async(e,t,s)=>{let n=w(t,e),a=w(s,e);return await it(n)?(await Qe(n,a),{success:!0}):{success:!1,error:`Source file not found: ${n}`}},ct=async(e,t)=>{let s=w(t,e);return await J(s,{force:!0}),{success:!0}},W=20,Y=async(e,t,s)=>{let n=[];for(let a=0;a<e.length;a+=s){let r=e.slice(a,a+s),i=await Promise.all(r.map(t));n.push(...i)}return n},lt=async(e,t,s,n,a)=>{let r={success:[],deleted:[],failed:[]},i=[...new Set(e.map(c=>et(w(n,c))))];a.message(`Creating ${i.length} directories...`),await Promise.all(i.map(c=>Z(c,{recursive:!0}))),a.message(`Updating ${e.length} files...`);let l=await Y(e,async c=>{let o=await ot(c,s,n);return{file:c,...o}},W);for(let{file:c,success:o,error:d}of l)o?r.success.push(c):r.failed.push({file:c,error:d??"Unknown error"});if(t.length>0){a.message(`Deleting ${t.length} files...`);let c=await Y(t,async o=>{try{return await ct(o,n),{file:o,success:!0}}catch(d){let u=d instanceof Error?d.message:`${d}`;return{file:o,success:!1,error:u}}},W);for(let o of c)o.success?r.deleted.push(o.file):r.failed.push({file:o.file,error:o.error})}return r},pt=e=>{if(e.success.length>0){p.success(`Successfully updated ${e.success.length} files:`);for(let t of e.success)p.info(` \u2713 ${t}`)}if(e.deleted.length>0){p.success(`Deleted ${e.deleted.length} files:`);for(let t of e.deleted)p.info(` \u{1F5D1} ${t}`)}if(e.failed.length>0){p.warn(`Failed to update ${e.failed.length} files:`);for(let{file:t,error:s}of e.failed)p.error(` \u2717 ${t}: ${s}`)}},dt=e=>e.includes("canary")?"canary":"latest",gt=async e=>{let t=await fetch(`https://registry.npmjs.org/${encodeURIComponent(g)}`);if(!t.ok)throw new Error(`Failed to resolve ${g}@${e}`);let n=(await t.json())["dist-tags"]?.[e];if(!n)throw new Error(`Could not find dist-tag ${e} for ${g}`);return n},ut=async e=>{let t=await P(e),s=R(t,g);if(!s)return{currentVersion:s,nextVersion:void 0,updated:!1};let n=dt(s),a=await gt(n);return s===a?{currentVersion:s,nextVersion:a,updateTag:n,updated:!1}:(b(t,g,a),await x(e,t),{currentVersion:s,nextVersion:a,updateTag:n,updated:!0})},ft=async(e,t,s)=>{let n=await P(e);if(!V(n,g))return!1;t&&t.length>0&&p.warn("Ignoring file patterns for a package-based site. This update will bump the package version instead."),s?.sync&&p.warn("Ignoring --sync for a package-based site. Runtime updates now come from the package version.");let{currentVersion:a,nextVersion:r,updateTag:i,updated:l}=await ut(e);if(!l)return p.success(a?`@vercel/geistdocs is already at ${r} (${i}).`:"No package version update was needed."),C("Package-based site is already up to date."),!0;p.info(`Bumping ${g} from ${a} to ${r} (${i})`);let c=Q();return c.start("Installing updated package version..."),await m("pnpm",["install"],{cwd:e}),c.stop("Package update complete!"),C("Please review and test the upgraded package version."),!0},mt=async(e,t,s,n,a)=>{let r=w(e,O),i=Q(),l=a?.sync?r:t;i.start("Preparing template snapshot..."),a?.sync&&(await rt(e,O),await F(r)),i.message("Scanning for files...");let c=await X(s,n,l),o=[];if(a?.sync){i.message("Comparing with local files...");let u=await X(s,n,e),f=new Set(c);o=u.filter(k=>!f.has(k))}if(i.stop(`Found ${c.length} files to update`),c.length===0&&o.length===0){p.warn("No files matched the patterns. Nothing to update."),a?.sync&&await I(r),C("Update cancelled.");return}p.info(`Patterns: ${s.length}`),p.info(`Files to update: ${c.length}`),a?.sync&&p.info(`Files to delete: ${o.length}`),i.start("Updating files...");let d=await lt(c,o,l,e,i);a?.sync&&(i.message("Cleaning up..."),await I(r)),i.stop("Update complete!"),pt(d),C("Please review and test the changes carefully.")},ee=async(e,t)=>{let s=process.cwd(),n=j(),a=e&&e.length>0?e:nt,r=e&&e.length>0?[]:at;try{if(tt("Let's update your Geistdocs project!"),await ft(s,e,t))return;p.info("Template source: bundled package snapshot"),e&&e.length>0&&p.info(`Updating specific files: ${e.join(", ")}`),t?.sync&&p.info("Sync mode enabled: will delete files removed from template"),await mt(s,n,a,r,t)}catch(i){let l=i instanceof Error?i.message:`${i}`;try{await I(w(s,O))}catch{}p.error(`Failed to update project: ${l}`),process.exit(1)}};T.name("geistdocs").description("CLI for Geistdocs projects").version("1.15.4","-v, --version","Output the current version");T.command("init").description("Initialize a new Geistdocs project").option("--name <name>","Name of the project").option("--disable-git","Disable git initialization").action(G);T.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(ee);T.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(q);T.parse(process.argv);
@@ -1 +1 @@
1
- {"version":3,"file":"navbar-logo.d.ts","sourceRoot":"","sources":["../../../src/internal/navbar/navbar-logo.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAC;AAK5D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAY9D,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD,eAAO,MAAM,oBAAoB,EAAE,yBAAyB,EAoB3D,CAAC;AAgGF,KAAK,eAAe,GAAG;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,CACA;IACE,OAAO,EAAE,KAAK,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,CAAC,EAAE,yBAAyB,EAAE,CAAC;CAC3C,GACD;IACE,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,IAAI,EAAE,SAAS,CAAC;CACjB,CACJ,CAAC;AAEF,wBAAgB,UAAU,CAAC,EACzB,SAAS,EACT,IAAU,EACV,GAAG,KAAK,EACT,EAAE,eAAe,2CA6IjB"}
1
+ {"version":3,"file":"navbar-logo.d.ts","sourceRoot":"","sources":["../../../src/internal/navbar/navbar-logo.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAC;AAK5D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AAY9D,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AAEjD,eAAO,MAAM,oBAAoB,EAAE,yBAAyB,EAoB3D,CAAC;AAgGF,KAAK,eAAe,GAAG;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,CACA;IACE,OAAO,EAAE,KAAK,CAAC;IACf,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,CAAC,EAAE,yBAAyB,EAAE,CAAC;CAC3C,GACD;IACE,OAAO,CAAC,EAAE,UAAU,CAAC;IACrB,IAAI,EAAE,SAAS,CAAC;CACjB,CACJ,CAAC;AAEF,wBAAgB,UAAU,CAAC,EACzB,SAAS,EACT,IAAU,EACV,GAAG,KAAK,EACT,EAAE,eAAe,2CAkJjB"}
@@ -79,5 +79,5 @@ export function NavbarLogo({ className, href = "/", ...props }) {
79
79
  if (e.detail !== 0) {
80
80
  router.push(href);
81
81
  }
82
- }, children: props.logo }), _jsx(NavigationMenuPrimitive.Content, { className: "fixed inset-x-0 top-16 z-30 w-screen bg-background-200 shadow-[0_1px_0_0_var(--ds-gray-alpha-300)] before:absolute before:inset-x-0 before:-top-3 before:h-3 before:content-['']", children: _jsx("div", { className: "mx-auto w-full max-w-[1448px] px-2", children: _jsxs("div", { className: "flex flex-nowrap gap-x-10 pt-4 pb-6 pl-4", children: [featuredProducts.length > 0 ? (_jsxs("div", { className: "flex shrink-0 flex-col", children: [_jsx("h5", { className: "text-gray-900 text-label-14", children: "Latest" }), _jsx("div", { className: "mt-[5px] flex flex-1 gap-x-10", children: featuredProducts.map((product) => (_jsx(OssFeaturedCard, { product: product }, product.href))) })] })) : null, ossSections.map((section) => (_jsxs("div", { className: "min-w-[180px] shrink-0", children: [_jsx("h5", { className: "text-gray-900 text-label-14", children: section.heading }), _jsx("ul", { className: "mt-[5px] flex list-none flex-col", children: section.items.map((product) => (_jsx("li", { className: "flex", children: _jsx(OssProductLink, { product: product }) }, product.href))) })] }, section.heading)))] }) }) })] }) }) }), _jsx("div", { "aria-hidden": "true", className: cn("pointer-events-none fixed inset-x-0 top-16 bottom-0 z-0 bg-background-200/60", navOpen ? "opacity-100" : "opacity-0") })] })] })) : (_jsx(Link, { className: "flex items-center text-gray-1000", href: href, children: props.logo }))] }));
82
+ }, children: props.logo }), _jsx(NavigationMenuPrimitive.Content, { className: "fixed inset-x-0 top-16 z-30 w-screen bg-background-200 shadow-[0_1px_0_0_var(--ds-gray-alpha-300)] before:absolute before:inset-x-0 before:-top-3 before:h-3 before:content-[''] data-[state=closed]:hidden", forceMount: true, children: _jsx("div", { className: "mx-auto w-full max-w-[1448px] px-2", children: _jsxs("div", { className: "flex flex-nowrap gap-x-10 pt-4 pb-6 pl-4", children: [featuredProducts.length > 0 ? (_jsxs("div", { className: "flex shrink-0 flex-col", children: [_jsx("h5", { className: "text-gray-900 text-label-14", children: "Latest" }), _jsx("div", { className: "mt-[5px] flex flex-1 gap-x-10", children: featuredProducts.map((product) => (_jsx(OssFeaturedCard, { product: product }, product.href))) })] })) : null, ossSections.map((section) => (_jsxs("div", { className: "min-w-[180px] shrink-0", children: [_jsx("h5", { className: "text-gray-900 text-label-14", children: section.heading }), _jsx("ul", { className: "mt-[5px] flex list-none flex-col", children: section.items.map((product) => (_jsx("li", { className: "flex", children: _jsx(OssProductLink, { product: product }) }, product.href))) })] }, section.heading)))] }) }) })] }) }) }), _jsx("div", { "aria-hidden": "true", className: cn("pointer-events-none fixed inset-x-0 top-16 bottom-0 z-0 bg-background-200/60", navOpen ? "opacity-100" : "opacity-0") })] })] })) : (_jsx(Link, { className: "flex items-center text-gray-1000", href: href, children: props.logo }))] }));
83
83
  }
@@ -1 +1 @@
1
- {"version":3,"file":"table-of-contents.d.ts","sourceRoot":"","sources":["../../src/internal/table-of-contents.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,UAAU,6BAA6B;IACrC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,GAAG,EAAE,eAAe,CAAC;CACtB;AAED,eAAO,MAAM,wBAAwB,GAAI,0BAItC,6BAA6B,4CAqB/B,CAAC"}
1
+ {"version":3,"file":"table-of-contents.d.ts","sourceRoot":"","sources":["../../src/internal/table-of-contents.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,UAAU,6BAA6B;IACrC,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,GAAG,EAAE,eAAe,CAAC;CACtB;AAED,eAAO,MAAM,wBAAwB,GAAI,0BAItC,6BAA6B,4CAqB/B,CAAC"}
@@ -1,5 +1,5 @@
1
1
  "use client";
2
2
  import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
3
- import { TOCItems } from "fumadocs-ui/components/toc/clerk";
4
3
  import { TOCScrollArea } from "fumadocs-ui/components/toc/index";
4
+ import { TOCItems } from "./toc-items";
5
5
  export const GeistdocsTableOfContents = ({ footer, header, toc, }) => (_jsx("aside", { "aria-label": "Page navigation", className: "sticky top-(--fd-docs-row-1) hidden h-[calc(var(--fd-docs-height)-var(--fd-docs-row-1))] w-(--fd-toc-width) flex-col pt-14 pr-4 pb-2 [grid-area:toc] xl:flex", id: "nd-toc", children: _jsxs("nav", { "aria-label": "On this page", className: "flex min-h-0 flex-1 flex-col", children: [header, toc.length > 0 ? (_jsxs(_Fragment, { children: [_jsx("p", { className: "mb-2 font-medium text-gray-1000 text-sm", children: "On this page" }), _jsx(TOCScrollArea, { className: "geistdocs-toc-scroll", children: _jsx(TOCItems, {}) })] })) : null, footer] }) }));
@@ -0,0 +1,3 @@
1
+ import { type ComponentProps } from "react";
2
+ export declare const TOCItems: ({ className, ...props }: ComponentProps<"div">) => import("react/jsx-runtime").JSX.Element;
3
+ //# sourceMappingURL=toc-items.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"toc-items.d.ts","sourceRoot":"","sources":["../../src/internal/toc-items.tsx"],"names":[],"mappings":"AAQA,OAAO,EACL,KAAK,cAAc,EAKpB,MAAM,OAAO,CAAC;AAuCf,eAAO,MAAM,QAAQ,GAAI,yBAAyB,cAAc,CAAC,KAAK,CAAC,4CAiFtE,CAAC"}
@@ -0,0 +1,86 @@
1
+ "use client";
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
+ import { TOCItem as TOCItemLink, useActiveAnchors, } from "fumadocs-core/toc";
4
+ import { useTOCItems } from "fumadocs-ui/components/toc/index";
5
+ import { useCallback, useEffect, useRef, useState, } from "react";
6
+ import { cn } from "./cn";
7
+ // Text indentation per heading depth; the guide rail stays straight.
8
+ const getItemOffset = (depth) => {
9
+ if (depth <= 2) {
10
+ return 14;
11
+ }
12
+ if (depth === 3) {
13
+ return 26;
14
+ }
15
+ return 36;
16
+ };
17
+ // Ignore programmatic scrolling this long after a click/deep-link so the jump
18
+ // to the anchor does not immediately release the selection.
19
+ const ANCHOR_SCROLL_MS = 600;
20
+ const TOCItem = ({ item, active, onSelect, }) => (_jsx(TOCItemLink, { className: "prose wrap-anywhere border-fd-foreground/10 border-s py-1.5 text-fd-muted-foreground text-sm transition-colors first:pt-0 last:pb-0 hover:text-fd-accent-foreground data-[active=true]:border-fd-primary data-[active=true]:text-fd-primary", "data-active": active ? "true" : undefined, href: item.url, onClick: onSelect, style: { paddingInlineStart: getItemOffset(item.depth) }, children: item.title }));
21
+ export const TOCItems = ({ className, ...props }) => {
22
+ const items = useTOCItems();
23
+ const anchors = useActiveAnchors();
24
+ // Trailing headings never reach the top of the viewport, so scroll tracking
25
+ // misses them. Fall back to the clicked/deep-linked hash, and to the last
26
+ // heading once the reader hits the bottom of a scrollable page.
27
+ const [selected, setSelected] = useState(null);
28
+ const [atBottom, setAtBottom] = useState(false);
29
+ const ignoreScroll = useRef(false);
30
+ const ignoreTimer = useRef(undefined);
31
+ const select = useCallback((id) => {
32
+ setSelected(id);
33
+ if (!id) {
34
+ return;
35
+ }
36
+ ignoreScroll.current = true;
37
+ clearTimeout(ignoreTimer.current);
38
+ ignoreTimer.current = setTimeout(() => {
39
+ ignoreScroll.current = false;
40
+ }, ANCHOR_SCROLL_MS);
41
+ }, []);
42
+ useEffect(() => {
43
+ const syncFromHash = () => select(window.location.hash.slice(1) || null);
44
+ const updateAtBottom = () => {
45
+ const doc = document.documentElement;
46
+ const scrollable = doc.scrollHeight - window.innerHeight > 4;
47
+ setAtBottom(scrollable &&
48
+ window.scrollY + window.innerHeight >= doc.scrollHeight - 2);
49
+ };
50
+ // Any real scroll — wheel, touch, keyboard, or scrollbar drag — hands the
51
+ // indicator back to viewport-based tracking, unless it is the programmatic
52
+ // jump from a click/deep-link.
53
+ const onScroll = () => {
54
+ updateAtBottom();
55
+ if (!ignoreScroll.current) {
56
+ setSelected(null);
57
+ }
58
+ };
59
+ syncFromHash();
60
+ updateAtBottom();
61
+ window.addEventListener("hashchange", syncFromHash);
62
+ window.addEventListener("scroll", onScroll, { passive: true });
63
+ window.addEventListener("resize", updateAtBottom);
64
+ return () => {
65
+ clearTimeout(ignoreTimer.current);
66
+ window.removeEventListener("hashchange", syncFromHash);
67
+ window.removeEventListener("scroll", onScroll);
68
+ window.removeEventListener("resize", updateAtBottom);
69
+ };
70
+ }, [select]);
71
+ const lastId = items.at(-1)?.url.slice(1) ?? null;
72
+ return (_jsx("div", { className: cn("flex flex-col", className), ...props, children: items.map((item) => {
73
+ const id = item.url.slice(1);
74
+ let active;
75
+ if (selected) {
76
+ active = selected === id;
77
+ }
78
+ else if (atBottom) {
79
+ active = id === lastId;
80
+ }
81
+ else {
82
+ active = anchors.includes(id);
83
+ }
84
+ return (_jsx(TOCItem, { active: active, item: item, onSelect: () => select(id) }, item.url));
85
+ }) }));
86
+ };
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.15.3 so agents can understand the installed package without web access.
3
+ These docs are bundled with `@vercel/geistdocs` 1.15.4 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
@@ -42,4 +42,5 @@ They are generated from `apps/template/content/docs` during the package build.
42
42
  - [llms.txt](pages/llms-txt.md): A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
43
43
  - [Open in Chat](pages/open-in-chat.md): Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
44
44
  - [RSS](pages/rss.md): An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
45
+ - [Table of contents](pages/table-of-contents.md): Geistdocs builds the "On this page" outline from your headings, indents sub-headings under their parent, and tracks the active section along a straight vertical guide rail.
45
46
  - [Theme-Aware Image](pages/theme-aware-image.md): A component that swaps images based on the active theme, built on top of Next.js Image.
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.15.3.
3
+ These docs are bundled with `@vercel/geistdocs` 1.15.4.
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
@@ -25,6 +25,7 @@ They describe how to build package-backed Geistdocs sites and how to use the pac
25
25
  - [llms.txt](pages/llms-txt.md): A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
26
26
  - [Open in Chat](pages/open-in-chat.md): Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
27
27
  - [RSS](pages/rss.md): An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
28
+ - [Table of contents](pages/table-of-contents.md): Geistdocs builds the "On this page" outline from your headings, indents sub-headings under their parent, and tracks the active section along a straight vertical guide rail.
28
29
  - [Theme-Aware Image](pages/theme-aware-image.md): A component that swaps images based on the active theme, built on top of Next.js Image.
29
30
 
30
31
  ---
@@ -3305,6 +3306,71 @@ lastModified: 2025-11-12
3305
3306
  ```
3306
3307
 
3307
3308
 
3309
+ ---
3310
+
3311
+ ---
3312
+ title: Table of contents
3313
+ description: Show an "On this page" outline that tracks the reader's position along a straight guide rail
3314
+ type: reference
3315
+ summary: Geistdocs builds the "On this page" outline from your headings, indents sub-headings under their parent, and tracks the active section along a straight vertical guide rail.
3316
+ url: /docs/table-of-contents
3317
+ source: apps/template/content/docs/table-of-contents.mdx
3318
+ prerequisites:
3319
+ - /docs/getting-started
3320
+ related:
3321
+ - /docs/syntax
3322
+ - /docs/configuration
3323
+ ---
3324
+
3325
+ # Table of contents
3326
+
3327
+ Every documentation page shows an **On this page** outline on the right side of the desktop layout. Geistdocs builds it from your headings, so you get an in-page table of contents without extra configuration. This page nests its own headings so you can watch the outline update as you scroll.
3328
+
3329
+ ## Read the outline
3330
+
3331
+ The outline lists your headings in document order and highlights the section you are currently reading.
3332
+
3333
+ ### Track the active section
3334
+
3335
+ A vertical guide rail runs down the left edge of the outline. As you scroll, an indicator slides along the rail to mark the active heading, so readers always know where they are in a long page.
3336
+
3337
+ ### Follow the straight guide rail
3338
+
3339
+ The guide rail stays straight for every heading level. Sub-headings indent to the right of the rail, and the rail no longer bends outward to meet them, which keeps deep pages readable at a glance.
3340
+
3341
+ ## Structure your headings
3342
+
3343
+ The outline mirrors your heading hierarchy, so a clear structure produces a clear outline.
3344
+
3345
+ ### Start each section with an h2
3346
+
3347
+ Use `##` for the top-level sections of a page. These sit closest to the guide rail and anchor the rest of the outline.
3348
+
3349
+ ### Nest sub-sections with an h3
3350
+
3351
+ Use `###` for sub-sections. Geistdocs indents them under their parent `##` heading:
3352
+
3353
+ ```mdx
3354
+ ## Structure your headings
3355
+
3356
+ ### Nest sub-sections with an h3
3357
+
3358
+ #### Add detail with an h4
3359
+ ```
3360
+
3361
+ #### Add detail with an h4
3362
+
3363
+ Use `####` when a sub-section needs its own breakdown. Geistdocs indents each level a little further so the relationship stays clear, while the guide rail itself remains a single straight line.
3364
+
3365
+ ## Adapt to smaller screens
3366
+
3367
+ On mobile, Geistdocs replaces the sidebar outline with a compact menu in the page bar. The menu lists the same headings as a flat, indented list without the guide rail, so it stays legible on narrow screens.
3368
+
3369
+ ## Write scannable headings
3370
+
3371
+ Keep headings short and descriptive so the outline reads like a summary of the page. Name each heading after the goal of its section, and avoid stacking two headings with no content between them.
3372
+
3373
+
3308
3374
  ---
3309
3375
 
3310
3376
  ---
@@ -188,6 +188,15 @@
188
188
  "type": "conceptual",
189
189
  "url": "/docs/rss"
190
190
  },
191
+ {
192
+ "description": "Show an \"On this page\" outline that tracks the reader's position along a straight guide rail",
193
+ "path": "pages/table-of-contents.md",
194
+ "source": "apps/template/content/docs/table-of-contents.mdx",
195
+ "summary": "Geistdocs builds the \"On this page\" outline from your headings, indents sub-headings under their parent, and tracks the active section along a straight vertical guide rail.",
196
+ "title": "Table of contents",
197
+ "type": "reference",
198
+ "url": "/docs/table-of-contents"
199
+ },
191
200
  {
192
201
  "description": "Display different images based on the user's light or dark theme preference",
193
202
  "path": "pages/theme-aware-image.md",
@@ -199,5 +208,5 @@
199
208
  }
200
209
  ],
201
210
  "source": "apps/template/content/docs",
202
- "version": "1.15.3"
211
+ "version": "1.15.4"
203
212
  }
@@ -0,0 +1,61 @@
1
+ ---
2
+ title: Table of contents
3
+ description: Show an "On this page" outline that tracks the reader's position along a straight guide rail
4
+ type: reference
5
+ summary: Geistdocs builds the "On this page" outline from your headings, indents sub-headings under their parent, and tracks the active section along a straight vertical guide rail.
6
+ url: /docs/table-of-contents
7
+ source: apps/template/content/docs/table-of-contents.mdx
8
+ prerequisites:
9
+ - /docs/getting-started
10
+ related:
11
+ - /docs/syntax
12
+ - /docs/configuration
13
+ ---
14
+
15
+ # Table of contents
16
+
17
+ Every documentation page shows an **On this page** outline on the right side of the desktop layout. Geistdocs builds it from your headings, so you get an in-page table of contents without extra configuration. This page nests its own headings so you can watch the outline update as you scroll.
18
+
19
+ ## Read the outline
20
+
21
+ The outline lists your headings in document order and highlights the section you are currently reading.
22
+
23
+ ### Track the active section
24
+
25
+ A vertical guide rail runs down the left edge of the outline. As you scroll, an indicator slides along the rail to mark the active heading, so readers always know where they are in a long page.
26
+
27
+ ### Follow the straight guide rail
28
+
29
+ The guide rail stays straight for every heading level. Sub-headings indent to the right of the rail, and the rail no longer bends outward to meet them, which keeps deep pages readable at a glance.
30
+
31
+ ## Structure your headings
32
+
33
+ The outline mirrors your heading hierarchy, so a clear structure produces a clear outline.
34
+
35
+ ### Start each section with an h2
36
+
37
+ Use `##` for the top-level sections of a page. These sit closest to the guide rail and anchor the rest of the outline.
38
+
39
+ ### Nest sub-sections with an h3
40
+
41
+ Use `###` for sub-sections. Geistdocs indents them under their parent `##` heading:
42
+
43
+ ```mdx
44
+ ## Structure your headings
45
+
46
+ ### Nest sub-sections with an h3
47
+
48
+ #### Add detail with an h4
49
+ ```
50
+
51
+ #### Add detail with an h4
52
+
53
+ Use `####` when a sub-section needs its own breakdown. Geistdocs indents each level a little further so the relationship stays clear, while the guide rail itself remains a single straight line.
54
+
55
+ ## Adapt to smaller screens
56
+
57
+ On mobile, Geistdocs replaces the sidebar outline with a compact menu in the page bar. The menu lists the same headings as a flat, indented list without the guide rail, so it stays legible on narrow screens.
58
+
59
+ ## Write scannable headings
60
+
61
+ Keep headings short and descriptive so the outline reads like a summary of the page. Name each heading after the goal of its section, and avoid stacking two headings with no content between them.
package/docs/sitemap.md CHANGED
@@ -23,4 +23,5 @@ Use it to choose focused page files from `docs/pages/` before reading the full `
23
23
  - [llms.txt](pages/llms-txt.md) | URL: /docs/llms-txt | Type: conceptual | Summary: A single endpoint that returns all documentation as plain Markdown text following the llms.txt standard.
24
24
  - [Open in Chat](pages/open-in-chat.md) | URL: /docs/open-in-chat | Type: conceptual | Summary: Transfer documentation context to AI chat platforms like ChatGPT, Claude, Cursor, and v0 with a single click.
25
25
  - [RSS](pages/rss.md) | URL: /docs/rss | Type: conceptual | Summary: An automatically generated RSS 2.0 feed that keeps users informed when documentation is published or updated.
26
+ - [Table of contents](pages/table-of-contents.md) | URL: /docs/table-of-contents | Type: reference | Summary: Geistdocs builds the "On this page" outline from your headings, indents sub-headings under their parent, and tracks the active section along a straight vertical guide rail.
26
27
  - [Theme-Aware Image](pages/theme-aware-image.md) | URL: /docs/theme-aware-image | Type: reference | Summary: A component that swaps images based on the active theme, built on top of Next.js Image.
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.15.3",
4
+ "version": "1.15.4",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
7
7
  "type": "git",
@@ -0,0 +1,57 @@
1
+ ---
2
+ title: Table of contents
3
+ description: Show an "On this page" outline that tracks the reader's position along a straight guide rail
4
+ type: reference
5
+ summary: Geistdocs builds the "On this page" outline from your headings, indents sub-headings under their parent, and tracks the active section along a straight vertical guide rail.
6
+ prerequisites:
7
+ - /docs/getting-started
8
+ related:
9
+ - /docs/syntax
10
+ - /docs/configuration
11
+ ---
12
+
13
+ Every documentation page shows an **On this page** outline on the right side of the desktop layout. Geistdocs builds it from your headings, so you get an in-page table of contents without extra configuration. This page nests its own headings so you can watch the outline update as you scroll.
14
+
15
+ ## Read the outline
16
+
17
+ The outline lists your headings in document order and highlights the section you are currently reading.
18
+
19
+ ### Track the active section
20
+
21
+ A vertical guide rail runs down the left edge of the outline. As you scroll, an indicator slides along the rail to mark the active heading, so readers always know where they are in a long page.
22
+
23
+ ### Follow the straight guide rail
24
+
25
+ The guide rail stays straight for every heading level. Sub-headings indent to the right of the rail, and the rail no longer bends outward to meet them, which keeps deep pages readable at a glance.
26
+
27
+ ## Structure your headings
28
+
29
+ The outline mirrors your heading hierarchy, so a clear structure produces a clear outline.
30
+
31
+ ### Start each section with an h2
32
+
33
+ Use `##` for the top-level sections of a page. These sit closest to the guide rail and anchor the rest of the outline.
34
+
35
+ ### Nest sub-sections with an h3
36
+
37
+ Use `###` for sub-sections. Geistdocs indents them under their parent `##` heading:
38
+
39
+ ```mdx
40
+ ## Structure your headings
41
+
42
+ ### Nest sub-sections with an h3
43
+
44
+ #### Add detail with an h4
45
+ ```
46
+
47
+ #### Add detail with an h4
48
+
49
+ Use `####` when a sub-section needs its own breakdown. Geistdocs indents each level a little further so the relationship stays clear, while the guide rail itself remains a single straight line.
50
+
51
+ ## Adapt to smaller screens
52
+
53
+ On mobile, Geistdocs replaces the sidebar outline with a compact menu in the page bar. The menu lists the same headings as a flat, indented list without the guide rail, so it stays legible on narrow screens.
54
+
55
+ ## Write scannable headings
56
+
57
+ Keep headings short and descriptive so the outline reads like a summary of the page. Name each heading after the goal of its section, and avoid stacking two headings with no content between them.
@@ -3,6 +3,15 @@ import type { NextConfig } from "next";
3
3
 
4
4
  const withMDX = createMDX();
5
5
 
6
+ // Distinct favicon per environment; production keeps the default (no-op).
7
+ const ENV_FAVICONS = {
8
+ development: "/favicon.development.ico",
9
+ preview: "/favicon.preview.ico",
10
+ } as const;
11
+
12
+ const environment = process.env.VERCEL_ENV ?? process.env.NODE_ENV;
13
+ const envFavicon = ENV_FAVICONS[environment as keyof typeof ENV_FAVICONS];
14
+
6
15
  const config: NextConfig = {
7
16
  experimental: {
8
17
  turbopackFileSystemCacheForDev: true,
@@ -17,6 +26,18 @@ const config: NextConfig = {
17
26
  },
18
27
  ],
19
28
  },
29
+
30
+ rewrites() {
31
+ if (!envFavicon) {
32
+ return Promise.resolve([]);
33
+ }
34
+
35
+ return Promise.resolve({
36
+ beforeFiles: [{ source: "/favicon.ico", destination: envFavicon }],
37
+ afterFiles: [],
38
+ fallback: [],
39
+ });
40
+ },
20
41
  };
21
42
 
22
43
  export default withMDX(config);
@@ -18,7 +18,7 @@
18
18
  "@streamdown/code": "^1.0.1",
19
19
  "@vercel/agent-readability": "^0.2.1",
20
20
  "@vercel/analytics": "^1.6.1",
21
- "@vercel/geistdocs": "1.15.3",
21
+ "@vercel/geistdocs": "1.15.4",
22
22
  "@vercel/speed-insights": "^1.3.1",
23
23
  "ai": "^6.0.132",
24
24
  "class-variance-authority": "^0.7.1",
package/theme.css CHANGED
@@ -896,8 +896,24 @@
896
896
  padding-left: max(1rem, env(safe-area-inset-left));
897
897
  }
898
898
 
899
- .geistdocs-toc-scroll > div[style*="mask-image"] {
900
- inset-inline-start: -0.5px;
899
+ /* Show a slim scrollbar on long tables of contents. `scrollbar-width: auto`
900
+ overrides the component's `scrollbar-width: none`, which would otherwise
901
+ suppress the WebKit styling below too. */
902
+ #nd-toc .geistdocs-toc-scroll {
903
+ scrollbar-width: auto;
904
+ }
905
+
906
+ #nd-toc .geistdocs-toc-scroll::-webkit-scrollbar {
907
+ width: 6px;
908
+ }
909
+
910
+ #nd-toc .geistdocs-toc-scroll::-webkit-scrollbar-thumb {
911
+ background-color: var(--color-gray-alpha-500);
912
+ border-radius: 9999px;
913
+ }
914
+
915
+ #nd-toc .geistdocs-toc-scroll::-webkit-scrollbar-thumb:hover {
916
+ background-color: var(--color-gray-alpha-600);
901
917
  }
902
918
 
903
919
  [data-mobile-docs-bar] {