Creating Your First Sync

Learn how to set up a synchronization between a GitHub repository and a Notion page using our step-by-step wizard.

Prerequisites

• ✅ Google account (for authentication)
• ✅ GitHub account connected in mdsync.app
• ✅ Notion account connected in mdsync.app
• ✅ A GitHub repository with markdown files
• ✅ A Notion page (or you can create one during setup)
• ✅ Available sync slot (check your plan limits)

Step-by-Step Wizard

Step 1: Open the Wizard

Click the "Add Synchronization" button in your dashboard. The wizard will check your plan limits first.

Step 2: Select Repository

• Browse your GitHub repositories in the dropdown
• Select the repository you want to sync
• The wizard will fetch the repository structure

Step 3: Choose Folder Path

• Root folder: Use "/" to sync the entire repository
• Specific folder: Enter a path like "/docs" or "/documentation"
• You can browse the folder structure to see what's available
• Select the branch to sync from (default: "main")

Step 4: Select Notion Destination

• Browse your Notion pages in the dropdown
• Select an existing page as the destination
• Or click "Create New Page" to create a page during setup
• This page will become the parent for all synced content

Step 5: Configure Webhooks (Starter & Pro Only)

• Automatic webhooks: Enable to auto-sync on every GitHub push
• Manual sync only: Available on Free plan (webhooks disabled)
• Webhooks are automatically configured when you enable them

Step 6: Review and Confirm

• Review all your settings
• Check the summary of what will be synced
• Click "Create Synchronization"

What Happens During Sync?

The sync process has two phases:

1. Phase 1 - Structure Creation: Creates Notion pages for all folders and files, mirroring your GitHub structure
2. Phase 2 - Content Population: Populates all pages with markdown content, converts images, and updates existing pages

Sync Behavior

• Folders → Become Notion pages
• README.md files → Become page content (or child pages for root README)
• Other .md files → Become child pages with their content
• Images → Uploaded to Notion and referenced in pages
• Structure → Perfectly mirrors your GitHub folder hierarchy

After Sync Completes

• View sync status in the dashboard
• Check sync logs for any errors
• Test by making a change in GitHub and syncing again
• Enable/disable syncs as needed