Docgo selects a layout from page frontmatter.

page frontmatter

---
layout: ''
---

Docs layout

The default layout is the documentation article layout.

docs/guide/getting-started.mdx

---
title: Getting Started
description: Install and configure Docgo.
---

# Getting Started

It includes:

header navigation
sidebar
article title and description
markdown action menu
table of contents
edit link and last-updated metadata
prev/next links
footer

Use this layout for normal documentation pages.

Page layout

Use layout: page for custom, full-width pages.

docs/showcase.mdx

---
layout: page
title: Showcase
---

<section className="hero">
  <h1>Build documentation faster</h1>
</section>

This layout keeps the header, footer, search, theme toggle, and mobile navigation, but removes the desktop sidebar, article chrome, and right-side TOC.

Use it for landing pages, custom examples, status pages, or pages composed with your own components.

Home layout

Use layout: home for a structured homepage generated from frontmatter.

This is the reusable default for project documentation. Change the product name, headline, actions, and feature cards; the responsive preview and subtle halftone background are included automatically.

docs/index.mdx

---
layout: home
title: Home
hero:
  name: Project name
  text: A clear home for your project documentation.
  tagline: Explain what readers can find here in one or two practical sentences.
  preview: ./_home-preview.mdx
  actions:
    - text: Get started
      link: /guide/getting-started
      theme: brand
    - text: Repository
      link: https://github.com/owner/repository
      theme: alt
features:
  - icon: WRITE
    title: Write with Markdown
    details: Describe the documentation format or authoring workflow.
  - icon: FIND
    title: Find answers quickly
    details: Describe the main navigation or search benefit.
  - icon: SHIP
    title: Ship with confidence
    details: Describe the project outcome or release workflow.
---

Additional MDX content can appear below the generated hero and feature grid.

Home hero fields

Field	Type	Description
`hero.name`	`string`	Main product or site name.
`hero.pattern`	`string`	Optional dot-matrix background wordmark.
`hero.text`	`string`	Large heading text below the name.
`hero.tagline`	`string`	Supporting copy.
`hero.image`	`string \| { src, alt? }`	Optional hero image.
`hero.preview`	`string \| { source } \| false`	Local file rendered in the preview slot.
`hero.actions`	`{ text, link, theme? }[]`	CTA links. `theme` can be `brand` or `alt`.

hero.preview can point at a local .md, .mdx, or .html file. Docgo renders that file inside the preview panel, so the hero can show project-specific UI, a command flow, an API response, or any MDX content.

docs/index.mdx

hero:
  preview: ./_home-preview.mdx

docs/_home-preview.mdx

# Project workspace

<p className="lead">Show a screenshot-like panel, command flow, or API response.</p>

```bash [first useful command]
npm run docs
```

Use _-prefixed preview files for partial content. They can be rendered inside the hero preview but are not generated as standalone docs pages.

You can also write the source as an object:

docs/index.mdx

hero:
  preview:
    source: ./_home-preview.html

Set hero.preview: false or omit hero.preview to render no preview panel. Supply hero.image when a real screenshot communicates the project better.

Feature fields

Field	Type	Description
`icon`	`string`	Short icon text.
`title`	`string`	Feature title.
`details`	`string`	Feature description.
`link`	`string`	Optional link wrapping the feature.

Landing sections

Use sections for the optional blocks below the hero and feature cards. Each entry has an optional eyebrow, title, details, and actions array. Only the sections you configure are rendered.

docs/index.mdx

sections:
  - type: split
    eyebrow: EXAMPLE
    title: Show the first useful command.
    details: A two-column section for a quickstart, example, or integration.
    code: |-
      npm install your-project
      npm run dev
    language: bash
    actions:
      - text: Read the guide
        link: /guide/getting-started
        theme: alt
  - type: stats
    eyebrow: AT A GLANCE
    title: Make important facts easy to scan.
    items:
      - value: Static
        title: Output
        details: Portable files ready to host.
  - type: cards
    eyebrow: COMMUNITY
    title: Put people and project links in one place.
    items:
      - label: CONTRIBUTE
        title: Join the project
        details: Link to contribution guidance or discussions.
        link: https://github.com/owner/repository
  - type: steps
    eyebrow: WORKFLOW
    title: Explain the path from first visit to useful work.
    details: Use three steps for onboarding, adoption, or a project workflow.
    items:
      - label: WRITE
        title: Start with the first useful page
        details: Lead with the question people ask most often.
      - label: SHAPE
        title: Make the structure yours
        details: Tune the docs around your project.
      - label: SHARE
        title: Keep it easy to return to
        details: Publish a dependable home for the project.
  - type: cta
    eyebrow: READY
    title: End with one clear next step.
    actions:
      - text: Get started
        link: /guide/getting-started
        theme: brand

Type	Use it for
`split`	An install flow, code sample, migration note, or product example.
`stats`	Project facts, supported environments, release status, or numbers.
`cards`	Contributors, sponsors, partners, ecosystem links, or resources.
`steps`	A short onboarding, adoption, or project workflow.
`cta`	A focused final action such as installation, downloads, or support.

Card items accept title, details, label, link, and an optional image. Stats use value, title, and details. This keeps the same layout usable whether a project has a contributor list, sponsor logos, neither, or both. For a split section, set language to a supported Shiki language such as bash, ts, tsx, json, or yaml; bash is the default.

page and home layouts still render a mobile sidebar. When no sidebar is available, Docgo builds a mobile navigation tree from the header nav items.

404 pages

Docgo writes a ready-to-use 404.html for static hosts. Add 404.mdx beside your home page when the complete fallback content needs to be project-specific. It uses the normal page canvas by default, so the header and footer remain available while you control everything in between.

docs/404.mdx

---
layout: page
title: Page not found
---

<section className="my-not-found">
  <p>404</p>
  <h1>That link has moved.</h1>
  <a href="/">Back to the documentation</a>
</section>

For localized or versioned sites, place the file alongside that version’s index.mdx (for example, docs/ko/latest/404.mdx). Docgo selects the closest matching fallback when a visitor reaches an unknown URL.

Layouts

Docs layout

Page layout

Home layout

Home hero fields

Feature fields

Landing sections

Mobile navigation

404 pages

Layouts

#Docs layout

#Page layout

#Home layout

#Home hero fields

#Feature fields

#Landing sections

#Mobile navigation

#404 pages

Docs layout

Page layout

Home layout

Home hero fields

Feature fields

Landing sections

Mobile navigation

404 pages