Create pages with frontmatter

Add a Markdown file to your docs folder to publish a page. The file path determines its URL; optional YAML frontmatter sets its title and other page-level settings.

Create a page fileCopy Anchor Link

Margin reads .md and .mdx files from the folder selected by DOCS_DIR. A site needs only one content file: docs.json, meta.json, and frontmatter are optional. Use .md for Markdown content or .mdx when the page includes components.

Create guides/first-request.mdx inside your docs folder with this content:

---
title: Make your first request
description: Send a request and inspect the response.
---

Run the request from your terminal, then inspect the response body.

After publishing the change, open /guides/first-request. The page heading should read “Make your first request,” with the description beneath it. If your site has an explicit navigation configuration, the new file is still URL-reachable even before you add it to navigation.

To check the published route from a terminal, set SITE_ORIGIN to your docs origin and request the page. A published page returns HTTP 200:

curl --silent --output /dev/null --write-out '%{http_code}\n' \
  "${SITE_ORIGIN}/guides/first-request"

Set the title and URLCopy Anchor Link

The page title uses the first available value: frontmatter title, the first Markdown H1 (# Heading), then a title derived from the filename. Filename titles split hyphens and underscores into spaces and capitalize words; recognized acronyms such as API and SDK remain uppercase. A title is not required to build a page.

An index.md or index.mdx without a title or H1 uses its parent directory’s name as the title. A root index without either uses “Overview.”

URLs preserve the file’s directory structure, remove the .md or .mdx extension, and remove a trailing index segment. Changing a title does not change the URL. Rename or move the file to change its path; frontmatter has no supported slug override.

These examples use paths relative to the docs folder:

In filesystem-derived navigation, parenthesized folders are transparent: api/(rest)/users.mdx becomes /api/users. An explicit reference to that authored path in docs.json navigation or a meta.json page list preserves the parenthesized segment instead. Leading-underscore folders are unpublished drafts unless explicitly referenced. Version and language roots follow their configured routing prefixes. Do not create two files that resolve to the same URL.

Configure frontmatterCopy Anchor Link

Place YAML frontmatter at the start of the file, between the opening and closing --- delimiters. All fields are optional. Use YAML booleans such as hidden: true, not quoted strings such as hidden: "true".

The fields below control page metadata and behavior. Omitted values use the defaults shown.

Unknown frontmatter keys are retained, but retention does not give them built-in behavior. Invalid known fields are dropped with a field_invalid warning and use their derived defaults. An unresolved openapi reference produces an openapi_ref_unresolved warning and leaves the page without its API console.

Hide a page from navigationCopy Anchor Link

Set hidden: true when a published page should not appear in the sidebar. This example creates a URL-reachable preview page without a navigation entry:

---
title: Preview the migration
hidden: true
---

Review the migration instructions before updating your client.

Save it as migration-preview.mdx, publish the change, and open /migration-preview to confirm it still loads. Check the sidebar to confirm it is absent. The page remains hidden even if a navigation configuration explicitly lists it.

Under the default indexing policy, hidden pages are excluded from search and agent indexes unless searchable: true opts them back in. A site-wide indexing policy can also include hidden pages. Neither hiding nor excluding a page from indexes restricts access to its URL. Do not publish confidential content in a public docs folder.

To order pages or group them in the sidebar, configure navigation.