From ab85e7f056c650e09c4a93076bac4204b0ba063a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 22 Sep 2026 21:30:30 +0000 Subject: [PATCH 1/4] docs: document seo.paths folder-scoped meta tags --- optimize/seo.mdx | 28 ++++++++++++++++++++++++++++ organize/settings-seo.mdx | 30 ++++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) diff --git a/optimize/seo.mdx b/optimize/seo.mdx index 66671d2f81..cbea065692 100644 --- a/optimize/seo.mdx +++ b/optimize/seo.mdx @@ -147,6 +147,34 @@ To set default meta tags for all pages, add the `metatags` field to your `docs.j } ``` +### Folder-scoped meta tags + +To apply different meta tags to a subset of pages, such as versioned docs or a specific product area, add `seo.paths` to your `docs.json`. Each entry targets a folder path relative to the docs root and applies its tags to every page under that folder. + +```json +"seo": { + "metatags": { + "og:image": "https://example.com/og/default.png" + }, + "paths": [ + { + "path": "guides/v1", + "metatags": { + "robots": "noindex" + } + }, + { + "path": "guides/v2", + "metatags": { + "og:image": "https://example.com/og/v2.png" + } + } + ] +} +``` + +Folder tags override `seo.metatags` for the same key. When a page is under multiple entries, longer paths override shorter ones. Page frontmatter still overrides both. `canonical` is always sourced from `seo.metatags` and cannot be set per folder. See [`seo.paths`](/organize/settings-seo#seo) for the full schema. + ### Verify site ownership To verify your site with services like Google Search Console, Bing Webmaster Tools, or other search engines, add the verification meta tag to `seo.metatags` in your `docs.json`. Mintlify injects the tag into every page. diff --git a/organize/settings-seo.mdx b/organize/settings-seo.mdx index f523445992..e0edb42f6d 100644 --- a/organize/settings-seo.mdx +++ b/organize/settings-seo.mdx @@ -46,6 +46,36 @@ Search engine indexing and metadata settings. ``` + + Meta tags scoped to a folder. Use this to apply different tags to a subset of pages, such as versioned docs or a specific product area, without repeating them in page frontmatter. + + Each entry has: + + - `path`: Folder path relative to the docs root, for example `guides/v2`. Applies to every page under that folder. Each path can only be used once. Segments cannot contain whitespace, `\`, `?`, `#`, or be `.` or `..`, and the path must not start or end with a slash. + - `metatags`: Meta tags added to every page under `path`, as key-value pairs. + + Precedence, from lowest to highest: `seo.metatags`, then matching `seo.paths` entries (longer paths override shorter ones when a page is under multiple), then page frontmatter. + + `canonical` is always sourced from `seo.metatags` and cannot be set per folder, because it is a site-level base that Mintlify concatenates with each page's path. + + ```json + "paths": [ + { + "path": "guides/v1", + "metatags": { + "robots": "noindex" + } + }, + { + "path": "guides/v2", + "metatags": { + "og:image": "https://example.com/og/v2.png" + } + } + ] + ``` + + The organization used as the publisher entity in the [structured data](/optimize/seo#structured-data) emitted on every page. All fields are optional. If you omit this object, Mintlify derives the organization from your site name, docs logo, and site URL. From 5b10570329cd8fbd005d96268a37081a8af2a6ab Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 22 Sep 2026 21:33:32 +0000 Subject: [PATCH 2/4] docs: translate seo.paths content to es, fr, zh --- es/optimize/seo.mdx | 30 ++++++++++++++++++++++++++++++ es/organize/settings-seo.mdx | 30 ++++++++++++++++++++++++++++++ fr/optimize/seo.mdx | 30 ++++++++++++++++++++++++++++++ fr/organize/settings-seo.mdx | 30 ++++++++++++++++++++++++++++++ zh/optimize/seo.mdx | 30 ++++++++++++++++++++++++++++++ zh/organize/settings-seo.mdx | 30 ++++++++++++++++++++++++++++++ 6 files changed, 180 insertions(+) diff --git a/es/optimize/seo.mdx b/es/optimize/seo.mdx index ab41e3e0a2..902d5128ab 100644 --- a/es/optimize/seo.mdx +++ b/es/optimize/seo.mdx @@ -157,6 +157,36 @@ Para establecer metadatos predeterminados para todas las páginas, agrega el cam } ``` +
+ ### Meta tags con alcance a una carpeta +
+ +Para aplicar distintas meta tags a un subconjunto de páginas, como documentación versionada o un área específica de producto, agrega `seo.paths` a tu `docs.json`. Cada entrada apunta a una ruta de carpeta relativa a la raíz de la documentación y aplica sus etiquetas a todas las páginas dentro de esa carpeta. + +```json +"seo": { + "metatags": { + "og:image": "https://example.com/og/default.png" + }, + "paths": [ + { + "path": "guides/v1", + "metatags": { + "robots": "noindex" + } + }, + { + "path": "guides/v2", + "metatags": { + "og:image": "https://example.com/og/v2.png" + } + } + ] +} +``` + +Las etiquetas por carpeta prevalecen sobre `seo.metatags` para la misma clave. Cuando una página está en varias entradas, las rutas más largas prevalecen sobre las más cortas. El frontmatter de la página sigue prevaleciendo sobre ambas. `canonical` siempre proviene de `seo.metatags` y no puede definirse por carpeta. Consulta [`seo.paths`](/es/organize/settings-seo#seo) para ver el esquema completo. +
### Verificar la propiedad del sitio
diff --git a/es/organize/settings-seo.mdx b/es/organize/settings-seo.mdx index e07b87c9d2..9b0782bc84 100644 --- a/es/organize/settings-seo.mdx +++ b/es/organize/settings-seo.mdx @@ -46,6 +46,36 @@ Configuración de indexación y metadatos para motores de búsqueda. ``` + + Meta tags con alcance a una carpeta. Úsalo para aplicar distintas etiquetas a un subconjunto de páginas, como documentación versionada o un área específica de producto, sin tener que repetirlas en el frontmatter de cada página. + + Cada entrada tiene: + + - `path`: Ruta de carpeta relativa a la raíz de la documentación, por ejemplo `guides/v2`. Se aplica a todas las páginas dentro de esa carpeta. Cada `path` solo puede usarse una vez. Los segmentos no pueden contener espacios en blanco, `\`, `?`, `#`, ni ser `.` o `..`, y la ruta no debe comenzar ni terminar con una barra. + - `metatags`: Meta tags añadidas a cada página bajo `path`, como pares clave-valor. + + Precedencia, de menor a mayor: `seo.metatags`, luego las entradas de `seo.paths` que coincidan (las rutas más largas prevalecen sobre las más cortas cuando una página está en varias) y, por último, el frontmatter de la página. + + `canonical` siempre proviene de `seo.metatags` y no puede definirse por carpeta, porque es una base a nivel de sitio que Mintlify concatena con la ruta de cada página. + + ```json + "paths": [ + { + "path": "guides/v1", + "metatags": { + "robots": "noindex" + } + }, + { + "path": "guides/v2", + "metatags": { + "og:image": "https://example.com/og/v2.png" + } + } + ] + ``` + + Organización utilizada como entidad editora en los [datos estructurados](/es/optimize/seo#structured-data) que se emiten en cada página. Todos los campos son opcionales. Cuando se omiten, Mintlify deriva la organización a partir del nombre de tu sitio, el logo de la documentación y la URL del sitio. diff --git a/fr/optimize/seo.mdx b/fr/optimize/seo.mdx index 4411b744f2..ca2c0eb150 100644 --- a/fr/optimize/seo.mdx +++ b/fr/optimize/seo.mdx @@ -157,6 +157,36 @@ Pour définir des balises méta par défaut pour toutes les pages, ajoutez le ch } ``` +
+ ### Balises méta limitées à un dossier +
+ +Pour appliquer des balises méta différentes à un sous-ensemble de pages, comme une documentation versionnée ou un domaine produit spécifique, ajoutez `seo.paths` à votre `docs.json`. Chaque entrée cible un chemin de dossier relatif à la racine de la documentation et applique ses balises à toutes les pages sous ce dossier. + +```json +"seo": { + "metatags": { + "og:image": "https://example.com/og/default.png" + }, + "paths": [ + { + "path": "guides/v1", + "metatags": { + "robots": "noindex" + } + }, + { + "path": "guides/v2", + "metatags": { + "og:image": "https://example.com/og/v2.png" + } + } + ] +} +``` + +Les balises par dossier l'emportent sur `seo.metatags` pour la même clé. Lorsqu'une page est incluse dans plusieurs entrées, les chemins plus longs l'emportent sur les plus courts. Le frontmatter de la page l'emporte toujours sur les deux. `canonical` provient toujours de `seo.metatags` et ne peut pas être défini par dossier. Consultez [`seo.paths`](/fr/organize/settings-seo#seo) pour le schéma complet. +
### Vérifier la propriété du site
diff --git a/fr/organize/settings-seo.mdx b/fr/organize/settings-seo.mdx index 21cfc29a2a..c37f7176c4 100644 --- a/fr/organize/settings-seo.mdx +++ b/fr/organize/settings-seo.mdx @@ -46,6 +46,36 @@ Paramètres d'indexation et de métadonnées pour les moteurs de recherche. ``` + + Balises meta limitées à un dossier. Utilisez ce champ pour appliquer des balises différentes à un sous-ensemble de pages, comme une documentation versionnée ou un domaine produit spécifique, sans les répéter dans le frontmatter de chaque page. + + Chaque entrée contient : + + - `path` : Chemin de dossier relatif à la racine de la documentation, par exemple `guides/v2`. S'applique à toutes les pages sous ce dossier. Chaque `path` ne peut être utilisé qu'une seule fois. Les segments ne peuvent pas contenir d'espaces, `\`, `?`, `#`, ni être `.` ou `..`, et le chemin ne doit pas commencer ni se terminer par une barre oblique. + - `metatags` : Balises meta ajoutées à chaque page sous `path`, sous forme de paires clé-valeur. + + Priorité, du plus faible au plus élevé : `seo.metatags`, puis les entrées de `seo.paths` correspondantes (les chemins plus longs l'emportent sur les plus courts lorsqu'une page est incluse dans plusieurs), puis le frontmatter de la page. + + `canonical` provient toujours de `seo.metatags` et ne peut pas être défini par dossier, car il s'agit d'une base au niveau du site que Mintlify concatène avec le chemin de chaque page. + + ```json + "paths": [ + { + "path": "guides/v1", + "metatags": { + "robots": "noindex" + } + }, + { + "path": "guides/v2", + "metatags": { + "og:image": "https://example.com/og/v2.png" + } + } + ] + ``` + + Organisation utilisée comme entité éditrice dans les [données structurées](/fr/optimize/seo#structured-data) émises sur chaque page. Tous les champs sont facultatifs. Lorsqu'ils sont omis, Mintlify dérive l'organisation du nom de votre site, du logo de la documentation et de l'URL du site. diff --git a/zh/optimize/seo.mdx b/zh/optimize/seo.mdx index e436298e64..6c1c190c73 100644 --- a/zh/optimize/seo.mdx +++ b/zh/optimize/seo.mdx @@ -157,6 +157,36 @@ description: "Your page description" } ``` +
+ ### 作用于文件夹的元标签 +
+ +要为一部分页面（例如版本化文档或特定的产品区域）应用不同的元标签，请在 `docs.json` 中添加 `seo.paths`。每个条目指向相对于文档根目录的文件夹路径，并将其标签应用到该文件夹下的每个页面。 + +```json +"seo": { + "metatags": { + "og:image": "https://example.com/og/default.png" + }, + "paths": [ + { + "path": "guides/v1", + "metatags": { + "robots": "noindex" + } + }, + { + "path": "guides/v2", + "metatags": { + "og:image": "https://example.com/og/v2.png" + } + } + ] +} +``` + +对于相同的键，文件夹级标签会覆盖 `seo.metatags`。当页面位于多个条目下时，较长的路径会覆盖较短的路径。页面的 frontmatter 仍会覆盖上述两者。`canonical` 始终来源于 `seo.metatags`，无法按文件夹设置。完整的架构请参见 [`seo.paths`](/zh/organize/settings-seo#seo)。 +
### 验证站点所有权
diff --git a/zh/organize/settings-seo.mdx b/zh/organize/settings-seo.mdx index 55f1af69b3..20865ef85d 100644 --- a/zh/organize/settings-seo.mdx +++ b/zh/organize/settings-seo.mdx @@ -46,6 +46,36 @@ keywords: ["SEO", "搜索", "索引", "meta 标签", "描述", "时间戳", "最 ``` + + 作用范围限定为某个文件夹的 meta 标签。使用它可以为一部分页面（例如版本化文档或特定的产品区域）应用不同的标签，而无需在每个页面的 frontmatter 中重复设置。 + + 每个条目包含： + + - `path`：相对于文档根目录的文件夹路径，例如 `guides/v2`。将应用于该文件夹下的每个页面。每个 `path` 只能使用一次。段中不能包含空白字符、`\`、`?`、`#`，也不能为 `.` 或 `..`，且路径不能以斜杠开头或结尾。 + - `metatags`：以键值对形式提供的 meta 标签，将添加到 `path` 下的每个页面。 + + 优先级从低到高依次为：`seo.metatags`、匹配的 `seo.paths` 条目（当页面位于多个条目下时，较长的路径优先于较短的路径），最后是页面的 frontmatter。 + + `canonical` 始终来源于 `seo.metatags`，无法按文件夹设置，因为它是站点级的基础地址，Mintlify 会将它与每个页面的路径拼接。 + + ```json + "paths": [ + { + "path": "guides/v1", + "metatags": { + "robots": "noindex" + } + }, + { + "path": "guides/v2", + "metatags": { + "og:image": "https://example.com/og/v2.png" + } + } + ] + ``` + + 用作每个页面所发出[结构化数据](/zh/optimize/seo#structured-data)中发布者实体的组织。所有字段均为可选。省略时，Mintlify 会根据你的站点名称、文档 logo 和站点 URL 推导组织。 From dd91b46b56e4c16e4dc1a069c303c2c16bc5a8dd Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 22 Sep 2026 21:52:58 +0000 Subject: [PATCH 3/4] docs: note frontmatter overrides declared custom metatags --- es/optimize/seo.mdx | 2 ++ fr/optimize/seo.mdx | 2 ++ optimize/seo.mdx | 2 ++ zh/optimize/seo.mdx | 2 ++ 4 files changed, 8 insertions(+) diff --git a/es/optimize/seo.mdx b/es/optimize/seo.mdx index 902d5128ab..03accce727 100644 --- a/es/optimize/seo.mdx +++ b/es/optimize/seo.mdx @@ -240,6 +240,8 @@ canonical: "https://docs.example.com/latest/my-page" Para configurar metaetiquetas específicas de página, agrégalas al frontmatter de la página. +El frontmatter también puede sobrescribir cualquier metaetiqueta personalizada declarada en tu `docs.json` bajo [`seo.metatags`](/es/organize/settings-seo#seo) o en una entrada coincidente de [`seo.paths`](/es/organize/settings-seo#seo). Proporciona un valor de cadena no vacío con la misma clave para reemplazar el valor global o el limitado a una carpeta en esa página. El frontmatter no puede introducir metaetiquetas que la configuración no declare, y los valores que no sean cadenas se ignoran. + Las metaetiquetas específicas de página incluyen: * `title` - Título de la página diff --git a/fr/optimize/seo.mdx b/fr/optimize/seo.mdx index ca2c0eb150..e1a1d938a0 100644 --- a/fr/optimize/seo.mdx +++ b/fr/optimize/seo.mdx @@ -240,6 +240,8 @@ canonical: "https://docs.example.com/latest/my-page" Pour définir des balises méta spécifiques à une page, ajoutez-les dans le frontmatter de la page. +Le frontmatter peut aussi remplacer toute balise méta personnalisée déclarée dans votre `docs.json` sous [`seo.metatags`](/fr/organize/settings-seo#seo) ou dans une entrée correspondante de [`seo.paths`](/fr/organize/settings-seo#seo). Fournissez une valeur de type chaîne non vide avec la même clé pour remplacer la valeur globale ou limitée à un dossier sur cette page. Le frontmatter ne peut pas introduire de balises méta que la configuration ne déclare pas, et les valeurs qui ne sont pas des chaînes sont ignorées. + Les balises méta spécifiques à une page incluent : * `title` - Titre de la page diff --git a/optimize/seo.mdx b/optimize/seo.mdx index cbea065692..57022b535a 100644 --- a/optimize/seo.mdx +++ b/optimize/seo.mdx @@ -222,6 +222,8 @@ canonical: "https://docs.example.com/latest/my-page" To set page-specific meta tags, add them to a page's frontmatter. +Frontmatter can also override any custom meta tag declared in your `docs.json` under [`seo.metatags`](/organize/settings-seo#seo) or a matching [`seo.paths`](/organize/settings-seo#seo) entry. Provide a non-empty string value with the same key to replace the site-wide or folder-scoped value on that page. Frontmatter cannot introduce meta tags that the config does not declare, and non-string values are ignored. + Page-specific meta tags include: - `title` - Page title diff --git a/zh/optimize/seo.mdx b/zh/optimize/seo.mdx index 6c1c190c73..b4162f8661 100644 --- a/zh/optimize/seo.mdx +++ b/zh/optimize/seo.mdx @@ -240,6 +240,8 @@ canonical: "https://docs.example.com/latest/my-page" 要为特定页面设置元标签，可将它们添加到页面的 frontmatter 中。 +frontmatter 也可以覆盖 `docs.json` 中在 [`seo.metatags`](/zh/organize/settings-seo#seo) 或匹配的 [`seo.paths`](/zh/organize/settings-seo#seo) 条目下声明的任何自定义元标签。使用相同的键提供一个非空字符串值，即可在该页面上替换站点级或文件夹级的值。frontmatter 不能引入配置中未声明的元标签，非字符串值将被忽略。 + 页面级元标签包括： * `title` - 页面标题 From 4a6db64258886c967501c1cbeb4f057ecccc1ffb Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 24 Sep 2026 10:40:52 -0700 Subject: [PATCH 4/4] docs: tighten seo.paths docs and fix canonical and anchor accuracy - Replace "canonical is always sourced from seo.metatags", which contradicted per-page canonical, with the actual behavior: a canonical key in seo.paths entries is ignored. - Note that paths match page URLs, so language folders need their own entries. - Note that seo.paths metatag values must be non-empty strings. - Simplify path rules; the validation error lists every constraint. - Dedupe precedence rules in the SEO guide and link to the reference. - Move the frontmatter override paragraph after the page-specific tag list and example. - Link to #param-seo-metatags and #param-seo-paths instead of #seo. - Mirror all changes in es, fr, and zh. Co-Authored-By: Claude Opus 5.5 (1M context) --- es/optimize/seo.mdx | 6 +++--- es/organize/settings-seo.mdx | 8 +++++--- fr/optimize/seo.mdx | 6 +++--- fr/organize/settings-seo.mdx | 8 +++++--- optimize/seo.mdx | 6 +++--- organize/settings-seo.mdx | 8 +++++--- zh/optimize/seo.mdx | 6 +++--- zh/organize/settings-seo.mdx | 8 +++++--- 8 files changed, 32 insertions(+), 24 deletions(-) diff --git a/es/optimize/seo.mdx b/es/optimize/seo.mdx index 03accce727..84690f481a 100644 --- a/es/optimize/seo.mdx +++ b/es/optimize/seo.mdx @@ -185,7 +185,7 @@ Para aplicar distintas meta tags a un subconjunto de páginas, como documentaci } ``` -Las etiquetas por carpeta prevalecen sobre `seo.metatags` para la misma clave. Cuando una página está en varias entradas, las rutas más largas prevalecen sobre las más cortas. El frontmatter de la página sigue prevaleciendo sobre ambas. `canonical` siempre proviene de `seo.metatags` y no puede definirse por carpeta. Consulta [`seo.paths`](/es/organize/settings-seo#seo) para ver el esquema completo. +Las etiquetas por carpeta prevalecen sobre `seo.metatags` para la misma clave, las rutas más largas prevalecen sobre las más cortas y el frontmatter de la página prevalece sobre ambas. Consulta [`seo.paths`](/es/organize/settings-seo#param-seo-paths) para ver las reglas de las rutas y sus excepciones.
### Verificar la propiedad del sitio @@ -240,8 +240,6 @@ canonical: "https://docs.example.com/latest/my-page" Para configurar metaetiquetas específicas de página, agrégalas al frontmatter de la página. -El frontmatter también puede sobrescribir cualquier metaetiqueta personalizada declarada en tu `docs.json` bajo [`seo.metatags`](/es/organize/settings-seo#seo) o en una entrada coincidente de [`seo.paths`](/es/organize/settings-seo#seo). Proporciona un valor de cadena no vacío con la misma clave para reemplazar el valor global o el limitado a una carpeta en esa página. El frontmatter no puede introducir metaetiquetas que la configuración no declare, y los valores que no sean cadenas se ignoran. - Las metaetiquetas específicas de página incluyen: * `title` - Título de la página @@ -287,6 +285,8 @@ keywords: ["keyword1", "keyword2"] El campo `keywords` debe estar en formato de lista YAML. Por ejemplo, `keywords: ["keyword1", "keyword2", "keyword3"]`. +El frontmatter también puede sobrescribir cualquier metaetiqueta personalizada declarada en tu `docs.json` bajo [`seo.metatags`](/es/organize/settings-seo#param-seo-metatags) o en una entrada coincidente de [`seo.paths`](/es/organize/settings-seo#param-seo-paths). Asigna a la misma clave un valor de cadena no vacío para reemplazar el valor global o el de la carpeta en esa página. El frontmatter no puede añadir metaetiquetas personalizadas que tu configuración no declare, y Mintlify ignora los valores que no sean cadenas. +
## Referencia de etiquetas meta comunes
diff --git a/es/organize/settings-seo.mdx b/es/organize/settings-seo.mdx index 9b0782bc84..647d14d009 100644 --- a/es/organize/settings-seo.mdx +++ b/es/organize/settings-seo.mdx @@ -51,12 +51,14 @@ Configuración de indexación y metadatos para motores de búsqueda. Cada entrada tiene: - - `path`: Ruta de carpeta relativa a la raíz de la documentación, por ejemplo `guides/v2`. Se aplica a todas las páginas dentro de esa carpeta. Cada `path` solo puede usarse una vez. Los segmentos no pueden contener espacios en blanco, `\`, `?`, `#`, ni ser `.` o `..`, y la ruta no debe comenzar ni terminar con una barra. - - `metatags`: Meta tags añadidas a cada página bajo `path`, como pares clave-valor. + - `path`: Ruta de carpeta relativa a la raíz de la documentación, como `guides/v2`, sin barra inicial ni final. Se aplica a todas las páginas dentro de esa carpeta. Cada ruta solo puede aparecer una vez. + - `metatags`: Meta tags añadidas a cada página bajo `path`, como pares clave-valor. Los valores deben ser cadenas no vacías. Precedencia, de menor a mayor: `seo.metatags`, luego las entradas de `seo.paths` que coincidan (las rutas más largas prevalecen sobre las más cortas cuando una página está en varias) y, por último, el frontmatter de la página. - `canonical` siempre proviene de `seo.metatags` y no puede definirse por carpeta, porque es una base a nivel de sitio que Mintlify concatena con la ruta de cada página. + Las rutas se comparan con las URL de las páginas, por lo que las páginas traducidas en una carpeta de idioma necesitan sus propias entradas. Por ejemplo, `guides/v1` no se aplica a `es/guides/v1`. + + Mintlify ignora la clave `canonical` en las entradas de `seo.paths`. Define una URL canónica para todo el sitio en `seo.metatags` o una URL canónica por página en el frontmatter. ```json "paths": [ diff --git a/fr/optimize/seo.mdx b/fr/optimize/seo.mdx index e1a1d938a0..225ab30950 100644 --- a/fr/optimize/seo.mdx +++ b/fr/optimize/seo.mdx @@ -185,7 +185,7 @@ Pour appliquer des balises méta différentes à un sous-ensemble de pages, comm } ``` -Les balises par dossier l'emportent sur `seo.metatags` pour la même clé. Lorsqu'une page est incluse dans plusieurs entrées, les chemins plus longs l'emportent sur les plus courts. Le frontmatter de la page l'emporte toujours sur les deux. `canonical` provient toujours de `seo.metatags` et ne peut pas être défini par dossier. Consultez [`seo.paths`](/fr/organize/settings-seo#seo) pour le schéma complet. +Les balises par dossier l'emportent sur `seo.metatags` pour la même clé, les chemins plus longs l'emportent sur les plus courts, et le frontmatter de la page l'emporte sur les deux. Consultez [`seo.paths`](/fr/organize/settings-seo#param-seo-paths) pour les règles de chemin et leurs exceptions.
### Vérifier la propriété du site @@ -240,8 +240,6 @@ canonical: "https://docs.example.com/latest/my-page" Pour définir des balises méta spécifiques à une page, ajoutez-les dans le frontmatter de la page. -Le frontmatter peut aussi remplacer toute balise méta personnalisée déclarée dans votre `docs.json` sous [`seo.metatags`](/fr/organize/settings-seo#seo) ou dans une entrée correspondante de [`seo.paths`](/fr/organize/settings-seo#seo). Fournissez une valeur de type chaîne non vide avec la même clé pour remplacer la valeur globale ou limitée à un dossier sur cette page. Le frontmatter ne peut pas introduire de balises méta que la configuration ne déclare pas, et les valeurs qui ne sont pas des chaînes sont ignorées. - Les balises méta spécifiques à une page incluent : * `title` - Titre de la page @@ -287,6 +285,8 @@ keywords: ["mot-clé1", "mot-clé2"] Le champ `keywords` doit être formaté comme un tableau YAML. Par exemple, `keywords: ["keyword1", "keyword2", "keyword3"]`. +Le frontmatter peut aussi remplacer toute balise méta personnalisée déclarée dans votre `docs.json` sous [`seo.metatags`](/fr/organize/settings-seo#param-seo-metatags) ou dans une entrée correspondante de [`seo.paths`](/fr/organize/settings-seo#param-seo-paths). Attribuez à la même clé une valeur de type chaîne non vide pour remplacer la valeur globale ou celle du dossier sur cette page. Le frontmatter ne peut pas ajouter de balises méta personnalisées que votre configuration ne déclare pas, et Mintlify ignore les valeurs qui ne sont pas des chaînes. +
## Référence des balises meta courantes
diff --git a/fr/organize/settings-seo.mdx b/fr/organize/settings-seo.mdx index c37f7176c4..bb6f49100b 100644 --- a/fr/organize/settings-seo.mdx +++ b/fr/organize/settings-seo.mdx @@ -51,12 +51,14 @@ Paramètres d'indexation et de métadonnées pour les moteurs de recherche. Chaque entrée contient : - - `path` : Chemin de dossier relatif à la racine de la documentation, par exemple `guides/v2`. S'applique à toutes les pages sous ce dossier. Chaque `path` ne peut être utilisé qu'une seule fois. Les segments ne peuvent pas contenir d'espaces, `\`, `?`, `#`, ni être `.` ou `..`, et le chemin ne doit pas commencer ni se terminer par une barre oblique. - - `metatags` : Balises meta ajoutées à chaque page sous `path`, sous forme de paires clé-valeur. + - `path` : Chemin de dossier relatif à la racine de la documentation, comme `guides/v2`, sans barre oblique au début ni à la fin. S'applique à toutes les pages sous ce dossier. Chaque chemin ne peut apparaître qu'une seule fois. + - `metatags` : Balises meta ajoutées à chaque page sous `path`, sous forme de paires clé-valeur. Les valeurs doivent être des chaînes non vides. Priorité, du plus faible au plus élevé : `seo.metatags`, puis les entrées de `seo.paths` correspondantes (les chemins plus longs l'emportent sur les plus courts lorsqu'une page est incluse dans plusieurs), puis le frontmatter de la page. - `canonical` provient toujours de `seo.metatags` et ne peut pas être défini par dossier, car il s'agit d'une base au niveau du site que Mintlify concatène avec le chemin de chaque page. + Les chemins sont comparés aux URL des pages : les pages traduites dans un dossier de langue ont donc besoin de leurs propres entrées. Par exemple, `guides/v1` ne s'applique pas à `fr/guides/v1`. + + Mintlify ignore la clé `canonical` dans les entrées de `seo.paths`. Définissez une URL canonique pour tout le site dans `seo.metatags` ou une URL canonique par page dans le frontmatter. ```json "paths": [ diff --git a/optimize/seo.mdx b/optimize/seo.mdx index 57022b535a..4d96b8ea1b 100644 --- a/optimize/seo.mdx +++ b/optimize/seo.mdx @@ -173,7 +173,7 @@ To apply different meta tags to a subset of pages, such as versioned docs or a s } ``` -Folder tags override `seo.metatags` for the same key. When a page is under multiple entries, longer paths override shorter ones. Page frontmatter still overrides both. `canonical` is always sourced from `seo.metatags` and cannot be set per folder. See [`seo.paths`](/organize/settings-seo#seo) for the full schema. +Folder tags override `seo.metatags` for the same key, longer paths override shorter ones, and page frontmatter overrides both. See [`seo.paths`](/organize/settings-seo#param-seo-paths) for path rules and exceptions. ### Verify site ownership @@ -222,8 +222,6 @@ canonical: "https://docs.example.com/latest/my-page" To set page-specific meta tags, add them to a page's frontmatter. -Frontmatter can also override any custom meta tag declared in your `docs.json` under [`seo.metatags`](/organize/settings-seo#seo) or a matching [`seo.paths`](/organize/settings-seo#seo) entry. Provide a non-empty string value with the same key to replace the site-wide or folder-scoped value on that page. Frontmatter cannot introduce meta tags that the config does not declare, and non-string values are ignored. - Page-specific meta tags include: - `title` - Page title @@ -269,6 +267,8 @@ keywords: ["keyword1", "keyword2"] You must format the `keywords` field as a YAML array. For example, `keywords: ["keyword1", "keyword2", "keyword3"]`. +Frontmatter can also override any custom meta tag declared in your `docs.json` under [`seo.metatags`](/organize/settings-seo#param-seo-metatags) or a matching [`seo.paths`](/organize/settings-seo#param-seo-paths) entry. Set the same key to a non-empty string to replace the site-wide or folder value on that page. Frontmatter can't add custom meta tags that your config doesn't declare, and Mintlify ignores non-string values. + ## Common meta tags reference Below is a comprehensive list of meta tags you can add to your `docs.json`. These meta tags help improve your site's SEO, social sharing, and browser compatibility. diff --git a/organize/settings-seo.mdx b/organize/settings-seo.mdx index e0edb42f6d..4d37d80bf1 100644 --- a/organize/settings-seo.mdx +++ b/organize/settings-seo.mdx @@ -51,12 +51,14 @@ Search engine indexing and metadata settings. Each entry has: - - `path`: Folder path relative to the docs root, for example `guides/v2`. Applies to every page under that folder. Each path can only be used once. Segments cannot contain whitespace, `\`, `?`, `#`, or be `.` or `..`, and the path must not start or end with a slash. - - `metatags`: Meta tags added to every page under `path`, as key-value pairs. + - `path`: Folder path relative to the docs root, like `guides/v2`, with no leading or trailing slash. Applies to every page under that folder. Each path can appear only once. + - `metatags`: Meta tags added to every page under `path`, as key-value pairs. Values must be non-empty strings. Precedence, from lowest to highest: `seo.metatags`, then matching `seo.paths` entries (longer paths override shorter ones when a page is under multiple), then page frontmatter. - `canonical` is always sourced from `seo.metatags` and cannot be set per folder, because it is a site-level base that Mintlify concatenates with each page's path. + Paths match page URLs, so translated pages in a language folder need their own entries. For example, `guides/v1` doesn't apply to `es/guides/v1`. + + Mintlify ignores a `canonical` key in `seo.paths` entries. Set a site-wide canonical in `seo.metatags` or a per-page canonical in frontmatter. ```json "paths": [ diff --git a/zh/optimize/seo.mdx b/zh/optimize/seo.mdx index b4162f8661..48a2297bcb 100644 --- a/zh/optimize/seo.mdx +++ b/zh/optimize/seo.mdx @@ -185,7 +185,7 @@ description: "Your page description" } ``` -对于相同的键，文件夹级标签会覆盖 `seo.metatags`。当页面位于多个条目下时，较长的路径会覆盖较短的路径。页面的 frontmatter 仍会覆盖上述两者。`canonical` 始终来源于 `seo.metatags`，无法按文件夹设置。完整的架构请参见 [`seo.paths`](/zh/organize/settings-seo#seo)。 +对于相同的键，文件夹级标签会覆盖 `seo.metatags`，较长的路径会覆盖较短的路径，页面的 frontmatter 会覆盖上述两者。路径规则和例外情况请参见 [`seo.paths`](/zh/organize/settings-seo#param-seo-paths)。
### 验证站点所有权 @@ -240,8 +240,6 @@ canonical: "https://docs.example.com/latest/my-page" 要为特定页面设置元标签，可将它们添加到页面的 frontmatter 中。 -frontmatter 也可以覆盖 `docs.json` 中在 [`seo.metatags`](/zh/organize/settings-seo#seo) 或匹配的 [`seo.paths`](/zh/organize/settings-seo#seo) 条目下声明的任何自定义元标签。使用相同的键提供一个非空字符串值，即可在该页面上替换站点级或文件夹级的值。frontmatter 不能引入配置中未声明的元标签，非字符串值将被忽略。 - 页面级元标签包括： * `title` - 页面标题 @@ -287,6 +285,8 @@ keywords: ["关键词1", "关键词2"] `keywords` 字段必须格式化为 YAML 数组。例如：`keywords: ["keyword1", "keyword2", "keyword3"]`。 +frontmatter 也可以覆盖 `docs.json` 中在 [`seo.metatags`](/zh/organize/settings-seo#param-seo-metatags) 或匹配的 [`seo.paths`](/zh/organize/settings-seo#param-seo-paths) 条目下声明的任何自定义元标签。为相同的键设置一个非空字符串值，即可在该页面上替换站点级或文件夹级的值。frontmatter 不能添加配置中未声明的自定义元标签，Mintlify 会忽略非字符串值。 +
## 常用 meta 标签参考
diff --git a/zh/organize/settings-seo.mdx b/zh/organize/settings-seo.mdx index 20865ef85d..8db43f635e 100644 --- a/zh/organize/settings-seo.mdx +++ b/zh/organize/settings-seo.mdx @@ -51,12 +51,14 @@ keywords: ["SEO", "搜索", "索引", "meta 标签", "描述", "时间戳", "最 每个条目包含： - - `path`：相对于文档根目录的文件夹路径，例如 `guides/v2`。将应用于该文件夹下的每个页面。每个 `path` 只能使用一次。段中不能包含空白字符、`\`、`?`、`#`，也不能为 `.` 或 `..`，且路径不能以斜杠开头或结尾。 - - `metatags`：以键值对形式提供的 meta 标签，将添加到 `path` 下的每个页面。 + - `path`：相对于文档根目录的文件夹路径，例如 `guides/v2`，开头和结尾都不能有斜杠。将应用于该文件夹下的每个页面。每个路径只能出现一次。 + - `metatags`：以键值对形式提供的 meta 标签，将添加到 `path` 下的每个页面。值必须是非空字符串。 优先级从低到高依次为：`seo.metatags`、匹配的 `seo.paths` 条目（当页面位于多个条目下时，较长的路径优先于较短的路径），最后是页面的 frontmatter。 - `canonical` 始终来源于 `seo.metatags`，无法按文件夹设置，因为它是站点级的基础地址，Mintlify 会将它与每个页面的路径拼接。 + 路径与页面 URL 进行匹配，因此语言文件夹中的翻译页面需要单独的条目。例如，`guides/v1` 不会应用于 `zh/guides/v1`。 + + Mintlify 会忽略 `seo.paths` 条目中的 `canonical` 键。请在 `seo.metatags` 中设置站点级规范 URL，或在 frontmatter 中设置单个页面的规范 URL。 ```json "paths": [