Docs Heroes

Docs heroes are docs-set-first hero fields and components for product, landing, and docs entry pages. They link directly to a docs set and can use the selected docs set for default headings, descriptions, action hrefs, media, and skill buttons.

Field Helper

docsHeroField adds the docs hero variants to a Payload hero field. It can stand alone, or it can merge into an existing Payload website template hero group.

1import type { CollectionConfig } from 'payload'2 3import { docsHeroField } from '@valkyrianlabs/payload-markdown-docs/fields'4import { hero } from '@/heros/config'5 6export const Pages: CollectionConfig = {7  slug: 'pages',8  fields: [9    {10      type: 'tabs',11      tabs: [12        {13          label: 'Hero',14          fields: [15            docsHeroField({16              hero,17            }),18          ],19        },20      ],21    },22  ],23}

When a local hero field is provided, its existing type picker is preserved and the docs variants are appended:

• docsSetFullWidth
• docsSetSideImage
• docsSetSideInfo

docsSetFullWidth is a centered, full-background landing hero. docsSetSideImage uses a true side media layout with skill buttons under the copy. docsSetSideInfo keeps the faux browser/info panel and embeds available skill buttons inside that panel.

Local hero fields are hidden while a docs hero variant is selected. Docs hero fields are hidden while a local hero variant is selected.

Standalone Field

If the app does not have a local hero field, use the standalone docs hero field:

1import { docsHeroField } from '@valkyrianlabs/payload-markdown-docs/fields'2 3fields: [docsHeroField()]

Docs heroes are scoped to a selected docs set. The heading field is optional only when the selected docs set has a title. Description remains optional.

Plugin Install

The plugin can wrap existing hero fields on the configured pages collection:

1import { payloadMarkdownDocs } from '@valkyrianlabs/payload-markdown-docs'2 3payloadMarkdownDocs({4  heroes: true,5})

For pages-only scoping:

1payloadMarkdownDocs({2  pages: {3    heroes: true,4  },5})

For collection-level scoping:

1payloadMarkdownDocs({2  collections: {3    pages: {4      heroes: true,5    },6  },7})

The installer searches the collection fields, including tabs, for a group named hero. If it finds one, it wraps it. If it does not find one, it installs a standalone docs hero field named hero.

Rendering

Render docs hero variants inside your existing hero renderer:

1import type { FC } from 'react'2import type { Page } from '@/payload-types'3 4import { docsHeroComponents } from '@valkyrianlabs/payload-markdown-docs/next'5 6import { HighImpactHero } from './HighImpact'7import { LowImpactHero } from './LowImpact'8 9const heroes: Record<string, FC<Page['hero']>> = {10  ...docsHeroComponents,11  highImpact: HighImpactHero,12  lowImpact: LowImpactHero,13}14 15export function RenderHero(props: Page['hero']) {16  const { type } = props || {}17 18  if (!type || type === 'none') return null19 20  const HeroToRender = heroes[type]21 22  if (!HeroToRender) return null23 24  return <HeroToRender {...props} />25}

The docs hero components accept the normal spread Payload field shape. Data hydration runs through the plugin afterRead resolver, so id-only docs set relationships are expanded before render when the plugin installed or wrapped the field.

Custom Components

Use hero components directly on custom Set or Group pages. Pass URLs from your own route logic or from already-resolved docs data.

1import { DocsProductHero } from '@valkyrianlabs/payload-markdown-docs/next'2 3export function SetLandingPage({4  set,5}: {6  set?: { description?: string; href?: string; title?: string }7}) {8  return (9    <DocsProductHero10      eyebrow={set?.title}11      heading="Build faster with the docs"12      description={set?.description ?? 'Explore guides, API references, and downloadable skills.'}13      primaryAction={{14        label: 'Read the docs',15        href: set?.href ?? '/docs',16      }}17      skills={{18        enabled: true,19        display: 'buttons',20        resolvedItems: [21          {22            label: 'Codex skill',23            type: 'codex',24            href: '/plugins/payload-markdown-docs/skills/codex.zip',25          },26        ],27      }}28    />29  )30}

For docs-native pages, use DocsNativeHero:

1import { DocsNativeHero } from '@valkyrianlabs/payload-markdown-docs/next'2 3<DocsNativeHero4  breadcrumb={[{ label: 'Docs', href: '/docs' }, { label: 'Configuration' }]}5  title="Configuration"6  description="Plugin options, routing behavior, and sync settings."7/>