From fa1a442b75c7471c5840781f69df864cc7afd00b Mon Sep 17 00:00:00 2001 From: Hazel Virdo Date: Wed, 28 Jan 2026 12:09:06 -0500 Subject: [PATCH] docs: update front matter docs --- CLAUDE.md | 2 +- CONTRIBUTION.md | 22 ++++++++-------------- main/CLAUDE.md | 8 +------- 3 files changed, 10 insertions(+), 22 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 10c27f65c3..fc07104f1b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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:** diff --git a/CONTRIBUTION.md b/CONTRIBUTION.md index 1ee49b68f6..376e38b853 100644 --- a/CONTRIBUTION.md +++ b/CONTRIBUTION.md @@ -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 @@ -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. \ No newline at end of file +* Preview your document to ensure that the build will succeed once your changes are published. diff --git a/main/CLAUDE.md b/main/CLAUDE.md index 3bbb1060c9..6bd6fe26d0 100644 --- a/main/CLAUDE.md +++ b/main/CLAUDE.md @@ -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'; @@ -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