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:

  1. An images/ folder which stores image assets such as your logo,
  2. An apis/ folder to store machine-readable specs to allow you to render APIs or Schemas,
  3. At least one content folder (e.g. platform/) below, and
  4. A portal.yaml file which sets top-level portal configuration and navigation.
📁 docs/
├──”€ apis/ # Machine-readable API documentation goes here
│ └── openapi/ # One subfolder per protocol
│ └── finspec/
├──”€ images/ # Image assets go here
├──”€ platform/ # Example content folder (create as many as you like)
└──”€ portal.yaml # REQUIRED. Top-level configuration

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:

  1. At least one markdown content file, and
  2. A sidebars.yaml file which defines the left-hand navigation menu.
📁 docs/
├──”€ platform/
│”‚ ├──”€ index.md # Content markdown
│”‚ └──”€ sidebars.yaml # REQUIRED. Sidebar (within folder) configuration

💡 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).

📁 docs/
├──”€ platform/
│”‚ ├──”€ index.md # https://example.com/platform
│”‚ ├──”€ concepts/
│”‚ │”‚ ├──”€ index.md # https://example.com/platform/concepts
│”‚ │” ├──”€ access/
│”‚ │” │”‚ └──”€ index.md # https://example.com/platform/concepts/access
│”‚ │”‚ └── architecture/
│”‚ │”‚ ”‚ └──”€ overview.md # https://example.com/platform/architecture/overview

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.