What NextGuide creates
A complete documentation website with working components, search, navigation, and editable project files.
Every generated file, explained
The Developer Mode installer generates a documentation website with editable source files. The new starter has a responsive sidebar, mobile navigation, local search with Ctrl/Cmd+K, light/dark/system appearance, clickable breadcrumbs, page actions and a sticky page table of contents.
my-docs
- nextguide.config.json
content
docs
- _meta.json
- index.mdx
- getting-started.mdx
- api-reference.mdx
guides
- _meta.json
- writing.mdx
- customization.mdx
components
- _meta.json
- index.mdx
- examples.mdx
src
lib
- nextguide.ts
- nextguide-mdx-components.tsx
styles
- nextguide.css
app
docs
- layout.tsx
[[...slug]]
- page.tsx
What the files do
| Path | Purpose |
|---|---|
nextguide.config.json | Name, description, base URL, default theme and accent |
content/docs/index.mdx | Documentation homepage with live blocks |
content/docs/getting-started.mdx | Onboarding guide with component examples |
content/docs/guides/ | Writing and customization tutorials |
content/docs/components/ | Component gallery that actually renders tabs, cards, accordions and more |
content/docs/api-reference.mdx | Starting point for an API reference |
content/docs/**/_meta.json | Navigation section names and ordering |
src/lib/nextguide.ts | MDX source, plugins, code highlighting, searchable page index |
src/lib/nextguide-mdx-components.tsx | Editable registry of built-in NextGuide MDX components |
src/app/docs/layout.tsx | Renders the shared documentation layout with a Next.js client-navigation adapter (nextguide/site/next) so page changes preserve the sidebar and browser theme |
src/app/docs/[[...slug]]/page.tsx | Builds documentation routes, headings, breadcrumbs, page actions and TOC |
src/styles/nextguide.css | Tailwind 4 utilities, package-class discovery and official design tokens imported from nextguide/site.css; you can override theme values here |
Components work on first install
The installer automatically registers NextGuide's actual components with the MDX engine. You can use them in new pages immediately:
<Callout kind="tip" title="Ready">No separate registry installation.</Callout>
<CodeWindow language="bash" code="bun run dev" />The registry includes callouts, code windows and tabs, file trees, steps, link cards, buttons, cards, tabs, accordions, input fields, tables, alerts and more. Edit nextguide-mdx-components.tsx to add your own.
Where the design comes from
There is only one documentation design. The official NextGuide website in apps/web and the documentation generated by nextguide init --developer import the same components from nextguide/site. This includes the sticky sidebar, mobile drawer, Ctrl/Cmd+K search, appearance switcher, MDX reading column, breadcrumbs, page actions, table of contents, and previous/next links. The generated App Router site also uses nextguide/site/next for client-side links and search navigation. The official development-version selector is not included in installed sites.
The official light/dark color tokens are published as nextguide/site.css. The installer writes a Tailwind 4 stylesheet that imports those tokens and scans nextguide/dist, so the package's actual UI classes are compiled into the consuming application. Inter and JetBrains Mono are loaded using Next.js font helpers, just as in the official documentation.
The older DocsStarterShell remains exported for compatibility with existing alpha installations, but new installations do not use it.
App Router and Pages Router
The installer supports both routers, JavaScript or TypeScript, with and without src/. For Pages Router, it generates pages/docs/[[...slug]].tsx and adds the required imports to _app. Documentation can live at /docs or at the site root using --base-path /.
Updating an existing site
New installations receive the full site immediately. Existing users should first preview bunx nextguide upgrade --refresh-generated --dry-run. A confirmed refresh backs up generated layouts and styles, preserves custom MDX and navigation, and never overwrites files without the NextGuide-generated marker.
bunx nextguide upgrade --refresh-generated --dry-run