Documentation

GitHub sync

Keep your markdown in a GitHub repository and publish on every push.

On this page 6

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.

Note

If you're not the team's owner, ask them to connect GitHub before you set up a repository.

Create a GitHub site

  1. Click New site and choose Sync from a GitHub repo.
  2. Pick the Repository and the Production branch.
  3. Set the Docs directory: the folder that holds your markdown, usually docs/.
  4. 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 .md file inside the docs directory, including subfolders. Folders become sections, and _index.md is 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:

markdown

---

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:

  1. In the repository, go to Settings → Webhooks → Add webhook.
  2. Paste the Payload URL shown on the site's Settings tab.
  3. Set the content type to application/json.
  4. Click Reveal secret on the Settings tab and paste it into Secret.
  5. 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