File & Folder Organisation
This portal is designed to be easy to maintain through a flexible system of Markdown files in folders. Because these are just files, they work well with any version control system (e.g. GitHub or GitLab), giving you straightforward deployment and rollback.
ℹ️ Info
This section focuses on documentation pages within the portal. There may be other pages (such as the initial page) which are highly customised, and FixSpec works with customers directly to get these looking just right - they are not described here.
Minimal File Structure
The minimal file structure needed to make the portal work consists of:
- An
images/folder which stores image assets such as your logo, - An
apis/folder to store machine-readable specs to allow you to render APIs or Schemas, - At least one content folder (e.g.
platform/) below, and - A
portal.yamlfile which sets top-level portal configuration and navigation.
Minimal Content Folder Structure
You are free to create as many custom folders and subfolders as you like, adding as many Markdown files (your content) within them as you like.
ℹ️ Reserved Folder Names
The folder names images/, apis/ and schemas/ are reserved at the top level, but you are free to use these as sub-folder names within a custom folder if you wish. The URL /admin is reserved for the portal’s admin interface, so avoid creating a folder with this name.
The minimal file structure needed within each custom folder is:
- At least one markdown content file, and
- A
sidebars.yamlfile which defines the left-hand navigation menu.
💡 Tip
While there is no requirement to name Markdown files index.md, we recommend folder-level “landing” pages be named this way, as it helps generate clean URLs.
Content URLs
There is a direct relationship between the file path within the structure and the URL created. The URL segments directly correspond to the folder names for traversal, with the final segment pointing either to the name of a markdown file (without the .md extension) or to a folder name (at which point we show the index.md file within that folder).
Ready to get started? Check out the Content Formatting section to discover the set of extended Markdown syntax supported.
FAQs
Can I rename or move a folder without breaking existing links? Renaming or moving a folder changes its URL, since the URL is derived directly from the file path — so yes, it will break any existing links or bookmarks pointing to the old path. Plan folder names with that in mind.
Do I need a sidebars.yaml file in every folder?
Only in folders you want to appear in the left-hand navigation. See Section Sidebars for how this works.
Do I have to name my landing page index.md?
No, it isn’t a strict requirement — but it’s the convention this portal expects for a folder’s own URL (e.g. /platform) to resolve to a page, so we recommend following it for any folder-level landing page.