Files
The Files panel shows your whole docs site as a set of files: one settings file, your stylesheets and custom code, every page as an MDX file, and your custom components. Open any of them in a code editor, change it, and save.
Nothing in the panel is stored as a file. Each file is a view of something the studio already edits, read when you open it and written back when you save. Change a page in the visual editor and its file shows the change; save the file and the visual editor shows it. The two never disagree.
Opening the panel
Files lives in the right-hand panel of API Studio, beside Request code.
- On an endpoint, the panel opens on Request code. Switch to Files at the top of the panel.
- On a page, or anywhere request code does not apply, the panel shows Files on its own.
- On a narrow screen, the panel button in the studio header opens it as a drawer.
Type in Filter files to narrow the list by name. Click a file to open it in the editor in the middle of the studio.
What the files are
| Group | Files | What they hold |
|---|---|---|
| Config | octri.json | Every setting a schema can describe: appearance, navigation, home page, redirects, nav buttons, socials, SEO, feedback, the playground |
| Styles | styles/ | Your theme stylesheet |
| Custom code | custom-code/, head.html, body-end.html | A stylesheet and HTML added to every docs page |
| Pages | pages/ | One file per page, with its frontmatter and body |
| Components | components/ or .mdx, plus <Name>.css | Each custom component's source and its scoped stylesheet |
Every setting in octri.json is covered in the octri.json reference.
Custom code and Components are on the Growth plan and above. On a lower plan the group shows a lock and no files.
A page's path is its place in your navigation: the tab, then any folders, then the page, which matches its URL. Move a page in the navigation and its file moves with it. A page that is not in the navigation sits at the top of pages/ under its slug.
Editing and saving
Save with the Save button above the editor, or press Ctrl+S (Cmd+S on a Mac). MDX files are formatted as they save.
- The status beside the button reads Unsaved changes, Saving… or Saved. Revert throws away your unsaved edits.
- A dot beside a file in the list marks unsaved changes, so you can leave a file and come back to it. A collapsed folder shows the dot when something inside it is unsaved.
- If a save is refused, nothing is written. The editor lists each problem to fix, for example a page with no title.
- If the same settings change somewhere else while you edit, for example in the visual editor, a notice offers Load latest. Saving anyway writes only the parts you changed in the file.
When a save reaches readers
One Save button means different things for different files. The label above the editor tells you which rule a file follows.
| Label | Files | What saving does |
|---|---|---|
| Draft until Publish | Pages | Writes the page's draft. Readers see it after you publish. |
| Applies on save | Styles, custom code, components | Changes the live docs straight away. |
| Draft and live | octri.json | Navigation, the home page and redirects save as a draft until you publish. Everything else applies on save. |
A stylesheet, custom code or component change reaches readers the moment you save it, with no Publish step. Check it in the preview before you save.
Page files
A page file is the same draft the page editor writes. It opens with frontmatter between two --- lines, followed by the page body in MDX.
---
title: Authentication
description: How to get an API key and send it with every request.
badge: New
---
Every request needs an API key. Create one from your dashboard.| Field | What it sets |
|---|---|
title | The page title. Required. |
description | The description search engines and link previews show. |
icon | The page's icon in the sidebar. |
badge | A short label beside the page in the sidebar. |
badgeColor | The badge's colour. |
The body takes every component the page editor does. See Components.
Adding and importing files
Each group, and each folder inside Pages, has a ⋯ menu beside its name. It offers only what can be added in that place.
How imported pages land
Before anything is written, the import lists every file and where it will go. Octri matches each file to a page like this:
- By place
The folder the picked files share is dropped from their paths, along with the extension, and the rest is read as a place in your navigation.
guides/auth.mdxlands on the page atguides/auth. A folder'sindexfile stands for the folder itself. - By slug
If no page sits at that place, the file lands on the one page with the same slug.
- As a new page
Otherwise it becomes a new page, marked New page in the list.
Two files never land on the same page. One import takes up to 100 files, and hidden folders and node_modules are skipped.
An import writes page drafts only. Nothing reaches readers until you publish.
Pulling from GitHub
With a GitHub repository connected to the project, Pull from GitHub in the Pages menu lists the .mdx and .md files on your branch. Pick the ones you want and they land as page drafts, matched by the same rules as an import.
The pull is forgiving about frontmatter. It keeps the fields a page file takes, skips anything else, and names what it skipped. A file with no title but a leading # Heading uses the heading as its title.
To keep pages in step with your repository, tick Keep these pages in step with pushes to your branch and set the Docs folder. From then on, a push that adds or changes a .mdx or .md file in that folder updates its page draft.
- Nothing reaches readers before you publish.
- A deleted file leaves its page alone.
- Each file stays linked to the page it landed on, so later pushes reach the same page even after you rename it.