Skip to content
Last updated

Configure Redocly

The redocly.yaml file is the single place to configure everything Redocly. This configuration file allows you to customize your API documentation, developer projects, and other Redocly services according to your needs.

This guide provides a comprehensive overview of available configuration options organized by functional areas.

Filter configuration options
Choose your Redocly products and plan to see only the configuration options available to you. Select filters below to get started.
Products
Plan

API Management

These options let you define your APIs and control how API descriptions are processed and validated.

apis

Loading description and requirements…

openapi

Loading description and requirements…

graphql

Loading description and requirements…

mock-server

Loading description and requirements…

decorators

Loading description and requirements…

preprocessors

Loading description and requirements…

extends

Loading description and requirements…

rules

Loading description and requirements…

scorecard

Loading description and requirements…

catalog-classic

Loading description and requirements…

Navigation elements

These settings control how users navigate through your documentation project.

navbar

Loading description and requirements…

sidebar

Loading description and requirements…

footer

Loading description and requirements…

navigation

Loading description and requirements…

search

Loading description and requirements…

User interface

Customize the look and feel of your documentation project with these options.

code-snippet

Loading description and requirements…

breadcrumbs

Loading description and requirements…

markdown

Loading description and requirements…

remove-attribution

Loading description and requirements…

logo

Loading description and requirements…

color-mode

Loading description and requirements…

user-menu

Loading description and requirements…

Content management

Organize and control documentation content, versions, and localization.

products

Loading description and requirements…

version-picker

Loading description and requirements…

l10n

Loading description and requirements…

metadata

Loading description and requirements…

metadata-globs

Loading description and requirements…

Security and access management

Configure user authentication and access controls for your documentation.

rbac

Loading description and requirements…

requires-login

Loading description and requirements…

sso

Loading description and requirements…

residency

Loading description and requirements…

Customization

Extend functionality with custom code and additional features.

api-functions

Loading description and requirements…

plugins

Loading description and requirements…

resolve

Loading description and requirements…

env

Loading description and requirements…

response-headers

Loading description and requirements…

links

Loading description and requirements…

scripts

Loading description and requirements…

Analytics and SEO

Improve discoverability and track usage of your documentation.

analytics

Loading description and requirements…

seo

Loading description and requirements…

redirects

Loading description and requirements…

ignore

Loading description and requirements…

Developer experience

Enhance the experience for developers using your APIs.

developer-onboarding

Loading description and requirements…

feedback

Loading description and requirements…

reunite

Loading description and requirements…

Example configuration

The following example demonstrates a typical redocly.yaml configuration combining various options:

logo:
  srcSet: './images/redocly-logo.svg light, ./images/redocly-logo-inverted.svg dark'
  altText: Redocly logo
  link: '/'
navbar:
  items:
    - page: index.md
      label: '{{ process.env.HOME_LABEL }}' 
    - page: config/index.md
      label: Config
feedback:
  type: sentiment
  settings:
    comment:
      likeLabel: What was most helpful?
      dislikeLabel: What can we improve?

apis:
  redocly-museum:
    root: './openapi-files/redocly-museum.yaml'

extends:
  - recommended

rules:
  info-license: error
  no-ambiguous-paths: error
  no-http-verbs-in-paths:
    severity: error
    splitIntoWords: true
  rule/operationId-casing:
    subject:
      type: Operation
      property: operationId
    assertions:
      casing: camelCase
  rule/no-description-start-with-the-a-an:
    subject:
      type: any
      property: description
    assertions:
      notPattern: /^(The\s|A\s|An\s)/

rbac:
  content:
    '**'
      authenticated: read

redirects:
  '/concepts/categories/':
    to: 'author/concepts/categories/'
  '/concepts/navigation/':
    to: 'author/concepts/navigation/'

This example includes logo customization, navigation setup, feedback controls, API descriptions, rule configurations, access controls, and redirects.

Configuration principles

Redocly has a few important configuration philosophies:

  • universal config (all configuration in one place)
  • zero config (you don't need to do any configuration because we have sane defaults)
  • config-as-code (all configuration should be writable in a simple source-control friendly format)

Some options have multiple levels of nesting. Pay attention to the indentation and nesting when modifying the file.

Next steps

After configuring your redocly.yaml file, you can validate it using the Redocly CLI with npx @redocly/cli check-config. For more detailed information about specific configuration options, follow the links in each section.

 
Next page