Project structure best practices

Redocly projects follow some best practices when it comes to structuring your project. For instance, by default, projects expect an index.md file as the landing page for each directory. Also, a _partials folder is expected for content reuse files. Furthermore, we recommend following best practices such as placing images in an images folder close to the content where they are referenced. The following sections include example project structures and explanatory content for structuring your Redocly projects.

Customization files

While not required for running a Redocly project, the following are some useful files to include when customizing your project to your particular needs:

• redocly.yaml: This file is your main configuration file. It should be in the root, or main folder of your project. You may have more than one of these files if you have a multi-product configuration. Among other things, you can configure your top navigation menu and footer in this file.
• sidebars.yaml: This file is your left side navigation configuration file. It should be in the root, or main folder of your project, unless you want your navigation to be automatically based on folder structure. You can include more than one of these files and add $refs to different sidebars.yaml files. If you include this file in the root of your project, you must add all content you want displayed in your side navigation.
• translations.yaml: This file includes translated content for labels used within your project. It should be in the corresponding locale folder or in the root of your project if you want to update a label's text.
• versions.yaml: This file allows you to set the order and default version for the version picker UI element when you have multiple content versions. It should be in the main folder for your versioned content.
• styles.css: This file should contain CSS variable values you are using to override the default styles for your project. It should be in the @theme folder described in the following Special directories section.
• index.md: This file should be the default page for the directory. You should include one of these files in the root of your project as the landing page for your project.

Special directories

While not required for running a Redocly project, the following are some useful directories to include when customizing your project to your particular needs:

• images: Use this directory to hold images that are referenced in your Markdown files. You can have multiple images directories to keep your images close to the files that reference them.
• @theme: Use this directory to store your styles.css file as well as any components you have ejected from the default theme.
• static: Use this directory for supplemental files that are referenced in your project files such as PDF documents or scripts. You can host static assets without having to include them in your project's build.
• l10n: Use this directory to store the different locale folders for translations of your documentation.

Example project file trees

To give you a better view into how to structure your project, the following section includes several use cases with sample project file trees.

Multiple products

The following example file structure is for a Redocly project that includes two Acme products: Widgets and Cogs:

acme-docs
├── images
│   ├── cog-logo.png
│   └── widget-logo.png
├── products
│   ├── widget
│   │   ├── widget-openapi.yaml
│   │   ├── index.md
│   │   └── redocly.yaml
│   └── cog
│       ├── images
│       │   ├── round-cog.png 
│       │   ├── square-cog.png
│       │   └── triangle-cog.png
│       ├── cog-openapi.yaml
│       ├── index.md
│       └── redocly.yaml
├── tutorials
│   ├── getting-started.md
│   └── index.md
├── index.md
├── sidebars.yaml
└── redocly.yaml

Multiple languages

The following example file structure is for a Redocly project that includes two locales - Spanish-Spain and French:

hooli-docs
├── @l10n
│   ├── es-ES
|   |   ├── tutorials
|   |   │   ├── getting-started.md
|   |   │   └── index.md
|   |   ├── how-tos
|   |   │   ├── install.md
|   |   │   └── index.md
|   |   ├── concepts
|   |   │   ├── terms.md
|   |   │   └── index.md
|   |   └── translations.yaml
│   ├── fr
|   |   ├── tutorials
|   |   │   ├── getting-started.md
|   |   │   └── index.md
|   |   ├── how-tos
|   |   │   ├── install.md
|   |   │   └── index.md
|   |   ├── notions
|   |   │   ├── terms.md
|   |   │   └── index.md
|   |   └── translations.yaml
├── tutorials
│   ├── getting-started.md
│   └── index.md
├── how-tos
│   ├── install.md
│   └── index.md
├── concepts
│   ├── terms.md
│   └── index.md
├── sidebars.yaml
├── index.md
└── redocly.yaml

Multiple versions

The following example file structure is for a Redocly project that includes two sets of API documentation with different versions:

initech-docs
├── printer-api
│   ├── @1.0
│   │   ├── index.md
│   │   ├── printer-openapi.yaml
│   │   └── overview.md
│   ├── @2.0
│   │   ├── index.md
│   │   └── printer-openapi.yaml
│   ├── @3.0
│   |   ├── diagram.png
│   |   ├── index.md
│   |   └── printer-openapi.yaml
│   └── versions.yaml
├── paper-api
│   ├── @latest
│   │   ├── index.md
│   │   └── paper-openapi.yaml
│   ├── @legacy
│   │   ├── index.md
│   │   ├── paper-openapi.yaml
│   │   └── readme.md
│   └── versions.yaml
├── index.md
├── redocly.yaml
└── sidebars.yaml

Content reuse

The following example file structure is for a Redocly project that includes a _partials folder with a resources file that can now be included in both the getting-started.md and install.md documents:

globex-docs
├── images
│   └── globex-logo.svg
├── _partials
|   └── resources.md
├── tutorials
│   ├── getting-started.md
│   └── index.md
├── how-tos
│   ├── install.md
|   └── index.md
├── index.md
├── sidebars.yaml
└── redocly.yaml

Resources

• Follow step-by-step instructions for configuring your project to include multiple projects or multiple languages.
• Learn more about configuring your project to use the same content in multiple places using the partial markdoc tag.
• See the configuration options available for your sidebars.yaml file in the sidebars reference documentation.