Writing Docs

Pages

Every page is a Markdown file with YAML front matter. Here's the full reference.

Documentation lives in resources/docs as Markdown files. Each file is one page. Directories become navigation groups (see organization), and the file's path becomes its URL.

Anatomy of a page

A page opens with a YAML front matter block, then Markdown:

markdown

---
title: Payment Methods
description: Add, update, and remove payment methods.
order: 2
---

You can store multiple payment methods and designate one as the default.

The title renders as the page heading and the browser tab; the description appears under the heading and is used for search and meta tags. Start your body at ##, since the title already provides the page's top-level heading.

Scaffolding a page

Rather than start from a blank file, scaffold a page from a content-type template:

bash

php artisan docent:make how-to billing/refunds

The type is one of tutorial, how-to, reference, or concept — the Diátaxis quartet. Each writes a starter page with the right front matter and a section outline for that shape: a how-to opens with a goal and steps, a reference with a scannable table, a concept with what-it-is and why-it-matters, a tutorial with a walkthrough. The slug is the file path under your docs root; pass --site to target a specific site and --force to overwrite an existing page.

Scaffolded pages start their body at ## and pass validation as-is, so you can fill one in and check it immediately.

Front matter reference

Every key is optional except title, which docent:check will remind you to add.

title: the page heading, tab title, and search title.
description: a short summary shown under the heading and used for search and meta.
order: an integer that sorts the page within its group. Lower comes first.
hidden: when true, the page is reachable by URL but doesn't appear in the navigation.
authorize: a gate ability that guards the whole page. See access control.
audience: a named audience that guards the whole page. See access control.
layout: docs (the default, with full navigation chrome), landing (hero and centered body), or a custom layout name.
redirect: send this slug to another location instead of rendering.
search.exclude: when true, the page stays out of the search index.
search.keywords: up to 12 alternate phrases that improve ranking without being rendered.
locked: when true, the web admin can't edit or override this page. The repository version always wins, even over a database copy that existed before the lock. Use it for legal text, security policies, or anything that must only change through a pull request.

The search-exclusion key is nested, so in YAML it reads:

yaml

---
title: Internal Notes
search:
  exclude: true
---

Use keywords when readers are likely to describe a task differently from the page itself:

yaml

---
title: Videos
search:
  keywords:
    - insert video
    - upload a movie
---

Keywords are ranking hints, not hidden page content. They never appear on the page, in result snippets, or in agent-readable Markdown. Each entry may be up to 80 characters, and docent:check reports malformed or oversized lists.

Slugs

Slugs come from the file path relative to your site's content directory (resources/docs for the shipped site), minus the .md extension:

resources/docs/billing/payment-methods.md → /docs/billing/payment-methods
resources/docs/getting-started/installation.md → /docs/getting-started/installation

Slugs are unique within a site. On a multi-site install, each site has its own directory and its own slug space, so two sites can both have a billing/refunds page without conflict.

index.md

An index.md inside a directory becomes that directory's own page. So resources/docs/billing/index.md is served at /docs/billing, the landing page for the group. In the sidebar, a nested group's index.md turns the group header itself into a link to it — see organization.

The index.md at the root of resources/docs is your home page, served at /docs. It's usually a landing page with a hero and a grid of cards, which is what the next section covers.

Landing pages

Set layout: landing to drop the sidebar, table of contents, and prev/next navigation in favor of a hero and a centered body. The hero is driven by front matter:

yaml

---
title: Give your app a guide
layout: landing
hero:
  badge: Documentation
  search: true
  cta:
    - label: Get started
      href: getting-started/installation
    - label: Learn more
      href: getting-started/configuration
      style: secondary
---

hero.badge adds an accent eyebrow pill above the title, and hero.search puts a prominent search-and-ask box in the hero. Each CTA button has a label, an href (an internal slug or an external URL), and a style: primary gets the accent, secondary gets a border. The home page of this site uses exactly this.

Landing pages stay out of the sidebar navigation automatically — readers reach them through the site name in the topbar, and both search and the URL still work. Prefer a homepage that sits in the sidebar like any other page? Just use the default docs layout.

Pair the hero with section cards for a help-center homepage, or go further with a fully custom layout.

Next, group your pages with organization, then reach for the authoring toolkit.