Configuration

This page describes how to organize the files and folders and how to configure the look and feel of the Portal.

Overview

To start working with Redocly Portal, please get familiar with the following:

The Markdown syntax. We recommend using Visual Studio Code for writing and maintaining your files.
File management basics.

Organizing content

Folders

The following special folders will be created automatically within your project:

images/ – you can keep your images in this folder.
node_modules/ – do not remove or modify the contents of this folder. It contains the software library dependencies.

We recommend creating folders based on your content, and then organizing the content within one root folder:

[_folder_name_]/

Important: The folder naming influences the URL paths of the published website.

File types

Markdown files

A regular markdown file ends with a .md file extension. Utilize the regular markdown files when your content doesn't require any special components.

Markdown extensions

A markdown extension file ends with a .mdx file extension. Learn more about using markdown extensions here.

Special files

The following files must be kept at the top level of the project structure. If needed, you can change the contents of these files to configure look and feel of the Portal.

File	Description
`index.mdx`	The home page of the Portal.
`siteConfig.yaml`	In this file, you can do the following: Set up persistent navigation and logo. Declare API definitions and stylesheets. Add custom scripts. Set up google analytics.
`theme.ts`	Controls the fonts and colors used throughout the Portal.
`sidebars.yaml`	Controls the sidebar navigation among contents.
`favicon.png`	Displays the favicon.

For more details, see Customizing Portal.

Also, you can include your OpenAPI .yaml or .json file directly in the Portal to be able to generate the API reference pages.

For more details, see Integrating API Reference.