`seo`
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Use the seo options to control the contents of your project's HTML <head> element, llms.txt file generation, and search engine optimization features like sitemaps and indexing control. You can override seo options, except llmstxt, in the front matter of Markdown and React pages.

The seo option also supports page-level configuration using front matter.

Options

Option	Type	Description
description	string	Sets the contents of the `<meta name="description">` tag. The description can be up to 150 characters long. This text may be used in search engine results pages. Adds the same value to `og:description` and `twitter:description` parameters. To change the description in the social media preview, you can override the parameters using `og:description` or `twitter:description` specified in `meta` option.
image	string	Sets the image with extended metadata (`og:image`, `twitter:image`) used when sharing links to your project on social networks. You must specify the path to an existing image in your project project. In addition, you can replace the image for Twitter or other social networks separately with `og:image` or `twitter:image` at is specified in the `meta` option.
jsonLd	JSON	Configures JSON-LD parameters.
keywords	string \| [string]	Sets the contents of the `<meta name="keywords">` tag.
lang	string	Sets the language attribute to indicate the language in which the content is written. Provide the `lang` value as a language tag with optional subtags (for example, `en-US` for United States English, `es` for Spanish). Consult the W3.org guide and the language subtag registry for more information about language tags and subtags.
meta	[Meta object]	Array of additional meta tags.
siteUrl	string	Sets the base URL for canonical links. When this option is configured, it automatically adds `rel="canonical"` to the head of all HTML pages. This option is required to generate a sitemap, see more information in the Sitemaps section below. This option should not be used in front matter.
title	string	Sets the default contents of the `<title>` HTML tag for all pages in your project. Heading tags like `<h1>`, or a `seo.title` in front matter of a Markdown file, take priority over this default value. Priority order: this global `seo.title` (lowest) < page headings < `seo.title` in front matter (highest). This title is used in search engine results pages, and when sharing links to your project on social media. To change the preview of social networks, you can override using `og:description` or `twitter:description` in the specified `meta` option.
llmstxt	llmstxt object	`llms.txt` file generation options.

Meta object

Option	Type	Description
name	string	Meta tag name property
content	string	Meta tag content property

llmstxt object

Option	Type	Description
hide	boolean	Specifies if an `llms.txt` file and clean Markdown versions of pages included in the `llms.txt` file are generated. Defaults to `false`.
title	string	Name of the project. If this option is not specified, the value of the `seo.title` option is used.
description	string	Short summary of the project. If this option is not specified, the value of the `seo.description` option is used.
details	llmstxt details object	Defines sources for detailed information about the project.
excludeFiles	[string]	List of files or glob patterns to exclude from the `llms.txt` file. The list can contain relative paths to files, glob patterns (like `.md` or `docs//.md`), or negated glob patterns (for example, `!docs/*/.md`).
sections	[llmstxt section object]	List of sections to include in the `llms.txt` file. See llms.txt format documentation for details.

Default values for the llmstxt object are:

  llmstxt:
    sections:
      - title: Optional
        includeFiles:
          - '**/*'
        excludeFiles: []

llmstxt details object

Option	Type	Description
path	string	Path to the `.md` file with detailed information about the project. Must be a relative path to the `redocly.yaml` config. Mutually exclusive with `content`.
content	string	Detailed information about the project. Must be a string. Mutually exclusive with `path`.

llmstxt section object

Option	Type	Description
title	string	REQUIRED. Section title. See llms.txt format documentation for details.
description	string	Short summary of the section.
includeFiles	[string]	List of files or glob patterns to include in the section. The list can contain relative paths to files, glob patterns (like `.md` or `docs//.md`), or negated glob patterns (for example, `!docs/*/.md`).
excludeFiles	[string]	List of files or glob patterns to exclude from the section. The list can contain relative paths to files, glob patterns (like `.md` or `docs//.md`), or negated glob patterns (for example, `!docs/*/.md`).

Sitemaps

A sitemap is a resource that lists all the pages in your website to help search engines and other automation tools identify all the pages available.

Generate a sitemap

When the siteUrl is set, Redocly automatically generates and hosts a sitemap file for your project at build time. The sitemap is accessible at https://your-domain.com/sitemap.xml.

seo:
  siteUrl: https://docs.example.com

No protected content

The generated sitemap does not include any pages protected by role based access controls or pages listed in the ignore configuration.

The sitemap data is formatted to standard search engine expectations, using the <loc> tag:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://docs.example.com/</loc>
  </url>
  <url>
    <loc>https://docs.example.com/reference/</loc>
  </url>
</urlset>

Page priority

Redocly sets the optional priority property for pages in the generated sitemap.xml file to 0.5, unless the pages are non-default versioned content (set to 0.3). This distinction tells search engines the default version of content is more important than non-default versions.

You can override the priority for specific pages:

Markdown files:

---
seo:
  priority: 0.9
---

React/TSX files:

export const frontmatter = {
  seo: {
    priority: 0.9
  }
};

Custom sitemap

Add a custom sitemap by placing a sitemap.xml file into the /static folder in the root of your project:

your-awesome-project/
├──static/
│   └──sitemap.xml
├──guides/
├──redocly.yaml
└──...

Validate your sitemap

Redocly serves the sitemap but doesn't validate the structure, so you should validate your sitemap before adding the file.

Control search indexing

Use the noindex rule to block search indexing for your entire project or specific pages. The noindex rule tells search engines that pages shouldn't be indexed or included in searches.

The noindex rule only applies to external search engines. It does not block pages from in-site search (controlled by excludeFromSearch) or user access (controlled by RBAC).

Block indexing with meta tags

Add <meta name="robots" content="noindex"> to page HTML headers.

For an entire project:

seo:
  meta:
    - name: robots
      content: noindex

For specific pages using front matter:

---
seo:
  meta:
    - name: robots
      content: noindex
---

Block indexing with response headers

Add the X-Robots-Tag: noindex HTTP response header.

For an entire project:

responseHeaders: 
  '**':
    - name: X-Robots-Tag
      value: noindex

For specific pages:

responseHeaders: 
  /blog/example-draft:
    - name: X-Robots-Tag
      value: noindex
  '/internal-docs/**':
    - name: X-Robots-Tag
      value: noindex

Static SEO files

Robots.txt file

Add a robots.txt file to manage how search engines index your website by placing it in the /static folder:

your-awesome-project/
├──static/
│   ├──robots.txt
│   └──...
├──guides/
├──redocly.yaml
└──...

Example robots.txt content:

User-agent: *

Allow: /
Disallow: /internal-docs/

sitemap: https://docs.example.com/sitemap.xml

Site ownership verification

Verify ownership of your website with third-party tools (like Google Search Console) by adding verification files to the /static folder:

your-awesome-project/
├──static/
│   ├──google1234567890abcde.html
│   └──.well-known/
│       └──apple-developer-merchantid-domain-association.txt
├──guides/
├──redocly.yaml
└──...

The verification files will be accessible at:

https://docs.example.com/google1234567890abcde.html
https://docs.example.com/.well-known/apple-developer-merchantid-domain-association.txt

Examples

The following is an example of setting default values for all pages in the configuration file.

seo:
  title: Example Project
  description: Learn how to work with Example APIs
  siteUrl: https://www.example.com
  image: ./images/example-project-home.png
  keywords: 'documentation, api'
  lang: en-US
  jsonLd:
    '@context': 'https://schema.org'
    '@type': 'Organization'
    url: 'http://www.example.com'
    name: My website
    contactPoint:
      '@type': 'ContactPoint'
      telephone: '+1111111111111'
      contactType: 'Customer service'
  meta:
    - name: twitter:image
      content: ./images/twitter-image.png
    - name: twitter:description
      content: 'Overridden description for Twitter'
  llmstxt:
    hide: false
    title: Example Project title for llms.txt
    description: Example Project description for llms.txt 
    details:
      content: Details of the Example Project
    sections: 
      - title: Docs
        description: This is a description of the Docs section
        includeFiles:
          - docs/**/*.md
      - title: API Catalog
        description: This is a description of the API Catalog section
        includeFiles:
          - '**/openapi.yaml'
        excludeFiles:
          - '**/openapi-legacy.yaml'
      - title: 'Optional'
        includeFiles:
          - '**/*.md'
        excludeFiles:
          - '**/wrong.md'

The following example shows how to override the title and description in the front matter of a specific Markdown page.

---
seo:
  title: Apricot Trees
  description: Harvest apricots in the summer.
---

# Apricots

This page is about apricots.

The following example shows how to override the title and description in the front matter of a specific React page.

export const frontmatter = {
  seo: {
    title: 'Example Project',
    description: 'Learn how to work with Example APIs',
  },
};

Resources

Static assets - Host and manage static assets in Redocly projects for enhanced SEO performance and content delivery
Custom domain setup - Personalize your URL to reflect your brand and improve SEO ranking with custom domain configuration
Front matter configuration - Configure SEO settings on individual pages using front matter for granular search optimization control
Response headers - Configure response headers for advanced search engine indexing control and optimization strategies
Configuration options - Explore other project configuration options for comprehensive documentation and platform customization

seoCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude