---
seo:
    title: "File Organisation"
    description: "The minimal folder and Markdown file structure required to run a FixSpec portal from a git repository."
llm_context: "Guide to the portal's on-disk layout - the required images/ and apis/ folders and the flexible Markdown structure that makes the portal git-friendly."
category: "guide"
related:
    - "/portal/reference/navigation"
    - "/portal/guides/pushing"
---

## 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](/portal/guides/rendering_schemas#rendering-apis-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](/portal/reference/navigation#header-navigation).

```treeview 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.

:::info 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](/portal/reference/navigation#section-sidebars).

```treeview 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).

```treeview 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](/portal/reference/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](/portal/reference/navigation#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.
