Skip to content

Commit 93559f6

Browse files
devalogdevalog
authored
Restructure info on SEO metadata (Docs) (#577)
1 parent a57559d commit 93559f6

File tree

6 files changed

+233
-199
lines changed

6 files changed

+233
-199
lines changed

‎fern/products/docs/docs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -170,6 +170,8 @@ navigation:
170170
slug: seo
171171
collapsed: true
172172
contents:
173+
- page: Setting SEO metadata
174+
path: ./pages/seo/metadata.mdx
173175
- page: Configuring slugs
174176
path: ./pages/seo/configuring-slugs.mdx
175177
- page: Redirects

‎fern/products/docs/pages/customization/frontmatter.mdx‎

Lines changed: 3 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -245,120 +245,8 @@ Currently, relative paths are _not_ supported for this field.
245245

246246
## SEO metadata
247247

248-
<Note title="SEO Best Practices">
249-
Looking to set metadata across the entire site? [Use the metadata field in the `docs.yml` file](/learn/docs/configuration/what-is-docs-yml#metadata-configuration).
250-
251-
When configuring SEO metadata, ensure your titles and descriptions are unique, descriptive, and relevant to the page content. Keep descriptions between 150-160 characters for optimal display in search results.
248+
<Note title="Looking to set metadata across the entire site?">
249+
[Use the metadata field in the `docs.yml` file](/learn/docs/configuration/what-is-docs-yml#seo-metadata-configuration).
252250
</Note>
253251

254-
<CodeBlock title="Example SEO metadata">
255-
```mdx
256-
---
257-
title: PlantStore API Quick Start
258-
headline: "Get Started with PlantStore API | Developer Documentation"
259-
keywords: plants, garden, nursery
260-
canonical-url: https://docs.plantstore.dev/welcome
261-
og:site_name: PlantStore Developer Documentation
262-
og:title: "PlantStore API Quick Start Guide"
263-
og:description: "Learn how to integrate with PlantStore's API to manage plant inventory, process orders, and track shipments. Complete with code examples."
264-
og:image: https://plantstore.dev/images/api-docs-banner.png
265-
og:image:width: 1200
266-
og:image:height: 630
267-
twitter:card: summary_large_image
268-
twitter:site: "@PlantStoreAPI"
269-
noindex: false
270-
nofollow: false
271-
---
272-
```
273-
</CodeBlock>
274-
275-
### Document Properties
276-
<ParamField path="headline" type="string" required={false}>
277-
When set, the `<title />` tag in the document head will use this value rather than the `title` property. This property changes the title that search engines see when crawling this page, and can be used to address Duplicate Title issues in your SEO report.
278-
</ParamField>
279-
280-
<ParamField path="canonical-url" type="string" required={false}>
281-
Overrides the canonical URL for this page. Must be a full URL including the protocol (i.e. `https://buildwithfern.com/learn/docs/content/frontmatter`)
282-
</ParamField>
283-
284-
<ParamField path="keywords" type="string" required={false}>
285-
Comma-separated string of keywords relevant to the page content (i.e. `plants, garden, nursery`). These keywords help search engines understand the page topic and contributes to search rankings. Use specific, relevant terms that users might search for when looking for the page's content.
286-
287-
This field accepts only comma-separated strings, not bracketed arrays.
288-
289-
</ParamField>
290-
291-
### OpenGraph Properties
292-
<ParamField path="og:site_name" type="string" required={false}>
293-
The name of your website as it should appear when your content is shared.
294-
</ParamField>
295-
296-
<ParamField path="og:title" type="string" required={false}>
297-
The title of your page as it should appear when your content is shared.
298-
</ParamField>
299-
300-
<ParamField path="og:description" type="string" required={false}>
301-
The description of your page as it should appear when your content is shared.
302-
</ParamField>
303-
304-
<ParamField path="og:url" type="string" required={false}>
305-
The URL of your page.
306-
</ParamField>
307-
308-
<ParamField path="og:image" type="string" required={false}>
309-
The URL or identifier of the image that will be displayed when your content is shared.
310-
</ParamField>
311-
312-
<ParamField path="og:image:width" type="number" required={false}>
313-
The width of the image in pixels.
314-
</ParamField>
315-
316-
<ParamField path="og:image:height" type="number" required={false}>
317-
The height of the image in pixels.
318-
</ParamField>
319-
320-
<ParamField path="og:locale" type="string" required={false}>
321-
The locale of the page, typically in the format `language_TERRITORY` (e.g., `en_US`).
322-
</ParamField>
323-
324-
<ParamField path="og:logo" type="string" required={false}>
325-
The URL or identifier of the logo image of your website that will be displayed when your content is shared.
326-
</ParamField>
327-
328-
### Twitter Properties
329-
<ParamField path="twitter:title" type="string" required={false}>
330-
The title of your page as it should appear in a tweet.
331-
</ParamField>
332-
333-
<ParamField path="twitter:description" type="string" required={false}>
334-
The description of your page as it should appear in a tweet.
335-
</ParamField>
336-
337-
<ParamField path="twitter:handle" type="string" required={false}>
338-
The Twitter handle of the page creator or site.
339-
</ParamField>
340-
341-
<ParamField path="twitter:image" type="string" required={false}>
342-
The URL or identifier of the image that will be displayed in a tweet.
343-
</ParamField>
344-
345-
<ParamField path="twitter:site" type="string" required={false}>
346-
The name of your website as it should appear in a tweet.
347-
</ParamField>
348-
349-
<ParamField path="twitter:url" type="string" required={false}>
350-
The URL of your page.
351-
</ParamField>
352-
353-
<ParamField path="twitter:card" type="string" required={false}>
354-
The type of card to be used for sharing on Twitter. Options: `summary`, `summary_large_image`, `app`, `player`
355-
</ParamField>
356-
357-
### Indexing Properties
358-
<ParamField path="noindex" type="boolean" required={false} default={false}>
359-
If set to `true`, the page will not be indexed by search engines.
360-
</ParamField>
361-
362-
<ParamField path="nofollow" type="boolean" required={false} default={false}>
363-
If set to `true`, a search engine will not follow any links present on the page.
364-
</ParamField>
252+
<Markdown src="/snippets/seo-metadata-page.mdx" />

‎fern/products/docs/pages/customization/what-is-docs-yml.mdx‎

Lines changed: 6 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ navbar-links:
100100

101101
<ParamField path="metadata" type="object" required={false}>
102102
Configure SEO metadata for your documentation website. Learn more about the
103-
[`metadata` configuration](/learn/docs/getting-started/global-configuration#metadata-configuration).
103+
[`metadata` configuration](/learn/docs/getting-started/global-configuration#seo-metadata-configuration).
104104
</ParamField>
105105

106106
## Instances configuration
@@ -523,91 +523,13 @@ landing-page:
523523

524524
See [Vapi's landing page live](https://docs.vapi.ai/) and the associated [Markdown file](https://github.com/VapiAI/docs/blob/main/fern/quickstart/introduction.mdx?plain=1).
525525

526-
## Metadata configuration
526+
## SEO metadata configuration
527527

528-
```yaml docs.yml
529-
metadata:
530-
# Core platform identity
531-
og:site_name: "Square Developer Documentation"
532-
og:title: "Square Developer Platform | Payments, Commerce & Banking APIs"
533-
og:description: "Build with Square's suite of APIs and SDKs. Accept payments, manage inventory, create loyalty programs, and access financial services. Complete documentation for developers building the future of commerce."
534-
og:url: "https://developer.squareup.com/docs"
535-
536-
# Social sharing assets
537-
og:image: "https://developer.squareup.com/images/docs-social-card.png"
538-
og:image:width: 1200
539-
og:image:height: 630
540-
og:locale: "en_US"
541-
og:logo: "https://developer.squareup.com/images/square-logo.png"
542-
543-
# Twitter (I mean X) optimization
544-
twitter:title: "Square Developer Platform Documentation"
545-
twitter:description: "Integrate payments, point-of-sale, inventory, and financial services into your applications with Square's developer platform. Get started with our APIs, SDKs, and comprehensive guides."
546-
twitter:handle: "@SquareDev"
547-
twitter:image: "https://developer.squareup.com/images/twitter-card.png"
548-
twitter:site: "@Square"
549-
twitter:card: "summary_large_image"
550-
```
551-
552-
<ParamField path="metadata.og:site_name" type="string" required={false}>
553-
The name of your website for Open Graph tags.
554-
</ParamField>
555-
556-
<ParamField path="metadata.og:title" type="string" required={false}>
557-
The title shown in social media previews.
558-
</ParamField>
559-
560-
<ParamField path="metadata.og:description" type="string" required={false}>
561-
The description shown in social media previews.
562-
</ParamField>
563-
564-
<ParamField path="metadata.og:url" type="string" required={false}>
565-
The canonical URL of your documentation.
566-
</ParamField>
567-
568-
<ParamField path="metadata.og:image" type="string" required={false}>
569-
The image shown in social media previews. Recommended size is 1200x630 pixels.
570-
</ParamField>
571-
572-
<ParamField path="metadata.og:image:width" type="number" required={false}>
573-
The width of your Open Graph image in pixels.
574-
</ParamField>
575-
576-
<ParamField path="metadata.og:image:height" type="number" required={false}>
577-
The height of your Open Graph image in pixels.
578-
</ParamField>
528+
<Note title="Looking to set metadata for a single page?">
529+
[Use the `keywords` property in a page's frontmatter](/docs/configuration/page-level-settings#seo-metadata).
530+
</Note>
579531

580-
<ParamField path="metadata.og:locale" type="string" required={false}>
581-
The locale of your content (e.g., "en_US").
582-
</ParamField>
583-
584-
<ParamField path="metadata.og:logo" type="string" required={false}>
585-
URL to your company logo.
586-
</ParamField>
587-
588-
<ParamField path="metadata.twitter:title" type="string" required={false}>
589-
The title shown in Twitter Card previews.
590-
</ParamField>
591-
592-
<ParamField path="metadata.twitter:description" type="string" required={false}>
593-
The description shown in Twitter Card previews.
594-
</ParamField>
595-
596-
<ParamField path="metadata.twitter:handle" type="string" required={false}>
597-
Your company's Twitter handle.
598-
</ParamField>
599-
600-
<ParamField path="metadata.twitter:image" type="string" required={false}>
601-
The image shown in Twitter Card previews.
602-
</ParamField>
603-
604-
<ParamField path="metadata.twitter:site" type="string" required={false}>
605-
The Twitter handle for your website.
606-
</ParamField>
607-
608-
<ParamField path="metadata.twitter:card" type="string" required={false}>
609-
The Twitter Card type. Options are `summary`, `summary_large_image`, `app`, or `player`.
610-
</ParamField>
532+
<Markdown src="/snippets/seo-metadata-site.mdx" />
611533

612534
## Analytics configuration
613535

‎fern/products/docs/pages/seo/metadata.mdx‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Configure SEO metadata
3+
description: Configure SEO metadata at the page or site level.
4+
---
5+
6+
Optimize your documentation's search visibility and social media presence by configuring SEO metadata at the page or site level. Properly configured metadata helps search engines understand your content and creates compelling previews when your pages are shared on social platforms.
7+
8+
When configuring SEO metadata, ensure your titles and descriptions are unique, descriptive, and relevant to the page content. Keep descriptions between 150-160 characters for optimal display in search results.
9+
10+
## Page metadata
11+
12+
Set SEO properties in each page's [frontmatter](/docs/configuration/page-level-settings) to control how individual pages appear in search results and social media shares. Page-level metadata takes precedence over site-wide settings.
13+
14+
<Markdown src="/snippets/seo-metadata-page.mdx" />
15+
16+
## Website metadata
17+
18+
Define default SEO properties for your entire documentation site in your [`docs.yml` file](/docs/configuration/what-is-docs-yml). These settings apply to all pages unless overridden by page-specific metadata.
19+
20+
<Markdown src="/snippets/seo-metadata-site.mdx" />

‎fern/snippets/seo-metadata-page.mdx‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
<CodeBlock title="plantstore-quickstart.mdx">
2+
```mdx
3+
---
4+
title: PlantStore API Quick Start
5+
headline: "Get Started with PlantStore API | Developer Documentation"
6+
keywords: plants, garden, nursery
7+
canonical-url: https://docs.plantstore.dev/welcome
8+
og:site_name: PlantStore Developer Documentation
9+
og:title: "PlantStore API Quick Start Guide"
10+
og:description: "Learn how to integrate with PlantStore's API to manage plant inventory, process orders, and track shipments. Complete with code examples."
11+
og:image: https://plantstore.dev/images/api-docs-banner.png
12+
og:image:width: 1200
13+
og:image:height: 630
14+
twitter:card: summary_large_image
15+
twitter:site: "@PlantStoreAPI"
16+
noindex: false
17+
nofollow: false
18+
---
19+
```
20+
</CodeBlock>
21+
22+
<AccordionGroup>
23+
<Accordion title="Document properties">
24+
25+
<ParamField path="headline" type="string" required={false}>
26+
When set, the `<title />` tag in the document head will use this value rather than the `title` property. This property changes the title that search engines see when crawling this page, and can be used to address Duplicate Title issues in your SEO report.
27+
</ParamField>
28+
29+
<ParamField path="canonical-url" type="string" required={false}>
30+
Overrides the canonical URL for this page. Must be a full URL including the protocol (i.e. `https://buildwithfern.com/learn/docs/content/frontmatter`)
31+
</ParamField>
32+
33+
<ParamField path="keywords" type="string" required={false}>
34+
Comma-separated string of keywords relevant to the page content (i.e. `plants, garden, nursery`). These keywords help search engines understand the page topic and contributes to search rankings. Use specific, relevant terms that users might search for when looking for the page's content.
35+
36+
This field accepts only comma-separated strings, not bracketed arrays.
37+
38+
</ParamField>
39+
40+
</Accordion>
41+
<Accordion title="OpenGraph properties">
42+
43+
<ParamField path="og:site_name" type="string" required={false}>
44+
The name of your website as it should appear when your content is shared.
45+
</ParamField>
46+
47+
<ParamField path="og:title" type="string" required={false}>
48+
The title of your page as it should appear when your content is shared.
49+
</ParamField>
50+
51+
<ParamField path="og:description" type="string" required={false}>
52+
The description of your page as it should appear when your content is shared.
53+
</ParamField>
54+
55+
<ParamField path="og:url" type="string" required={false}>
56+
The URL of your page.
57+
</ParamField>
58+
59+
<ParamField path="og:image" type="string" required={false}>
60+
The URL or identifier of the image that will be displayed when your content is shared.
61+
</ParamField>
62+
63+
<ParamField path="og:image:width" type="number" required={false}>
64+
The width of the image in pixels.
65+
</ParamField>
66+
67+
<ParamField path="og:image:height" type="number" required={false}>
68+
The height of the image in pixels.
69+
</ParamField>
70+
71+
<ParamField path="og:locale" type="string" required={false}>
72+
The locale of the page, typically in the format `language_TERRITORY` (e.g., `en_US`).
73+
</ParamField>
74+
75+
<ParamField path="og:logo" type="string" required={false}>
76+
The URL or identifier of the logo image of your website that will be displayed when your content is shared.
77+
</ParamField>
78+
</Accordion>
79+
<Accordion title="Twitter properties">
80+
81+
<ParamField path="twitter:title" type="string" required={false}>
82+
The title of your page as it should appear in a tweet.
83+
</ParamField>
84+
85+
<ParamField path="twitter:description" type="string" required={false}>
86+
The description of your page as it should appear in a tweet.
87+
</ParamField>
88+
89+
<ParamField path="twitter:handle" type="string" required={false}>
90+
The Twitter handle of the page creator or site.
91+
</ParamField>
92+
93+
<ParamField path="twitter:image" type="string" required={false}>
94+
The URL or identifier of the image that will be displayed in a tweet.
95+
</ParamField>
96+
97+
<ParamField path="twitter:site" type="string" required={false}>
98+
The name of your website as it should appear in a tweet.
99+
</ParamField>
100+
101+
<ParamField path="twitter:url" type="string" required={false}>
102+
The URL of your page.
103+
</ParamField>
104+
105+
<ParamField path="twitter:card" type="string" required={false}>
106+
The type of card to be used for sharing on Twitter. Options: `summary`, `summary_large_image`, `app`, `player`
107+
</ParamField>
108+
</Accordion>
109+
<Accordion title="Indexing properties">
110+
<ParamField path="noindex" type="boolean" required={false} default={false}>
111+
If set to `true`, the page will not be indexed by search engines.
112+
</ParamField>
113+
114+
<ParamField path="nofollow" type="boolean" required={false} default={false}>
115+
If set to `true`, a search engine will not follow any links present on the page.
116+
</ParamField>
117+
</Accordion>
118+
</AccordionGroup>

0 commit comments

Comments
 (0)