Deployment

Choose static or Nitro hosting, build the right output, and verify every public surface before release.

Ginko Docs supports static hosting and Nitro deployments. Choose the target from the request-time behavior you need, not from the shape of the documentation pages: both targets can serve the same rendered content.

Choose a deployment target

Capability	Static host	Nitro server, serverless, or hybrid
Documentation and blog pages	Prerendered HTML	Prerendered or rendered by Nitro
Navigation and MiniSearch	Included in generated assets	Included in application assets
Sitemap, robots, and social images	Generated files	Generated files served with the application
`/raw/**.md`	Generated files	Available
`/llms.txt` and `/llms-full.txt`	Generated files	Available
Localized raw and LLM routes	Generated files	Available
`Accept: text/markdown` on a page URL	No	Yes
Agent link and content-signal response headers	No request-time middleware	Yes
`/mcp` with `list-pages` and `get-page`	No	Yes
Request-time provider reads	No; content is fixed at build time	Yes, when the provider supports them

The Copy Markdown menu uses the explicit raw route, so it works on static hosting when the generated /raw/**.md files are deployed. Its ChatGPT, Claude, and MCP entries are presentation controls; changing markdownActions does not enable or disable the underlying server routes.

Generate a static site

Run Nuxt generation from the consuming application:

terminal

pnpm generate

Deploy the complete .output/public directory. Ginko Content contributes public page routes, raw Markdown, and LLM catalogs to prerendering. The layer also requests /sitemap.xml, /robots.txt, /llms.txt, and /llms-full.txt explicitly.

Serve the generated directory over HTTP before release:

terminal

pnpm dlx serve .output/public

Opening an HTML file through file:// does not test host routing, asset paths, redirects, or fallback behavior.

Build a Nitro deployment

Build and preview the production server locally:

terminal

pnpm build
pnpm preview

Deploy .output with the Nitro preset required by the host. Keep provider clients and credentials in server-only files. The filesystem provider uses the content snapshot prepared during the build; an external provider can read at request time when its runtime and credentials are available on the target.

Same-URL Markdown negotiation and /mcp require Nitro to handle the request. A CDN may cache those responses, but it must forward the Accept header when Markdown negotiation is used.

Keep public URLs consistent

Use the same production origin wherever the site URL is configured:

site.json

{
  "name": "Example Docs",
  "description": "Documentation for Example.",
  "url": "https://docs.example.com"
}

content.config.ts

import { defineGinkoDocsConfig } from "@lupinum/ginko-docs/content";
import site from "./site.json" with { type: "json" };

export default defineGinkoDocsConfig({
  site,
});

app/app.config.ts

import site from "../site.json";

export default defineAppConfig({
  ginkoDocs: {
    site: {
      url: site.url,
    },
  },
});

nuxt.config.ts

import site from "./site.json" with { type: "json" };

export default defineNuxtConfig({
  extends: ["@lupinum/ginko-docs"],
  site: { url: site.url },
  i18n: { baseUrl: site.url },
});

Ginko Docs uses the app-config URL for canonical links, structured data, raw links, and MCP links. Ginko Content uses the content-config URL in agent catalogs.

Verify the deployed output

Check the deployment itself, not only the local build log:

Direct-load the home page, the first docs page, a nested docs page, and a missing URL.
Open representative pages in every configured locale and inspect canonical and alternate links.
Follow the section switcher, sidebar links, previous and next links, and search results.
Confirm /sitemap.xml, /robots.txt, /llms.txt, and /llms-full.txt return the expected content type.
Fetch one generated /raw/**.md URL and confirm drafts and private data are absent.
On Nitro, request a page with Accept: text/markdown and call /mcp only if those capabilities are part of the deployment contract.
Inspect browser and server logs for hydration errors, missing assets, and failed social-image routes.