Docs as code with GitHub

You can keep a docs site's pages in a GitHub repository. Every push to the connected branch updates the site, and, if you choose, edits made in the EvoHub console go back to the repository as pull requests. This page describes the repository layout EvoHub reads and how to connect it. This documentation is maintained this way.

#The repository layout

EvoHub reads one folder of one branch — the docs root, for example docs/. Inside it:

docs/
├── index.md                  first page ("Introduction")
├── getting-started.md        a top-level page
├── guides/                   a folder of pages is a section
│   ├── _category_.json       {"label": "Guides", "position": 3}
│   ├── 01-install.md
│   ├── 02-configure.md
│   └── 03-deploy.md
├── reference/
│   ├── _category_.json
│   └── components.md
├── images/
│   └── architecture.png      linked from pages by relative path
├── _snippets/
│   └── support.md            the snippet {{snippet:support}}
└── _openapi/
    └── orders.yaml           an API reference at /orders

#Pages and sections

• Every .md, .mdx or .markdown file is a page, except files in folders whose name starts with _.
• Files directly in the docs root are top-level pages.
• A folder that holds pages is a section. A folder inside a section becomes a section of its own, listed right after its parent. A folder with no pages (like images/) is not a section.

#Titles and addresses

• Title: the front matter title, else the first # Heading (which is then left out of the body), else the file name.
• Address (slug): the front matter slug, else the file name without its numeric prefix and extension. 01-install.md is /install; index.md takes its folder's name, and the root index.md is /introduction.

Slugs are unique within a site, so give pages in different folders different file names (or set slug).

#Order

Pages within a folder are ordered by sidebar_position in the front matter, then a numeric prefix of the file name (01-, 1_, 01.), then index.md or README.md first, then the file name.

Sections are ordered by position in their _category_.json, then a numeric prefix of the folder name, then the folder name. _category_.json also names the section:

{"label": "Guides", "position": 3}

Without it, the section is named after the folder (getting-started becomes "Getting started").

#Front matter

A YAML block between two --- lines at the top of a file. Every key is optional:

---
title: Deploy to production
slug: deploy
sidebar_position: 3
sidebar_label: Deploy
description: Ship a release to production from your machine or from CI.
seo_title: How to deploy Acme to production
og_image_url: https://acme.example/og/deploy.png
canonical_url: https://acme.example/docs/deploy
noindex: false
hidden: false
icon: rocket
---

Other keys are ignored. Quote strings that contain a colon: title: "Deploy: the basics".

#Links, images, snippets and API references

• Links between pages use the relative path to the file, as on GitHub: [Configure](./02-configure.md). They become links to the page's address, whatever its slug.
• Images and PDFs are linked relative to the file: ![Architecture](../images/architecture.png). Files a page links to are uploaded with the sync; files nobody links to are not.
• Snippets: _snippets/<name>.md becomes the snippet <name>, included with {{snippet:<name>}} on a line of its own.
• API references: every .yaml, .yml or .json file in _openapi/ is an OpenAPI 3.0 or 3.1 document. It becomes an API reference named after its info.title, at the address of its file name.
• Any other folder starting with _ is skipped; use one for drafts or partials.

Page bodies use the same Markdown and components as the console editor. See Writing pages.

#Start from the starter

The Docs as code starter is a small repository that shows every rule above. Download it from the site's Settings, GitHub tab (Download the starter (.zip)), or create a site from the Docs as code starter template to see it rendered.

#Formats other than plain Markdown

A connection reads plain Markdown by default. It can also read a repository written for Mintlify (mint.json or docs.json), GitBook (SUMMARY.md), ReadMe (_order.yaml per category) or Docusaurus (sidebars.js, _category_.json), or detect the format automatically. Change it under Format in the GitHub tab; saving a different format syncs the repository again and keeps pages in place by matching file paths.

When EvoHub pushes back to a repository in one of these formats, it writes that format's components and navigation where an equivalent exists. A component the format has no equivalent for is written in EvoHub syntax and listed as a warning on the push. Docusaurus sidebars.js is never written; keep it in step yourself.

#Connect a repository

You need permission to manage the site (docs:site:write), and you must be signed in as a person. You also need to be able to install a GitHub app on the repository.

The GitHub tab then shows the repository, branch, folder and format, the result of the Last sync and Last push, and any warnings for individual files. Sync now runs a sync by hand.

#What a sync does

A sync runs on every push to the connected branch that touches the folder.

• New files become pages, changed files update their pages, and the navigation follows the folders and order rules.
• A deleted file's page is unpublished and deleted.
• Snippets and API references are created and updated, but never deleted by a sync. Remove them in EvoHub.
• An empty folder makes no section.
• On a site that requires review, a sync does not publish. It opens one change request — or updates the one already open — with the pages waiting, unpublish items for removed files, and the navigation if it changed. See Review and change requests.

#Pushing edits back

With Push edits to GitHub as pull requests on, publishing in EvoHub (including merging a change request, unpublishing, deleting, rolling back) writes the live pages back to the repository:

• Commits go to a branch named evohub/<site address> and a pull request titled "Docs edits from EvoHub" is opened if none is open. Later edits are added to the same branch while the pull request is open.
• Your connected branch and the repository's default branch are never written to directly. You review and merge the pull request.
• New pages get a file in their section's folder; existing files are updated in place.

#Conflicts

If the same page changed both in EvoHub and in its file on GitHub, nothing is overwritten. The page is flagged in the navigation tree and in the editor, and the GitHub tab lists it. For each conflicting page choose:

• Keep EvoHub's — the next push replaces the file with the EvoHub version.
• Take GitHub's — the repository's file replaces the page's draft (and the live page, unless the site requires review). Your draft edits are lost.

#Versions and languages

• A site with several versions has one connection per version. Use a branch per version (main for the latest, v1 for the old one, the same folder on each) or one branch with a folder per version (docs/v2/, docs/v1/). Pushes for a version other than the default go to evohub/<site address>-<version>.
• Translations are not synced. The repository holds the site's default language; write translations in EvoHub.

#Disconnect

Disconnect in the GitHub tab removes the link between pages and files. The pages stay as they are. If the app is removed or loses access on GitHub, the connection shows as disconnected and Reconnect picks up where it left off.

#Related

• Writing pages
• Import and export
• Review and change requests