Landing Page

Docgo's landing page is a documentation entry point, not a product brochure. It should answer three questions quickly: what the project is, where to begin, and how readers can get useful work done.

#Start with the home layout

Set layout: home in docs/index.mdx. The starter produced by docgo init already includes a practical default:

1. A hero that introduces the project and links to the first guide.
2. Three features that explain the documentation experience.
3. A split section for installation or the smallest working example.
4. A steps section that explains the path from first visit to useful work.

Keep this order unless the project has a stronger first task to show.

#Write concrete copy

Use the hero for the project outcome, not a slogan. A good headline says what readers can accomplish; the tagline says what they will find in the docs.

hero:
  name: My project
  pattern: MY PROJECT
  text: A dependable way to run background work.
  tagline: Learn installation, configuration, and production patterns in one place.

Each feature should describe a real reader benefit. Prefer “Configure retries” over “Powerful configuration,” and “Find migration notes” over “Everything you need.”

Use hero.pattern for a quiet dot-matrix background wordmark when the hero needs more presence. Keep it short so it remains a supporting texture, not a second headline.

#Customize the preview

The hero preview can render a local .md, .mdx, or .html file. Use it for a small product, SDK, console, or workflow snapshot instead of leaving generic documentation copy in place.

hero:
  preview: ./_home-preview.mdx

# Acme console

<div className="preview-status">Production is ready</div>

```bash [deploy]
acme deploy --target production
```

Files or folders beginning with _ are useful for preview partials because Docgo can render them into the hero, but does not generate standalone pages for them.

Use hero.preview: false or omit hero.preview to render no preview panel. Use hero.image when a real product screenshot communicates the project better than custom markup.

#Use sections with intent

split works best for a short install flow, first command, or compact code example. Set language when the sample is not shell code; Docgo uses the same Shiki highlighting as documentation code blocks.

sections:
  - type: split
    title: Install and run the first worker.
    code: |-
      npm install my-project
      npm run dev
    language: bash

Use steps for a short workflow such as install → configure → deploy, or write → review → publish. It is more useful than generic statistics on most project homepages because it explains what a new reader should do next.

#Control heading line breaks

Hero text and tagline, feature titles and descriptions, and section headings use the full available width. When a deliberate line break improves the composition, write the field as a YAML block; each newline becomes a <br> in the rendered text.

- type: steps
  title: |-
    Start quickly.
    Keep answers close.
  details: |-
    Begin with the first useful page.
    Add structure only when it helps.

The literal <br> form is supported too, but YAML blocks are easier to read and edit.

cards, stats, and cta are optional. Add them only when the project has specific content for them: genuine ecosystem resources, stable facts, or one important final action. See Layouts for every field.

#Keep it maintainable

The entire landing page is frontmatter. When you reuse the format in another repository, replace the project name, first command, feature copy, and steps before changing the layout. Use the existing design tokens first; introduce a --dg-* token only for a visual role that is specific to Docgo.