Skip to content

Commit b575065

Browse files
SarahSoutoulalexisintech
SarahSoutoul
and
alexisintech
authored
Add documentation for metadata (#2711)
Co-authored-by: Alexis Aguilar <[email protected]>
1 parent 966a416 commit b575065

File tree

1 file changed

+155
-0
lines changed

1 file changed

+155
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,161 @@ description: Some brief, but effective description of the page's content.
326326

327327
These fields should be present on every documentation page.
328328

329+
#### Metadata
330+
331+
The `metadata` frontmatter field can be used to define additional information about a documentation page, such as SEO metadata, social sharing tags, or indexing information. It allows you to control how the page appears in browsers, search engines, and social media previews. It has the following subfields:
332+
333+
| Name | Type | Default | Description |
334+
| ------------- | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
335+
| `title` | `string` | - | Overrides the browser title and `<title>` meta tag. |
336+
| `description` | `string` | - | Overrides the meta description shown in search results and link previews. |
337+
| `authors` | `Array<{ name: string }>` | `[]` | Lists the authors of the page for structured data or article metadata. |
338+
| `alternates` | `object` | `{}` | Defines canonical and alternate URLs for the page. See its properties below. |
339+
| `openGraph` | `object` | `{}` | Configures [Open Graph](https://ogp.me/) data for social previews (Facebook, LinkedIn, etc). See its properties below. |
340+
| `twitter` | `object` | `{}` | Configures [X Cards](https://developer.x.com/en/docs/x-for-websites/cards/overview/abouts-cards) data for previews on X (Twitter). See its properties below. |
341+
| `robots` | `object` | `{}` | Controls how crawlers index and follow the page. See its properties below. |
342+
343+
##### Examples
344+
345+
<details>
346+
<summary>Set a custom browser title</summary>
347+
348+
```diff
349+
---
350+
title: Example
351+
+ metadata:
352+
+ title: Example
353+
---
354+
```
355+
356+
</details>
357+
358+
<details>
359+
<summary>Set SEO title and description</summary>
360+
361+
```diff
362+
---
363+
title: Example
364+
+ metadata:
365+
+ title: Example
366+
+ description: Example
367+
---
368+
```
369+
370+
</details>
371+
372+
</details>
373+
374+
<details>
375+
<summary>Add page authors</summary>
376+
377+
```diff
378+
---
379+
title: Example
380+
+ metadata:
381+
+ authors:
382+
+ - name: Jane Doe
383+
---
384+
```
385+
386+
</details>
387+
388+
<details>
389+
<summary>Define canonical or alternate URLs for your documentation page</summary>
390+
<br />
391+
<p><strong>This is set via the <code>alternates</code> field. It has the following subfields:</strong></p>
392+
393+
| Name | Type | Default | Description |
394+
| ---------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
395+
| `canonical` | `string` | - | The canonical URL to avoid duplicate content across versions or domains. |
396+
397+
```diff
398+
---
399+
title: Example
400+
+ metadata:
401+
+ alternates:
402+
+ canonical: https://docs.example.com/
403+
---
404+
```
405+
406+
</details>
407+
408+
</details>
409+
410+
<details>
411+
<summary>Configure Open Graph metadata for social media previews</summary>
412+
<br />
413+
<p><strong>This is set via the <code>openGraph</code> field. It has the following subfields:</strong></p>
414+
415+
| Name | Type | Default | Description |
416+
| --------------- | --------------- | ------- | ----------------------------------------- |
417+
| `title` | `string` | - | Title displayed in social previews. |
418+
| `description` | `string` | - | Description displayed in social previews. |
419+
| `images` | `Array<string>` | `[]` | One or more image URLs for preview cards. |
420+
| `publishedTime` | `string` | - | Publication timestamp. |
421+
| `authors` | `Array<string>` | `[]` | Author names associated with the page. |
422+
423+
```diff
424+
---
425+
title: Example
426+
+ metadata:
427+
+ openGraph:
428+
+ title: Clerk organizations - invite users
429+
+ description: Guide to sending and managing invitations within Clerk.
430+
+ images:
431+
+ - https://example.com/social-preview.png
432+
---
433+
```
434+
435+
</details>
436+
437+
<details>
438+
<summary>Define X Cards metadata for the page</summary>
439+
<br />
440+
<p><strong>This is set via the <code>twitter</code> field. It has the following subfields:</strong></p>
441+
442+
| Name | Type | Default | Description |
443+
| ------------- | --------------- | ------- | -------------------------------------------- |
444+
| `title` | `string` | - | Title displayed in the Twitter card. |
445+
| `description` | `string` | - | Description displayed in the Twitter card. |
446+
| `images` | `Array<string>` | `[]` | Image URLs used in the Twitter card preview. |
447+
448+
```diff
449+
---
450+
title: Example
451+
+ metadata:
452+
+ twitter:
453+
+ title: Clerk organizations - invite users
454+
+ description: Guide to sending and managing invitations within Clerk.
455+
+ images:
456+
+ - https://example.com/social-preview.png
457+
---
458+
```
459+
460+
</details>
461+
462+
<details>
463+
<summary>Control search engine indexing and crawler behavior.</summary>
464+
<br />
465+
<p><strong>This is set via the <code>robots</code> field. It has the following subfields:</strong></p>
466+
467+
| Name | Type | Default | Description |
468+
| -------- | --------- | ------- | ---------------------------------------------------- |
469+
| `index` | `boolean` | `true` | Whether the page should appear in search results. |
470+
| `follow` | `boolean` | `true` | Whether crawlers should follow links from this page. |
471+
472+
```diff
473+
---
474+
title: Example
475+
+ metadata:
476+
+ robots:
477+
+ index: false
478+
+ follow: true
479+
---
480+
```
481+
482+
</details>
483+
329484
#### Search
330485

331486
The `search` frontmatter field can be used to control how a page is indexed by [Algolia Crawler](https://www.algolia.com/doc/tools/crawler/getting-started/overview/). It has the following subfields:

0 commit comments

Comments
 (0)