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.
- Community
- Pro
- Scale
- Enterprise
API Management
Define your APIs and control how API descriptions are processed and validated.
Configure rules and settings for individual APIs in multi-API projects.
Customize the behavior and appearance of AsyncAPI documentation. Requires an AsyncAPI description file.
Organize your content into a catalog that users can filter and search. You can configure multiple catalogs and set the link text, description, and filters.
Define transformation steps applied to your API description when it is bundled.
Extend an existing configuration set.
Customize the behavior and appearance of integrated GraphQL documentation. Requires a GraphQL schema.
Configure a mock server in your Redocly-powered API documentation.
Customize the behavior and appearance of OpenAPI documentation. Requires an OpenAPI description file.
Define preprocessor transformation steps for your API description files.
Configure linting rules and their severity.
Add and create sets of rules and test your API description files against them.
Navigation elements
These settings control how users navigate through your documentation project.
Customize the AI assistant functionality in your project.
Customize the footer for the pages in your project.
Configure a navbar for your project.
Control the Previous and Next navigation buttons on project pages.
Customize the search functionality in your project.
Set the visibility of the sidebar in your project.
User interface
Customize the look and feel of your documentation project with these options.
Display announcement banners at the top of your documentation pages.
Control breadcrumb links that indicate a page's location in navigation.
Configure which control UI elements are available for code snippets.
Configure the behavior of the color mode UI control and add more color modes.
Configure a custom logo for the project navbar.
Customize behavior and appearance of pages rendered from Markdown files.
Set the visibility of the user menu in your project.
Content management
Organize and control documentation content, versions, and localization.
Configure localization (internationalization) for your project to support multiple languages.
Configure metadata properties for your project, APIs, and documentation files.
Configure glob patterns to apply metadata to specific files or directories.
Set up multiple product documentation sets in your project.
Configure the visibility of the version picker in your project.
Security and access management
Configure user authentication and access controls for your documentation.
Configure authentication and access-related settings in a single object.
Restrict project login to specific identity providers (IdPs) selected by unique ID.
Configure a URL where users are redirected after they log out.
Use team-based access controls to assign permissions required to files and project access.
This configuration option makes all your content private for non-authenticated users.
Select a geographical location to host your project.
Restrict project login to specific identity provider categories defined in the Redocly platform.
Restrict the built-in CORS proxy to specific remote hosts and paths.
Customization
Extend functionality with custom code and additional features.
Control where Redocly detects and hosts API functions.
Customize the redocly.yaml configuration for each environment.
Add custom fonts, stylesheets, and other links to pages.
Make your content accessible to AI tools.
Configure custom plugins to extend lint and decorator behavior.
Configure how to resolve URLs referenced from API descriptions.
Configure custom response headers for your project.
Insert custom scripts in the head or body of a page.
Control how agent skills are published from your project.
Analytics and SEO
Improve discoverability and track usage of your documentation.
Configure popular analytics providers for your documentation project.
Show a cookie consent banner and load analytics only after the visitor agrees.
Exclude files and folders from the project build without removing the source files from your project.
Configure redirects to resources within your project.
Setup Search Engine Optimization(SEO) for your project.
Developer experience
Enhance the experience for developers using your APIs.
Configure developer onboarding to enable external developers to self-register applications and manage API credentials.
Customize how users leave feedback about your documentation content with this option.
No metadata found for: platform.md
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.
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)
Boolean options should be false by default, and each name must say what true does. Set one only when you want to turn that behavior on. A few options are true by default. Check the reference pages for the option you need.
Some options have multiple levels of nesting. Pay attention to the indentation and nesting when modifying the file.
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.