Managing Notion Pages

Learn how mdsync.app creates and manages Notion pages, and how your GitHub structure maps to Notion.

Page Structure Mapping

mdsync.app uses a two-phase sync process to perfectly mirror your GitHub structure:

• GitHub Folders → Notion pages (with folder name as page title)
• README.md files → Page content (or child pages for root README)
• Other .md files → Child pages with their content
• Images → Uploaded to Notion and embedded in pages
• Folder hierarchy → Preserved as parent-child page relationships

Sync Process

Phase 1: Structure Creation

mdsync.app first creates the page structure:

1. Creates all folder pages as Notion pages
2. Creates pages for all markdown files
3. Establishes parent-child relationships
4. Sets page titles based on folder/file names

Phase 2: Content Population

Then it populates the content:

1. Converts markdown to Notion blocks
2. Uploads images to Notion
3. Updates page content
4. Handles orphaned pages (files deleted in GitHub)

Supported Markdown Features

mdsync.app supports comprehensive markdown formatting:

• Headers (H1-H6) → Notion headings
• Bold and italic text → Notion formatting
• Code blocks with syntax highlighting → Notion code blocks
• Inline code → Notion inline code
• Lists (ordered and unordered) → Notion lists
• Links → Notion links
• Images → Uploaded and embedded in Notion
• Tables → Notion tables
• Horizontal rules → Notion dividers
• Blockquotes → Notion callouts

Content Updates

When you update files in GitHub:

• ✅ Content is automatically updated in Notion (if webhooks enabled)
• ✅ Formatting is preserved and converted to Notion blocks
• ✅ Images are re-uploaded if changed
• ✅ Links are preserved and updated
• ✅ New files create new pages
• ✅ Deleted files archive their Notion pages

Manual Edits in Notion

• ⚠️ Manual edits may be overwritten on the next sync
• ⚠️ It's recommended to make changes in GitHub instead
• ✅ Use Notion comments for team collaboration (comments are preserved)
• ✅ Use Notion discussions for feedback (not overwritten)

Best Practices

Repository Structure

• Keep README.md files focused and clear
• Use consistent folder naming conventions
• Organize images in a dedicated folder (e.g., /images)
• Use relative links between markdown files

Content Guidelines

• Use clear, descriptive file and folder names
• Keep markdown files well-formatted
• Use proper heading hierarchy (H1 → H2 → H3)
• Optimize images before committing (smaller files = faster syncs)

Notion Collaboration

• Use Notion comments for team discussions
• Don't manually restructure pages (changes should come from GitHub)
• Share Notion pages with your team for easy access
• Use Notion's built-in collaboration features

Troubleshooting

• Check sync status in the dashboard
• Review sync logs for errors
• Ensure webhooks are enabled (Starter/Pro plans)
• Manually trigger a sync if needed

• Verify image paths are correct in markdown
• Check that images are committed to the repository
• Review sync logs for image upload errors
• Ensure you haven't exceeded your plan's image limit