---
seo:
    title: "Portal Frontmatter"
    description: "How the portal reads documentation directly from a mounted git-managed folder with no build step."
llm_context: "Reference introduction to the portal architecture - the mounted storage/docs folder, native rendering without a build or conversion step, and where images live."
category: "reference"
related:
    - "/portal/reference/navigation"
    - "/portal/guides/organisation"
    - "/portal"
---

## Front Matter

Every Markdown file in the `docs/` folder may start with a YAML front matter block, which provides additional metadata for the page. This metadata is designed for two audiences: search engines, and LLMs (for instance, when a user copies and pastes a page's Markdown into a chat window).

The block must start and end with `---` delimiters, which must sit on the very first line of the file.

```yaml
---
seo:
    title: Authentication Guide
    description: How to authenticate using OAuth 2.0.
    keywords: [authentication, oauth, api keys]
    noindex: false
llm_context: >
    This guide covers first-party OAuth only. For partner/service-account
    auth, see the API Keys guide instead.
---
```

### Available Attributes

| Field         | Purpose                                                                                                                                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `seo.*`       | Series of SEO-specific attributes converted into HTML `<metadata>` tags to help search engine indexing. See [SEO-Specific Attributes](#seo-specific-attributes)                                                                            |
| `llm_context` | Descriptive, contextual information intended for LLM consumption, not for SEO. Intended for content that genuinely differs from `seo.description` — scope, prerequisites, disambiguation — not just a longer version of the same sentence. |
| `category`    | A free-text classification, e.g. `concept`, `guide`, `reference`, `legal`. Intended for LLM reasoning.                                                                                                                                     |
| `related`     | A list of paths to related pages designed to assist LLMs in navigating your site.                                                                                                                                                          |

Note that all of these attributes are optional.

### SEO-Specific Attributes

| Field             | Purpose                                                                                                                                                                                                                             |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seo.title`       | Used to set the `<title>` HTML tag, as the search result title, and as the heading in `llms.txt`/`llms-full.txt`. If absent, the portal falls back to deriving title from file path (e.g. `guides/quick-start.md` → "Quick Start"). |
| `seo.description` | The human/search-engine-facing summary: rendered as `<meta name="description">`, tuned for a SERP snippet (short, marketing tone). If absent, the portal will fall back to `llm_context` if present.                                |
| `seo.keywords`    | A YAML list or comma-separated string. Rendered as `<meta name="keywords">`. Used by search engines to boost full-text search relevance, and appears as a `Keywords:` line per entry in `llms-full.txt`.                            |
| `seo.noindex`     | When truthy, renders `<meta name="robots" content="noindex">` on the page, so that search engines skip it. Does not affect the page's own reachability, portal search, or `llms.txt`/`llms-full.txt` generation.                    |

Note that all of these attributes are optional.

:::info Copy To Markdown Button
When a user clicks the :icon:fa-regular fa-copy:grey: Copy markdown button in the top-right corner, all front matter is included in the copied text. This lets the context travel with the content when it's pasted into an LLM's chat window.
:::

### Frequently Asked Questions

:::faqs
::faq[Do I need to add front matter to every page?]{#faq_portal_frontmatter_required}
No — every attribute is optional, and pages with no front matter at all render just fine. The portal falls back to sensible defaults (like deriving a title from the file path), so add front matter only where it genuinely helps SEO or LLM reasoning.
::
::faq[What's the difference between `seo.description` and `llm_context`?]{#faq_portal_frontmatter_description_vs_llm_context}
`seo.description` is written for humans and search engines — short, snappy, SERP-friendly. `llm_context` is for machine readers and can afford to be more precise: scope, prerequisites, disambiguation from similar pages. Don't just restate one as a longer version of the other.
::
::faq[Does `seo.noindex` hide the page from users too?]{#faq_portal_frontmatter_noindex_scope}
No. `noindex` only tells search engines not to index the page — it has no effect on whether logged-in users, portal search, or `llms.txt`/`llms-full.txt` can reach it. Use [Access Control](/portal/reference/access) if you need to actually restrict visibility.
::
:::
