Skip to content

docs: update front matter docs #516

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hazel-nut wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: update front matter docs #516

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,7 @@ This is **not a managed monorepo** (no Lerna, pnpm workspaces, etc.). Each folde

**Content Structure:**
- `.mdx` and `.md` files for documentation pages
- YAML frontmatter for metadata (title, description, og/twitter tags)
- YAML frontmatter for metadata (title, description)
- `docs.json` defines navigation structure and Mintlify configuration

**Reusable Components:**
Expand Down
22 changes: 8 additions & 14 deletions CONTRIBUTION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,19 +20,13 @@ Mintlify’s articles files are a form of Markdown, so all your article files sh
| `configure-identity-provider.mdx` | `ConfigureIdentityProviders.mdx` |
| `customize-ul-templates.mdx` | `customize_ul_templates.mdx` |

### File metadata

| **Field name** | **Description** | **Example** |
| ------ | -------- | ------ |
| `'og:description'` | Meta description for articles. This short summary populates in search engines. * Descriptions should: Start with present tense verbs: Learn, Configure, Access, Create. * Be no more than two clear, concise sentences. * Not contain complicated terminology. | `Learn how to configure your login page to use passwordless authentication using the Auth0 Dashboard.` |
| `'og:image'` | Main image from the doc site. | N/A |
| `‘og:title’` | Main title of the article. This field is specific for search engines. Titles should be short with present-tense verbs (Get Started not Getting Started) and SEO keywords. | Configure Universal Login |
| `'og:url'` | Defines the docs domain: `https://auth0.com/docs` ||
| `'permalink'` | URL component of the article. For search engine optimization, URLs should be **short** and contain **necessary keywords**, such as the feature name and job-to-be-done. Permalinks don’t have to be grammatically correct or contain all words in the title of the article. | `oidc-adoption-access-tokens`|
| `'sidebarTitle'` | Title of the article as shown in the side navigation. **Note**: long titles will drop off in the side navigation. Be mindful when you title an article. | Manage Self-Service Single Sign-On |
| `'title'` | Main title of the page. ||
| `'twitter:description'` | Description for social media website, X. Is the same as meta description. | Learn how to configure your login page to use passwordless authentication using the Auth0 Dashboard. |
| `'twitter:title'` | Title for social media website, X. Is the same as standard title. | Native to Web SSO and Sessions |
### Front matter and custom metadata

See [Mintlify's documentation on page front matter](https://www.mintlify.com/docs/organize/pages#page-metadata). Of the default available front matter, most pages only need `title` and `default`.

We one use piece of custom front matter:

* `validatedOn` with a date in `yyyy-mm-dd` format to indicate when the content was last validated.

### Format text

Expand Down Expand Up @@ -344,4 +338,4 @@ Before publishing your document, please check your work. You should:
* Check for broken links.
* Check that markdown and HTML in tables are formatted properly.
* Check for outdated screenshots of the Auth0 Dashboard or product and third-party sites.
* Preview your document to ensure that the build will succeed once your changes are published.
* Preview your document to ensure that the build will succeed once your changes are published.
8 changes: 1 addition & 7 deletions main/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,13 +56,7 @@ All documentation files follow this structure:
---
title: "Page Title"
description: "SEO description for search engines"
'og:image': https://cdn2.auth0.com/docs/...
'og:title': "Social media title"
'og:url': https://auth0.com/docs/path
permalink: unique-path-slug
sidebarTitle: "Optional sidebar label"
'twitter:description': "Twitter card description"
'twitter:title': "Twitter card title"
---

import { Component } from '/snippets/component.jsx';
Expand All @@ -77,7 +71,7 @@ export const codeExample2 = `more code here`;

### Key Conventions

1. **Frontmatter**: All MDX files require complete YAML frontmatter with SEO metadata
1. **Frontmatter**: All MDX files require complete YAML frontmatter
2. **Code Examples**: Export code as constants at the top of the file (after imports, before content)
3. **Imports**: Custom components imported from `/snippets/` directory
4. **Permalinks**: Used for stable URLs and redirects
Expand Down