{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"project-structure","__idx":0},"children":["Project structure"]},{"$$mdtype":"Tag","name":"ConfigOptionRequirements","attributes":{"products":["Redoc","Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly follows a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["zero-config"]}," philosophy."," ","While it provides an opinionated structure for clarity, the only hard requirement is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["at least one content file"]}," to generate a documentation site."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Knowing the common conventions helps you navigate, contribute to, and customize your project more effectively."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-directories-and-files","__idx":1},"children":["Common directories and files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A typical Redocly project includes the following folders and files."," ","Only one content file is strictly required — the rest are optional but help organize and extend your project:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["content files and folders: the files that generate pages (see ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"#content-files"},"children":["Content Files"]}," below)."," ","This is the only ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["required"]}," element - you need at least one file of content."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]},": the primary configuration file used to customize features, navigation, theming, and more."," ","While optional for a basic start, it's essential for most customizations."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.json"]},": the project manifest for managing Node.js dependencies."," ","It is required only if you want to specify a particular version of Redocly packages or install any third-party dependencies."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_partials/"]},": a directory for reusable Markdoc partials"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@l10n/"]},": a directory for locale folders"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@api"]},": a directory for API functions"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme/"]},": a directory for customizing the look, feel, and components of your portal"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static/"]},": optional directory for assets that should be copied directly to the build output without processing"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]},": optional file(s) that define the structure of one or multiple navigation sidebars"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"example-project-tree","__idx":2},"children":["Example project tree"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A common Redocly project directory might look like this:"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Multiple Sidebars","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"treeview","header":{"controls":{"copy":{}}},"source":".\n├── @theme/                 # Theme customizations and custom components\n│   ├── layouts/\n│   ├── markdoc/            # Markdoc configuration\n│   │   ├── components.tsx  # Markdoc custom components\n│   │   └── schema.ts       # Markdoc custom schema\n│   └── styles.css          # Custom global CSS\n├── _partials/              # Reusable Markdoc partials\n├── apis/                   # API description files (e.g., OpenAPI, AsyncAPI, GraphQL)\n│   └── museum.yaml\n├── guides/                 # Guides\n│   ├── guide-1.md\n│   ├── guide-2.md\n│   ├── images/             # Images for the specific content\n│   │   └── guide-1-screenshot.png\n│   ├── index.md\n│   └── sidebars.yaml       # Sidebar specific to the 'guides' section\n├── images/                 # Various shared images\n│   ├── favicon.png\n│   └── header-image.png\n├── tutorials/              # Tutorials\n│   ├── tutorial-1.md\n│   ├── tutorial-2.md\n│   ├── index.md\n│   └── sidebars.yaml       # Sidebar specific to the 'tutorials' section\n├── static/                 # Static assets copied directly to build output\n│   └── robots.txt\n├── index.page.tsx          # Custom React component for the landing page\n├── package.json            # Node.js project manifest\n└── redocly.yaml            # Main Redocly configuration file\n","lang":"treeview"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Single Sidebar","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"treeview","header":{"controls":{"copy":{}}},"source":".\n├── @theme/                 # Theme customizations and custom components\n│   ├── layouts/\n│   ├── markdoc/            # Markdoc configuration\n│   │   ├── components.tsx  # Markdoc custom components\n│   │   └── schema.ts       # Markdoc custom schema\n│   └── styles.css          # Custom global CSS\n├── _partials/              # Reusable Markdoc partials\n├── apis/                   # API description files (e.g., OpenAPI, AsyncAPI, GraphQL)\n│   └── museum.yaml\n├── guides/                 # Guides\n│   ├── guide-1.md\n│   ├── guide-2.md\n│   ├── images/             # Images for the specific content\n│   │   └── guide-1-screenshot.png\n│   └── index.md            # Landing page for guides\n├── images/                 # Various shared images\n│   ├── favicon.png\n│   └── header-image.png\n├── tutorials/              # Tutorials\n│   ├── tutorial-1.md\n│   ├── tutorial-2.md\n│   └── index.md            # Landing page for tutorials\n├── static/                 # Static assets copied directly to build output\n│   └── robots.txt\n├── index.md                # Landing page as markdown file\n├── package.json            # Node.js project manifest\n├── redocly.yaml            # Main Redocly configuration file\n└── sidebars.yaml           # Single sidebar definition for the entire site\n","lang":"treeview"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Multiple locales","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example file structure is for a Redocly project that includes three locales - Spanish-Spain, French and English (default):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"treeview","header":{"controls":{"copy":{}}},"source":".\n├── @l10n/\n│   ├── es-ES/\n|   |   ├── tutorials/\n|   |   │   ├── getting-started.md\n|   |   │   └── index.md\n|   |   ├── how-tos/\n|   |   │   ├── install.md\n|   |   │   └── index.md\n|   |   ├── concepts/\n|   |   │   ├── terms.md\n|   |   │   └── index.md\n|   |   └── translations.yaml\n│   ├── fr/\n|   |   ├── tutorials/\n|   |   │   ├── getting-started.md\n|   |   │   └── index.md\n|   |   ├── how-tos/\n|   |   │   ├── install.md\n|   |   │   └── index.md\n|   |   ├── notions/\n|   |   │   ├── terms.md\n|   |   │   └── index.md\n|   |   └── translations.yaml\n├── tutorials/\n│   ├── getting-started.md\n│   └── index.md\n├── how-tos/\n│   ├── install.md\n│   └── index.md\n├── concepts/\n│   ├── terms.md\n│   └── index.md\n├── sidebars.yaml\n├── index.md\n└── redocly.yaml\n","lang":"treeview"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Multiple products","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"treeview","header":{"controls":{"copy":{}}},"source":".\n├── @theme/                 # Theme customizations and custom components\n│   ├── layouts/\n│   ├── markdoc/            # Markdoc configuration\n│   │   ├── components.tsx  # Markdoc custom components\n│   │   └── schema.ts       # Markdoc custom schema\n│   └── styles.css          # Custom global CSS\n├── _partials/              # Reusable Markdoc partials\n├── products/               # Guides\n│   ├── product-1/          # Product 1\n|   |   ├── apis/           # The nested project structure can use any content structure\n|   |   ├── concepts/\n|   |   ├── how-tos/\n|   |   ├── tutorials/\n|   |   ├── index.md\n|   |   └── sidebars.yaml\n│   ├── product-2/          # Product 2\n|   |   ├── apis/\n│   │   ├── concepts/\n│   │   ├── how-tos/\n│   │   ├── tutorials/\n│   │   ├── index.md\n│   │   └── sidebars.yaml\n├── images/                 # Various shared images\n│   ├── favicon.png\n│   └── header-image.png\n├── static/                 # Static assets copied directly to build output\n│   └── robots.txt\n├── index.page.tsx          # Custom React component for the landing page\n├── package.json            # Node.js project manifest\n└── redocly.yaml            # Main Redocly configuration file\n","lang":"treeview"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Minimal","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"treeview","header":{"controls":{"copy":{}}},"source":".\n└── index.md                # Landing page as markdown file\n","lang":"treeview"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(Note: This is an illustrative example."," ","Your specific structure might vary based on configuration and content organization.)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"core-configuration","__idx":3},"children":["Core configuration"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"redoclyyaml","__idx":4},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the central configuration file for your Redocly project."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refer to the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config"},"children":["Redocly configuration documentation"]}," for a complete overview."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"packagejson","__idx":5},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package.json"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Standard Node.js project file used by package managers (like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pnpm"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["npm"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["yarn"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["bun"]},") to manage project dependencies."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is optional but when it exists it must list your Redocly package as a dependency (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@redocly/realm"]},")."," ","It may also include other packages for custom React-based pages or specific features."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sidebarsyaml","__idx":6},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can create one or more ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," files to define custom navigation structures."," ","Each file declares a hierarchy of items (pages, groups, links, separators)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A sidebar appears only if the current page is explicitly listed in a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]},"."," ","If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file doesn't exist, Redocly falls back to generating a basic sidebar from the folder structure."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For complex projects, using multiple ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," files (e.g., one per major section) provides fine-grained navigation control."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refer to the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/sidebar"},"children":["Sidebars configuration options"]}," for detailed syntax and options."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"content-files","__idx":7},"children":["Content files"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly treats several file types as primary content sources, automatically generating documentation pages from them based on their location in the filesystem."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Supported content file types include:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Markdown (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".md"]},")"]},": The most common format for documentation pages."," ","Redocly uses ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://markdoc.io/"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Markdoc"]}]},", an extensible Markdown format, allowing for custom tags, partials, and advanced content features."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["React pages (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.tsx"]},")"]},": React components used for pages requiring complex layouts, dynamic data fetching, or custom interactive elements."," ","These allow full control over layout, interactivity, and data fetching."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API descriptions (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".yaml"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".json"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".graphql"]},")"]},": API specification files (OpenAPI, AsyncAPI, GraphQL schemas)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"file-based-routing","__idx":8},"children":["File-based routing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Realm uses a file-based routing system."," ","The path and name of a content file within your project root directly determine the URL path for the generated page."," ","The file extension is automatically removed."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["get-started/installation.md"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/get-started/installation"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["concepts/markdoc.md"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/concepts/markdoc"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["changelog.page.tsx"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/changelog"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api/reference/museum.yaml"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/reference/museum"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Content files named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.md"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.page.tsx"]},", or even ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.yaml"]},") serve as the default page for their directory."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/index.md"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/index.page.tsx"]}," at the root becomes the site's home page (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["concepts/index.md"]}," becomes the page accessed at the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/concepts"]}," URL path."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api/reference/index.yaml"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/api/reference"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When content is versioned, the URL path includes the version subfolder."," ","The default version subfolder is the exception: that segment is omitted from the path."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/@v1/guide.md"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/v1/guide"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/@v2/guide.md"]}," (default version) becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/guide"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/@v3/guide.md"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/v3/guide"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When the default version changes to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["v3"]},", the paths also change:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/@v1/guide.md"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/v1/guide"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/@v2/guide.md"]}," becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/v2/guide"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/@v3/guide.md"]}," (default version) becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/config/guide"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some of your content files in the same location may share a name but have different extensions."," ","A file can also be an index file in a folder with the same name as files in the parent folder:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"treeview","data-title":"Example of files with identical names in the same folder","header":{"title":"Example of files with identical names in the same folder","controls":{"copy":{}}},"source":"...\n├── payments/\n│   └── index.md\n├── payments.md\n├── payments.page.tsx\n└── payments.yaml\n","lang":"treeview"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After building the project, all four files would generate the same route: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments"]},"."," ","To avoid having the same route leading to different resources, the build process appends a number (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["-n"]},") to each path."," ","In this case, paths to the files would be:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments-1"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments-2"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/payments-3"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"content-reuse","__idx":9},"children":["Content reuse"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can reuse content across your project by using the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/partial"},"children":["partial markdoc tag"]},"."," ","Reusable content should be stored in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_partials"]}," directory."," ","Learn more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/tag-library"},"children":["Markdoc tags"]}," for other content enhancement options."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"l10n","__idx":10},"children":["@l10n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@l10n"]}," directory is used to store locale files."," ","Each locale has its own folder, and within each locale folder, you can create subfolders for different sections of your documentation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is also an optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["translations.yaml"]}," file that contains the list of UI labels for the locale."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/l10n"},"children":["l10n configuration"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"api","__idx":11},"children":["@api"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@api"]}," directory is the default location for ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization/api-functions"},"children":["API functions"]}," in your project."," ","You can change the name of this directory in the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/api-functions"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apiFunctions"]}," config"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"versioned-content","__idx":12},"children":["Versioned content"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly supports versioned content by using a special folder structure."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Folders prefixed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@"]}," (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@v1"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@v2"]},") are treated as separate content versions."," ","For information how to set up versioned content in your project, see ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/versions"},"children":["Version content"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"multi-product","__idx":13},"children":["Multi-product"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can include multiple products in your project that users can switch between using a product picker in the navbar."," ","A product can be any set of content you want to separate from other documentation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For more information, see ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/navigation/multi-product"},"children":["Multi-product overview"]}," and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/products"},"children":["products configuration"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"customization","__idx":14},"children":["Customization"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"theme","__idx":15},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This special directory allows you to customize the default Redocly theme."," ","You can override or add various elements:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Components (Ejected/Overridden)"]},": Replace or extend default theme components (like headers, buttons, code blocks, layouts) by placing your custom React components in corresponding paths within ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme/*"]},"."," ","This process is often referred to as ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["\"ejecting\""]},"."," ","Refer to the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization/eject-components"},"children":["Eject components"]}," for more information."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Styles"]},": Add global custom CSS rules or modify ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/branding/css-variables"},"children":["theme variables"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme/styles.css"]}," file."," ","This file serves as the main entry point for your custom global styles."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Custom Markdoc tags and functions"]},": Create ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization/build-markdoc-tags"},"children":["new Markdoc tags"]}," and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/customization/build-custom-function"},"children":["functions"]}," within the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme/markdoc"]}," directory to enhance your Markdoc."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"static-files--static-","__idx":16},"children":["Static files (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static/"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Assets referenced directly within your content files (like images in Markdown using relative paths ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["./images/diagram.png"]},") are typically processed and bundled by Realm."," ","However, you often need files that are copied directly to the root of the final build output without any changes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static/"]}," directory serves this purpose."," ","Any files placed inside the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static/"]}," folder will be copied verbatim to the root of your built site."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static/"]}," for things like:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["robots.txt"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["favicon.ico"]}," and other site icons/manifest files"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["verification files for search engines or other services"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["other assets that must exist at specific paths and shouldn't be processed (e.g., fonts referenced by external CSS, specific JS libraries)."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Static files impact on your project"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Files in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static/"]}," are ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["not"]}," processed or optimized by Realm's build system."," ","Avoid placing regular images, CSS, or JavaScript that you author yourself in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static/"]}," directory if you expect them to be bundled or optimized."," ","These files usually belong alongside your content files or within the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["@theme"]}," directory."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"resources","__idx":17},"children":["Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/products"},"children":["Multiple products configuration"]}]}," - Set up product switching and organize documentation for multiple products with separate navigation and branding"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/config/l10n"},"children":["Multiple languages setup"]}]}," - Configure localization and internationalization for multi-language documentation projects"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/content/markdoc-tags/partial"},"children":["Partial tag"]}]}," - Share and reuse content across multiple pages and projects to maintain consistency and reduce duplication"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/realm/navigation/sidebars"},"children":["Configure sidebars"]}]}," - Configure navigation structures and sidebar organization with detailed syntax and options reference"]}]}]},"frontmatter":{"products":["Redoc","Revel","Reef","Realm"],"plans":["Pro","Enterprise","Enterprise+"],"title":"Project structure","description":"An introduction to the file structure of a Redocly project."},"tagList":["admonition","configOptionRequirements","tab","tabs"],"title":"Project structure","lastModified":"2026-10-01T23:00:57.000Z"}