Build with AI

This document is an implementation brief for AI coding agents. If a user gives you this file, its contents, or its URL, use it as the authoritative workflow for adding or improving Docgo in the project they placed in scope.

Docgo is a static documentation site generator built on React, MDX, and Vite. It turns Markdown and MDX into deployable HTML with a responsive documentation theme, static search, SEO output, locale and version routing, component previews, and raw Markdown pages for AI readers.

Package: @kyechan99/docgo

Official documentation: Docgo documentation

#Goal

Build a working Docgo documentation site that fits the existing project. Do not merely describe the setup or paste an example unless the user requested instructions only. Inspect the repository, implement the integration, and verify a production build.

#Operating rules

1. Inspect the project before changing it. Read its package manifest, lockfile, existing documentation, repository instructions, build scripts, public assets, and deployment configuration when present.
2. Preserve the project's package manager and conventions. Infer the package manager from the lockfile and use its normal install and run commands.
3. Preserve existing content. Do not replace a README, documentation tree, config file, logo, or deployment workflow without a clear user request.
4. Keep changes scoped to documentation. Do not refactor application code just to introduce Docgo.
5. Prefer the smallest useful configuration. Enable advanced features only when the repository or the user's request provides a reason for them.
6. Use current installed package types and the official documentation when an option is uncertain. Do not invent Docgo config fields or MDX syntax.
7. Finish by running the Docgo production build. Report any remaining blocker with the exact command and error.

#Choose the integration path

#New documentation site

When the project has no meaningful documentation structure, install Docgo and run its non-destructive initializer:

npm install @kyechan99/docgo
npx docgo init

Use the equivalent commands for pnpm, Yarn, or Bun. The initializer skips files that already exist. After it runs, replace placeholder names, URLs, navigation, and starter copy with project-specific values.

#Existing documentation

When Markdown, MDX, or another documentation system already exists, do not run an initializer blindly. First map the existing content, links, assets, routes, locales, versions, and deployment behavior. Then install Docgo, create a focused docgo.config.mjs, and migrate incrementally.

Keep source documents in place when practical by setting docsDir. If files must move, update relative links and asset references and verify the affected routes.

#Existing Docgo site

When docgo.config.mjs or an existing Docgo dependency is present, improve the current integration instead of scaffolding another one. Read the installed version and existing config first. Preserve intentional custom plugins, MDX components, styling, route structure, and deployment settings.

#Required project setup

Docgo requires Node.js ^20.19.0 or >=22.12.0.

Add scripts to the existing package.json without removing unrelated scripts:

{
  "scripts": {
    "docs:dev": "docgo dev",
    "docs:build": "docgo build"
  }
}

Use a minimal root config as a starting point:

import { defineConfig } from '@kyechan99/docgo';

export default defineConfig({
  title: 'Project name',
  description: 'What this project does and who the documentation is for.',
  docsDir: 'docs',
  outDir: 'dist',
  baseUrl: '/',
  siteUrl: 'https://docs.example.com',
});

Set siteUrl to the real production origin. Set baseUrl to the deployed subpath, such as /project/, when the site is not hosted at the domain root. If the deployment destination is unknown, call that out rather than guessing a production URL.

Do not copy a large sample config into a project. Add options as the content requires them.

#Build the content structure

Use .md for ordinary documentation and .mdx when the page needs imported components or JSX. A useful first structure is:

docs/
  index.mdx
  guide/
    getting-started.mdx
    configuration.mdx
  reference/
    api.mdx
docgo.config.mjs
head.html
public/
package.json

Create only pages supported by real project information. Prefer concise, task-oriented pages over empty category placeholders.

Each page should have useful frontmatter:

---
title: Getting Started
description: Install the project and complete the first working task.
navTitle: Getting Started
order: 1
---

For the root landing page, use layout: home when the project benefits from a hero, actions, feature cards, or workflow sections. Use the normal docs layout for reference content and layout: page only for intentionally custom, full-width pages.

#Select features intentionally

Docgo provides the following built-in capabilities. Use this list to recognize what is available, but do not enable every optional feature automatically.

• Markdown, MDX, GitHub-Flavored Markdown, frontmatter, emoji shortcodes, containers, steps, alerts, code groups, code highlighting, line annotations, file includes, snippet imports, playgrounds, and API reference layouts.
• Responsive header, sidebar, table of contents, breadcrumbs, previous/next links, dark mode, social links, edit links, last-updated metadata, and footer.
• Local static search with generated JSON indexes, or a custom search provider.
• Home, documentation, and full-width page layouts.
• Static HTML with client-side page transitions and independently hydrated React islands.
• Interactive React examples through ClientPreview, preview modules, providers, stylesheets, iframe isolation, and inline isolation.
• Locale-aware routes, translated navigation, and locale switching.
• Folder-based documentation versions, version switching, and release snapshots through docgo version <name>.
• Favicons, canonical URLs, Open Graph, Twitter cards, JSON-LD, sitemap, robots.txt, llms.txt, and per-page noindex controls.
• A raw .md mirror for every generated page, used by AI tools and the built-in View as Markdown actions.
• Plugin hooks for resolved config, MDX source, remark, rehype, Vite, and generated-page observation.
• Custom MDX components, public assets, raw head HTML, structured head entries, custom fonts, and CSS overrides.

Use these defaults unless project evidence suggests otherwise:

• Keep local search enabled.
• Keep Markdown mirrors and llms.txt enabled.
• Keep JSON-LD, robots output, and sitemap enabled; sitemap generation requires a valid siteUrl.
• Add i18n only when translated source content exists or is requested.
• Add versioning only when multiple maintained documentation versions exist.
• Add interactive previews when documenting React components or a design system; do not turn static examples into client islands unnecessarily.
• Add plugins only for a concrete transformation or integration need.

#Navigation and routing

Derive navigation from the pages that actually exist. Use nav for the header and sidebar for the documentation hierarchy. Docgo links are content-relative and automatically receive active locale and version prefixes.

Source paths map to clean routes. For example:

docs/index.mdx                    -> /
docs/guide/start.mdx              -> /guide/start
docs/en/latest/guide/start.mdx    -> /guide/start
docs/ko/latest/guide/start.mdx    -> /ko/guide/start
docs/en/v1/guide/start.mdx        -> /v1/guide/start

When enabling locales or versions, follow the folder structure documented by Docgo rather than encoding locale or version prefixes manually into every nav item.

#Styling and components

Prefer Docgo's theme and stable configuration surface before adding custom CSS. Put static files in public. Use head.html for verification tags, analytics, fonts, or a custom stylesheet. Preserve accessible labels, useful HTML without JavaScript, and responsive behavior.

Register project-specific MDX components through mdxComponents. For browser-stateful examples, create preview modules under docs/previews or register them through clientPreviews; use <ClientPreview /> in the page.

#Deployment

Docgo writes a static site to outDir, which defaults to dist. Integrate that directory with the project's existing static hosting or CI workflow. Preserve an existing deployment provider when possible.

Before changing deployment configuration, determine whether the site is hosted at / or a subpath. A wrong baseUrl breaks assets and navigation even when the local build succeeds.

#Verification checklist

Complete all applicable checks before considering the integration finished:

1. Install dependencies with the repository's package manager.
2. Run the documentation production build, normally npm run docs:build or its package-manager equivalent.
3. Confirm the configured output directory exists and contains index.html.
4. Confirm representative nested routes generated the expected HTML paths.
5. Confirm internal navigation and public asset URLs include the correct baseUrl.
6. Confirm search indexes exist when search is enabled.
7. Confirm raw Markdown mirrors and llms.txt exist.
8. Confirm sitemap and canonical URLs use the real production URL when siteUrl is configured.
9. Run the repository's relevant lint, typecheck, or test commands when the documentation change affects code or shared configuration.
10. Summarize created and modified files, commands run, verification results, and any values the user still needs to supply.

#Official references

• Getting started
• Project structure
• Configuration
• Config reference
• Markdown and MDX
• Layouts
• Search
• Preview components
• Locales and routing
• Versioning
• Plugins
• SEO and AI output
• Deployment

If a linked reference conflicts with this brief because Docgo has changed, follow the documentation for the version installed in the project.