A GitHub site publishes the markdown in a folder of your repository. Every push to your production branch updates the live site.
Connect GitHub
Your team's owner connects their GitHub account, either from Settings → Profile → Connect GitHub or when the new-site wizard asks. Maddie Docs uses the owner's connection to read repositories, including private ones, and to install webhooks.
If you're not the team's owner, ask them to connect GitHub before you set up a repository.
Create a GitHub site
- Click New site and choose Sync from a GitHub repo.
- Pick the Repository and the Production branch.
- Set the Docs directory: the folder that holds your markdown, usually
docs/. - Choose an address and click Create site.
To change the repository, branch or folder later, go to the site's Settings and click Configure beside Repository.
What gets synced
- Every
.mdfile inside the docs directory, including subfolders. Folders become sections, and_index.mdis a section's landing page. - The site mirrors the folder exactly: files you delete from the repository are removed from the site.
- Images and other files aren't synced. Host them elsewhere and link to them.
Write front matter at the top of each file to set its title, order and more:
---
title: Installation
description: Install the app and sign in.
order: 2
tags: [setup]
---
The fields you can set match the editor's page settings:
| Field | Does |
|---|---|
title |
The page's title |
description |
Shown in search results and link previews |
order |
Its position in the sidebar; lower comes first |
slug |
A custom URL for the page |
tags |
A list of tags |
hidden |
true hides it from the sidebar, search and the sitemap |
search |
false keeps it out of search |
search_rank |
Lifts (above 1) or lowers (below 1) it in search |
group, badge, icon |
Sidebar group, badge and icon |
author |
Credited on the page |
image |
The image shown when the page is shared |
redirect |
Sends visitors to another page or site |
Everything the editor can write works in your files too, including callouts, tabs, diagrams and maths. See Writing and formatting and Advanced content.
When syncs happen
- On every push to the production branch. Pushes to other branches are ignored.
- When you click Resync on the site's page.
Each sync appears under Deployments with how many files were written and removed.
The webhook
Maddie Docs installs a webhook on your repository automatically. The site's Settings tab shows Webhook installed automatically with a Reinstall webhook button.
If it couldn't be installed, for example because the owner can't manage the repository's webhooks, click Retry automatic setup or add it yourself:
- In the repository, go to Settings → Webhooks → Add webhook.
- Paste the Payload URL shown on the site's Settings tab.
- Set the content type to
application/json. - Click Reveal secret on the Settings tab and paste it into Secret.
- Choose Just the push event and save.
When a sync fails
The reason is shown in the site's Deployments tab:
| Message | Fix |
|---|---|
| GitHub access was revoked | The owner reconnects GitHub with Reconnect GitHub on the Settings tab |
| Team owner has no linked GitHub account | The owner connects GitHub |
| GitHub ref … was not found | Check the production branch still exists |
| docs_path … was not found | Check the docs directory exists on that branch |