Getting Started

Layouts

Pick a built-in page layout, compose a help-center homepage, or design your own layout — without forking a single package view.

Every page picks its layout with one front matter key. Most pages never set it and get the full documentation chrome; a homepage usually wants something bolder. This page covers the built-in layouts, the help-center recipe, and how to design a completely custom layout that survives package updates.

The docs layout

The default. Sidebar navigation, table of contents, breadcrumbs, and prev/next links — everything a reference page needs. Any page without a layout key uses it.

The landing layout

Set layout: landing to trade the chrome for a hero and a centered body. The hero is driven entirely by front matter:

yaml

---
title: Acme Ledger
description: The developer-friendly accounting platform.
layout: landing
hero:
  badge: Documentation
  search: true
  cta:
    - label: Get started
      href: getting-started/installation
    - label: Core concepts
      href: getting-started/concepts
      style: secondary
---

hero.badge: an accent-colored eyebrow pill above the title.
hero.search: when true, a prominent search box sits front and center in the hero. It opens the same search-and-ask dialog as the topbar button, and while it's visible the topbar's own search button stays hidden — it fades in once the hero scrolls out of view, so there's one search affordance at a time.
hero.cta: buttons under the hero. Each takes a label, an href (an internal slug or external URL), and a style of primary (accent) or secondary (bordered).

The page's title and description become the hero heading and subheading, and the Markdown body renders centered beneath it.

Landing and custom-layout pages don't appear in the sidebar navigation — they are jump-off points, not stops along a section, and readers return to them through the site name in the topbar. The page stays fully reachable at its URL and in search. If you want your homepage listed in the sidebar like any other page, give it the default docs layout instead.

A help-center homepage

Combine hero.search with the :::section-cards directive and your homepage becomes a classic help center — big search box up top, a card per category beneath, each with an icon, description, and article count:

markdown

---
title: Acme Ledger
description: The developer-friendly accounting platform.
layout: landing
hero:
  search: true
---

Browse a category to get started.

:::section-cards
:::

Because section cards are generated from the navigation tree, they inherit Docent's per-viewer filtering: a category a reader can't access simply isn't there, and the article counts only count what they can see. The grid also maintains its own balance, so a hidden card never leaves a hole.

Custom layouts

Any other layout value resolves to a view, so a fully custom homepage is one Blade file — no package views published, nothing forked, nothing to merge on update.

Name a layout in front matter:

yaml

---
title: Home
layout: help-center
---

Docent resolves the view in two steps:

A layouts entry in your site's config wins, and may point at any view in your application:
php
```
// inside sites.docs
'layouts' => [
    'help-center' => 'docs.help-center',
],
```
Layout maps belong to a site, so on a multi-site install each site declares its own.
Otherwise the name resolves to docent::layouts.<name>, which Laravel looks up in resources/views/vendor/docent/layouts/ before the package's own directory. Drop a new help-center.blade.php there and you're done.

An unknown layout throws rather than silently falling back, so a typo surfaces immediately instead of shipping a subtly wrong page.

A custom layout usually extends the shell to keep the topbar, theme handling, search dialog, and assistant panel:

blade

@extends('docent::layout')

@section('content')
    <x-docent::hero :docent="$docent" :title="$title" :description="$description" search />

    <div class="docent-prose mx-auto mt-12 max-w-5xl">
        <x-docent::section-cards columns="2" />
        {!! $html !!}
    </div>
@endsection

The view payload

Every layout — built-in or custom — receives the same data:

$docent: the DocentManager, for URLs, assets, and theme values.
$page: the current Page.
$context: the viewer's DocumentationContext.
$title / $description: the page's front matter.
$html: the rendered page body.
$sections: the viewer-filtered navigation sections.
$topbarLinks, $siteName, $homeUrl, $currentSlug, $searchEnabled.
$heroBadge, $heroCta, $heroSearch: the hero front matter, resolved.

Composable components

Three Blade components let a custom layout reuse the built-in pieces instead of rebuilding them:

<x-docent::hero>: the full hero — glow, badge, title, description, search box, and CTA buttons. Takes docent, title, description, badge, cta, and search props, plus a slot for extra content.
<x-docent::search-box :docent="$docent" size="lg" />: a search box that opens the search-and-ask dialog. The default size suits inline placement; lg is the hero-scale variant.

Both hero and search-box need the docent prop so they know which site they belong to; pass along the $docent your layout already receives.

<x-docent::section-cards section="billing" columns="2" />: the same permission-aware card grid as the Markdown directive, for use anywhere in Blade.

The shell's topbar has two overridable regions. Define the section to replace it; define it empty to remove it. Everything else — logo, theme toggle, the search dialog itself — stays put.