Syncing Documents to GitHub

Once GitHub is connected and a repository is selected, you can sync documents to keep them in version control.

Prerequisites

✅ GitHub connected
✅ Repository selected
✅ Document ready to sync

How to Sync a Document

Manual Sync

Navigate to Dashboard > Documents and open the document you want to sync
Find the GitHub card in the sidebar
Click Sync to GitHub
The button shows a spinner while in flight, and a success toast appears when the commit is created

Auto-sync on Save

You can opt a document into automatic syncing on every save:

Open the document and find the GitHub card in the sidebar
Toggle Auto-sync on save on
Every successful save now also pushes a commit to GitHub silently

The toggle is per-document and only appears when a repository is configured for the company. Auto-sync is silent — it doesn't show a toast on no-op commits — so it doesn't get in the way while you're iterating. The manual Sync button still works at any time.

Confirmation

After a sync, the GitHub sidebar card always shows:

A status row (Synced X ago or Never synced)
A View file link to the file in your repository
A scrollable list of recent linked PRs and commits (fixed height — the card no longer grows after repeated syncs)

What Gets Synced

Document Content

Your document is converted to a Markdown file with YAML front matter:

---
title: Use PostgreSQL for Database
type: ADR
category: ACCEPTED
author: John Doe
created: 2026-02-15
updated: 2026-02-17
---

# Use PostgreSQL for Database

## Context
...

## Decision
...

## Consequences
...

The HTML → Markdown conversion uses turndown with the GitHub-Flavored Markdown plugin, so tables, task lists, nested lists, strikethrough, and images with width/height all round-trip cleanly.

Diagrams

Diagrams render natively on GitHub:

Diagram type	How it's synced
Mermaid	Emitted as a ```mermaid fenced code block — GitHub renders these natively
Draw.io	Exported SVG is committed as a sibling asset (e.g. `docs/adr/<slug>-drawio-1.svg`) and the block is replaced with a Markdown image reference. Falls back to an ```xml `mxfile` fence when no SVG payload is available.
Excalidraw	Pre-rendered to SVG in the browser, posted alongside the sync request, and committed as a sibling asset, then referenced as a Markdown image.

The Markdown file and every generated SVG are written in a single atomic commit via the GitHub Git Data API (blob → tree → commit → ref). Reviewers always see the prose change and the diagrams change together — no half-applied syncs.

Metadata (Frontmatter)

Field	Description
title	Document title
type	ADR, RFC, or DESIGN_DOC
category	IN_PROGRESS, ACCEPTED, or CLOSED
author	Document creator
created	Creation date
updated	Last update date

File Location

Documents are synced to paths based on type:

Type	Path
ADR	`docs/adr/[slug].md`
RFC	`docs/rfc/[slug].md`
Design Doc	`docs/design-doc/[slug].md`

Sync Behavior

First Sync

Creates the file in the repository
Creates directories if needed
Commits with a descriptive message

Subsequent Syncs

Updates the existing file
Creates a new commit
Shows the changes in Git history

Commit Messages

ArchDoc creates descriptive commit messages:

docs: Add ADR - Use PostgreSQL for Database

Synced from ArchDoc by john.doe@company.com

When to Sync

Manual vs. Auto-sync

Most teams use a mix:

Manual sync for milestone commits — after major edits, when a document is finalized, or before a release. Gives you control over when each commit is created.
Auto-sync on save for living documents that should always mirror what's in ArchDoc. Toggle it on per-document so save-driven commits flow continuously to GitHub.

Recommended Workflow

Draft in ArchDoc (frequent saves)
Review with sign-offs
Sync when accepted — or enable Auto-sync on save if the document should always be mirrored
Update and re-sync as needed