GitHub sync
GitHub can be the home for your spec, your docs pages, or both. Connect a repository in Project settings, under GitHub, and choose how far you want it to go. There are three separate pieces.
| Piece | Direction | Turn it on in |
|---|---|---|
| Spec auto-sync | GitHub to Octri | Project settings, GitHub |
| Commit endpoint changes | Octri to GitHub | Docs settings, GitHub sync |
| Docs pull and sync on push | GitHub to Octri | The Files panel, Pull |
Spec auto-sync
Turn on Auto-sync and a push that changes your spec imports the new version. What happens to it next follows your spec sync setting. Press Sync now to import straight away.
Committing endpoint changes
Turn on Commit endpoint changes to GitHub so endpoints you add or delete in API Studio are written to your repository's spec.
With it off, endpoints you add or delete stay in Octri, and the next push to your repository replaces them.
Pulling pages from GitHub
Write your pages as .mdx or .md files in your repository and bring them in as drafts.
- Open Pull
In the Files panel, press Pull. It appears once a repository is connected, if you can edit both API Studio and the docs navigation.
- Pick your files
Octri lists the Markdown files on your branch. You can read up to 50 at a time.
- Check where each one lands
Each file shows its destination before anything is written. Then pull.
- Review and publish
Pulled files become page drafts, so nothing goes live until you publish.
Where a file lands
Octri removes the common folder of the files you picked and the extension, and reads index as its folder. Then it looks for:
- The page at that place in your navigation
- Otherwise, the one page with that slug
- Otherwise, it creates a new unpublished page
Frontmatter
Octri takes title, description, icon, badge and badgeColor when they're valid. Anything else is skipped and named in the result. With no title, a leading # Heading becomes the title and is removed from the body.
Syncing pages on every push
In the Pull dialog, turn on sync and name the folder that holds your docs. After that, a push that adds or changes files in the folder updates the matching pages.
- Pages stay linked. Octri remembers which file feeds which page, so renaming a page in the studio doesn't break the link.
- Pushes write drafts. A push doesn't reach readers until someone publishes.
- Removing a file doesn't delete a page. Delete pages yourself in the studio.
- A renamed file reads as a removal and an addition. It lands by place or slug, or becomes a new page.
- Octri never writes pages back to your repository.
From the CLI
Connecting a repository, syncing the spec, and pulling or syncing pages all work from octri github.