Organizing your portal content
Your developer portal content will typically be organized as a set of Markdown (.md
) or MDX (.mdx
) files in one or more (sub)folders. After installing the developer portal, you can explore and modify the tutorial files provided in the template, or start creating your own content from scratch.
You may create different types of files depending on your needs.
Every developer portal project must have these files, which you will edit for customization and configuration purposes:
- index.md or index.mdx
- siteConfig.yaml
- sidebars.yaml
- theme.ts
- favicon.png
To create content for your developer portal, you can use:
- Markdown files
- MDX files
- images and other multimedia assets (to embed into Markdown or MDX files)
- OpenAPI definitions (or references to it)
- React components to extend the portal functionality
URL routes
The folder and filename determine the URL route, so be deliberate with your naming.
The special index.md
or index.mdx
name is not included in the URL route. For example, if your base URL is docs.example.com
, and you place index.md
in your project root, the contents would be accessed at https://docs.example.com
.
If you place index.md
inside of a guides
folder, you would access that content at https://docs.example.com/guides
.
On the other hand, if you name the file anything else, such as home.md
, and place it in the guides
folder, it would be accessed at https://docs.example.com/guides/home
.
Note that the .md
and .mdx
file extensions are never included in the URL route.
Developer portal structure
Here is an example structure of a developer portal project.
├── ./README.md
├── ./contact.mdx
├── ./faq.md
├── ./favicon.png
├── ./images
│ ├── ./images/book-management.svg
│ ├── ./images/external-link-dark.svg
│ ├── ./images/found-or-private.svg
│ ├── ./images/icon1.png
│ ├── ./images/icon3.png
│ ├── ./images/launch-fast.svg
│ ├── ./images/logo.png
│ └── ./images/logo.svg
├── ./index.mdx
├── ./openapi
│ └── ./openapi/petstore.yaml
├── ./package.json
├── ./reference.page.yaml
├── ./sidebars.yaml
├── ./siteConfig.yaml
├── ./theme.ts
├── ./developer-portal
│ ├── ./developer-portal/creating-files.md
│ ├── ./developer-portal/development-tips.md
│ ├── ./developer-portal/footer-navigation.md
│ ├── ./developer-portal/installation.md
│ ├── ./developer-portal/introduction.md
│ ├── ./developer-portal/mdx.mdx
│ ├── ./developer-portal/markdown.md
│ ├── ./developer-portal/redoc-integration.md
│ ├── ./developer-portal/sidebar-nav.md
│ └── ./developer-portal/top-navigation.md
└── ./yarn.lock
In this example, most of our content is organized into the developer-portal
folder.
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 create reusable Markdown snippets for single-source authoring.
Excluding pages from portal builds
Page exclusion is supported starting with version 1.0.0-beta.110 of the Developer portal.
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:
- Add
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. - Rename the page source file so that its file name starts with an underscore (
_
). For example, to exclude theintroduction.md
file from the build, you would rename it to_introduction.md
.
To prevent broken links or potential build failures, make sure to remove any entries for the excluded page from your 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.
Excluding the README.md file
If your developer portal project has a README.md
file in the top-level (root) folder, this file will be automatically excluded from builds. File name matching is case-insensitive (readme.md
is treated the same as README.md
).
If you have 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 exclude: true
front matter option. Automatic exclusion applies only when the file is in the root folder of the project.