{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"organize-your-portal-content","__idx":0},"children":["Organize your portal content"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Deprecated docs"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The developer portal beta is ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/product-timelines"},"children":["approaching end of life"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Realm and Reunite instead. Read the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/migrate-from-legacy-portal"},"children":["migration guide"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You may create different types of files depending on your needs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every developer portal project must have these files, which you edit for ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/configuration/configuration-files"},"children":["customization and configuration"]}," purposes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["index.md or index.md"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["siteConfig.yaml"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["sidebars.yaml"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["theme.ts"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["favicon.png"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To create content for your developer portal, you can use:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/markdown"},"children":["Markdown files"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["images and other multimedia assets (to embed into Markdown or MDX files)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/reference-docs-integration"},"children":["OpenAPI definitions (or references to it)"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"url-routes","__idx":1},"children":["URL routes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The folder and filename determine the URL route, so be deliberate with your naming."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["public"]}," folder name is reserved at the top-level of the portal project structure. You should not use it in the root directory of your portal, but it can be used in subdirectories."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The special ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.md"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.md"]}," name is not included in the URL route. For example, if your base URL is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["docs.example.com"]},", and you place ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.md"]}," in your project root, the contents would be accessed at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://docs.example.com"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you place ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["index.md"]}," inside of a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guides"]}," folder, you would access that content at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://docs.example.com/guides"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On the other hand, if you name the file anything else, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["home.md"]},", and place it in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["guides"]}," folder, it would be accessed at ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://docs.example.com/guides/home"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note that the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".md"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".md"]}," file extensions are never included in the URL route."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"developer-portal-structure","__idx":2},"children":["Developer portal structure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is an example structure of a developer portal project."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"├── ./README.md\n├── ./contact.md\n├── ./faq.md\n├── ./favicon.png\n├── ./images\n│   ├── ./images/book-management.svg\n│   ├── ./images/external-link-dark.svg\n│   ├── ./images/found-or-private.svg\n│   ├── ./images/icon1.png\n│   ├── ./images/icon3.png\n│   ├── ./images/launch-fast.svg\n│   ├── ./images/logo.png\n│   └── ./images/logo.svg\n├── ./index.md\n├── ./openapi\n│   └── ./openapi/petstore.yaml\n├── ./package.json\n├── ./reference.page.yaml\n├── ./sidebars.yaml\n├── ./siteConfig.yaml\n├── ./theme.ts\n├── ./developer-portal\n│   ├── ./developer-portal/creating-files.md\n│   ├── ./developer-portal/development-tips.md\n│   ├── ./developer-portal/footer-navigation.md\n│   ├── ./developer-portal/installation.md\n│   ├── ./developer-portal/introduction.md\n│   ├── ./developer-portal/mdx.md\n│   ├── ./developer-portal/markdown.md\n│   ├── ./developer-portal/reference-docs-integration.md\n│   ├── ./developer-portal/sidebar-nav.md\n│   └── ./developer-portal/top-navigation.md\n└── ./yarn.lock\n","lang":"shell"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, most of our content is organized into the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["developer-portal"]}," folder."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The more content you create, the more you may want to organize it into sub-folders. It's a good practice to separate content by type (e.g. images in one folder, text in another). You can also categorize your content by topic into sub-folders, and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/reusing-content"},"children":["create reusable Markdown snippets"]}," for single-source authoring."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To help your readers access and find the content faster, ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/configuration/sidebar-nav"},"children":["set up a sidebar"]}," for your portal."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-the-static-folder-to-add-assets","__idx":3},"children":["Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static"]}," folder to add assets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In some cases, you may want to host file types other than Markdown in your portal - for example, images, PDF documents, or scripts - and reference them as additional resources in your portal pages."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For this purpose, Redocly Developer portal supports a special folder called ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static"]},". This folder must be in the root of the developer portal project, and its name must be ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static"]}," without any additional characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If it doesn't already exist in your portal project, create it manually before adding any assets into it. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static"]}," folder can contain any number of sub-folders, so you can organize assets by type or any other desired criteria."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All files placed into the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static"]}," folder are served directly from the project root. This allows you to dynamically reference them with absolute links. For example, if you had a file ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["./static/image.png"]},", you would link to it with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://your-portal.example.com/image.png"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Any files (images, Markdown pages...) that you reference in the front matter of MD(X) pages are automatically copied to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static"]}," folder during the portal build. This happens even if you haven't manually created the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["static"]}," folder, and doesn't affect any of the manually added assets (if they exist)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"link-pages","__idx":4},"children":["Link pages"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Any MD(X) page in your Developer portal can contain links to other pages. When linking pages, make sure to use the correct path to the MD(X) file you want to link to."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Starting with the version 1.0.0-beta.115, the Developer portal supports absolute links from the root of the project (relative links have been supported since the first release)."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Absolute link","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"[Example absolute link](/guides/example.md)\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Relative link","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"[Example relative link](../guides/example.md)\n","lang":"shell"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your MD(X) pages contain headings, you can link directly to a specific heading by its name instead of linking to the whole page. This is done by appending a fragment identifier (named anchor) to the file name. Heading names are case-insensitive, but you must replace spaces and any other special symbols in them with hyphens."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Named anchor in MD","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"[Example named anchor](/guides/example.md#heading-name)\n","lang":"shell"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Named anchor in MDX","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"shell","header":{"controls":{"copy":{}}},"source":"[Example named anchor](../guides/example.md#heading-name)\n","lang":"shell"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"exclude-pages-from-portal-builds","__idx":5},"children":["Exclude pages from portal builds"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Page exclusion is supported starting with version 1.0.0-beta.110 of the Developer portal."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In some cases, you may want to exclude specific pages from portal builds without removing the source files from your project. You can achieve this in either of the following two ways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exclude: true"]}," to the front matter of the page you want to exclude. This front matter option is supported in MD and in MDX files."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rename the page source file so that its file name starts with an underscore (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_"]},"). For example, to exclude the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["introduction.md"]}," file from the build, you would rename it to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_introduction.md"]},"."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To prevent broken links or potential build failures, make sure to remove any entries for the excluded page from your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file. If other MD or MDX pages have links pointing to the excluded page, those links should be modified or removed prior to building the portal."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"exclude-the-readmemd-file","__idx":6},"children":["Exclude the README.md file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your developer portal project has a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["README.md"]}," file in the top-level (root) folder, this file is automatically excluded from builds. File name matching is case-insensitive (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readme.md"]}," is treated the same as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["README.md"]},")."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you have ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["README.md"]}," files in other folders and want to exclude them from builds, you must either change their file name to start with an underscore, or add the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["exclude: true"]}," front matter option. Automatic exclusion applies only when the file is in the root folder of the project."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"exclude-folders-from-portal-builds","__idx":7},"children":["Exclude folders from portal builds"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Folder exclusion is supported starting with version ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1.1.0-beta.114"]}," of the Developer portal."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In case you want to exclude entire folder from portal builds you can rename the folder so that its name starts with an underscore (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_"]},"). For example, to exclude the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["legacy"]}," folder from the build, you would rename it to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_legacy"]},"."]}]},"frontmatter":{"seo":{"title":"Organize files in your portal project"},"enableToc":false,"excludeFromSearch":true},"tagList":["admonition","partial","tab","tabs"],"title":"Organize files in your portal project","lastModified":"2025-05-28T16:01:32.000Z"}