Frontmatter

Start from the template

Every documentation page opens with a frontmatter block. The writer sets five fields:

The title renders as the page’s H1. The body therefore starts at a ## heading, never at #. Write the title in sentence case, as Documentation terminology defines.

A validator runs inside every build. It stops the build when a namespace or a permalink is absent, malformed, or appears twice in the same language. The validator does not read the other fields, so their quality depends on the writer.

Set the namespace

The namespace identifies the page across the site. It is also the join key between languages: the English page and its Portuguese translation carry the same value, character for character. Bilingual pages describes the pairing in full.

Two rules apply:

• Keep the value unique within its language. A duplicate stops the build.
• Keep the value identical across the language pair. A mismatch breaks the language switcher, and the build still passes.

The second rule has no safety net. The switcher silently loses the connection between the two pages, so check the value by hand.

Write the value in lowercase words joined by underscores. Build it from the product and the feature: documentation_products_object_storage_bucket.

Set the permalink

The permalink is the page URL without the language segment. The permalink alone sets the URL; the file path does not.

• Do not add a language prefix. The directory tree provides it: a file in the English tree publishes at /en/ plus the permalink. A permalink that starts with /en/ publishes the page at /en/en/....
• Use lowercase ASCII letters, digits, hyphens, and slashes only, and end with a slash: /documentation/guides/application-development/data/create-and-modify-bucket/.
• Keep the permalink unique within its language. The English page and its Portuguese page have different permalinks, so the pair never collides.
• Fold accents out of Portuguese permalinks: configuracao, not configuração.
• Name the URL for the page’s place in the navigation: the section path, the segments of the rows above it, and the page’s own slug, as in /documentation/platform/firewall/waf/rules-set/. A page changes URL when its place in the navigation changes, and never when its file moves.
• Changing a permalink changes the URL, and the old URL then needs a redirect entry in the same change.

Write the description and meta tags

The description becomes the page’s meta description. The meta_tags value becomes its keywords, as a comma-separated list inside quotes.

No check validates either field, so an empty one ships silently. Write both on every page.

Write the description as one or two self-contained sentences, 50 to 160 characters long. Start with an imperative verb and state what the reader accomplishes on the page. Do not restate the title word for word. The rules in Sentence structure apply to the description.

Four openers are banned: This page describes..., This document explains..., Learn more about..., and Learn how to.... Start with the bare verb instead. A generic opener spends the description on framing instead of information.

Place the page in a sidebar

A page does not name its own sidebar. The navigation lists the page by its namespace, and the sidebar the reader sees is the one of the section that lists it. Register the page in the navigation, not in a frontmatter field.

The field also settles ownership: every page belongs to exactly one section. A section can list a page that another section owns, and that row is a cross-link rather than a claim. Keep ownership with the section where the page’s neighbors live.

Omit the type field

The frontmatter accepts an optional type field that switches a page to a special layout, such as a card-grid home. Documentation pages omit it. A page without the field uses the default layout, which is the right one for documentation content.