Skip to main content

​
Frontmatter Standards

Applies to: All document types
Back to overview: Content Standards

​
What frontmatter is

Every MDX page in the Aviatrix docs requires a YAML frontmatter block at the top of the file. Mintlify reads this block to render the page title, generate meta descriptions for search engines, and index keywords for site search.

​
Required fields

​
title

The title field renders as the page’s H1 heading in Mintlify. Do not add a # heading in the body of the document — it will produce a duplicate H1. Body content starts at H2 (##). Never use H1 (#) anywhere in the MDX body. Each doc type has its own title naming convention — see the relevant doc type definition for the format and examples.

​
description

The description renders as the meta description in search engine results. Write it as a complete sentence, under 160 characters, that can stand alone without the page title for context. Good description: "How Aviatrix uses distributed enforcement to secure east-west traffic across multi-cloud environments." Weak description: "Overview of DCF features and capabilities." — too vague to be useful in search results.

​
keywords

Keywords are used by Mintlify’s site search to surface pages for relevant queries. Include:
  • The primary subject name (feature name, component name, product area)
  • Common alternative terms or abbreviations readers might search for
  • The task type, if applicable (configuration, troubleshooting, reference)
  • Related product areas
Each doc type definition notes any additional keyword strategy specific to that type (for example, Reference docs should include version numbers; Operational Guides should include symptom terms readers are likely to search for).

​
Search optimization

Frontmatter is the primary lever for search discoverability — both in Mintlify’s site search (Algolia) and in external search engines. The fields that matter most are description and keywords, but heading text and the first paragraph of each page also carry indexing weight.

​
Write for the searcher, not the author

The most common mistake is writing descriptions and keywords that describe the document rather than matching what a user would type to find it. A user diagnosing a problem does not search “CoPilot Gateway Health UI Reference” — they search “gateway showing unhealthy in CoPilot” or “aviatrix gateway health check false positive.” Write every description as an answer to an implicit search query. Ask: What problem is this reader trying to solve, and how would they have phrased that problem in a search box?

​
Description field

The description renders as the search result snippet — it is the line of text below the title in Google and Mintlify search results. Optimize it accordingly:
  • Front-load the key concept. Search engines weight the first 60–80 characters most heavily. Put the most important term first, not last.
  • Match the reader’s intent, not the document’s content. “How to configure BGP route approval in Aviatrix CoPilot” will outperform “Reference for the BGP Route Approval settings page.”
  • Include at least one term the reader would actually type. If no phrase in your description matches a realistic search query, rewrite it.

​
Keywords field

Keywords power Mintlify/Algolia site search. Include all of the following that apply:
  • Primary feature name — the exact product name as written in the UI and docs
  • Acronyms and abbreviations — if DCF has a page, include both distributed-cloud-firewall and dcf
  • Symptom and problem terms — what a user searches when something is wrong: gateway-unhealthy, bgp-not-advertising, tunnel-down. These are especially important in Operational Guides and FAQs.
  • Alternate names — terms a user might know this feature by from a previous vendor or general industry usage
  • Action verbs for task docs — configure, upgrade, troubleshoot, enable, migrate
  • Version numbers — for release-specific docs (Release Notes, Upgrade Guides), include the version string: 8.2, 8.2.0
Aim for 5–10 keywords. More than 12 dilutes signal.

​
Heading and first paragraph weight

Mintlify’s Algolia index treats heading text and the first paragraph of each section with higher weight than body content. Write H2 and H3 headings as findable phrases — not clever labels. “What it does” is invisible to search; “How Distributed Cloud Firewall enforces east-west policy” is not. The first sentence of the page body (after frontmatter) also carries extra indexing weight. Use it to restate the core concept in plain language, including the key term.

​
Consistency rules

  • All three fields are required on every document
  • Do not use quotation marks inside keyword values
  • Keywords are a comma-separated string — no brackets: keywords: dcf, firewall, segmentation
  • Keywords should be lowercase; use hyphens for multi-word terms
  • The description should not duplicate the title word-for-word — it should complement it

​
Example blocks by tier

Concepts & Architectures
Guides
Reference