GitHub Sync

md0 CMS keeps your content synchronized with GitHub through automatic commits and real-time updates. This guide explains how synchronization works and how to manage it.

How Sync Works

Basic Workflow

1. Edit Content: Make changes in md0 CMS editor
2. Save: Click Save button
3. Commit: md0 CMS creates a Git commit
4. Push: Changes are pushed to GitHub
5. Available: Content is immediately available in repository

Real-Time Synchronization

Every save in md0 CMS:

• Creates a new Git commit
• Pushes to your GitHub repository
• Triggers webhooks (if configured)
• Updates repository immediately

No manual Git commands needed.

Commit Management

Automatic Commits

md0 CMS generates commits automatically:

Create new post: "Getting Started with md0"
Update post: "Quick Start Guide"
Delete post: "Deprecated Tutorial"
Update media: Upload image-hero.jpg

Commit Messages

Default commit message format:

[Action] [Content Type]: "[Title]"

Examples:
Create post: "Introduction to Markdown"
Update doc: "API Reference"
Delete page: "Old Landing Page"

Customizing Commit Messages

Configure commit message templates in settings:

# Template options
create: "Add {{type}}: {{title}}"
update: "Edit {{type}}: {{title}}"
delete: "Remove {{type}}: {{title}}"
# Variables available:
# {{type}} - Collection name
# {{title}} - Content title
# {{user}} - Author name
# {{date}} - Current date

Commit Attribution

Commits are attributed to:

• Your GitHub account
• Email from GitHub profile
• Verified via OAuth token

Example commit metadata:

Author: Jane Doe <jane@example.com>
Date: Mon Jan 15 14:30:00 2024 -0500
Committer: md0 CMS <noreply@md0.io>

Branch Management

Default Branch

md0 CMS works with your default branch by default:

• Usually main or master
• Configured in repository settings
• Can be changed in md0 CMS settings

Working with Branches

Select different branch:

1. Go to Settings > Repository
2. Click "Change Branch"
3. Select from available branches
4. Content loads from new branch

Create new branch:

1. Go to Settings > Repository
2. Click "Create Branch"
3. Enter branch name
4. Branch is created from current HEAD

Branch-Based Workflows

Feature branches:

main (production)
└── feature/new-docs (work in progress)

Work in feature branch:

1. Create branch in GitHub
2. Select branch in md0 CMS
3. Make content changes
4. Create pull request in GitHub
5. Merge to main after review

Content staging:

main (production)
└── staging (preview)
    └── draft (work in progress)

Conflict Resolution

What Causes Conflicts?

Conflicts occur when:

• Same file edited in GitHub and md0 CMS
• Same file edited by multiple users
• Local changes not pushed before remote changes
• Branch merges with overlapping changes

Detecting Conflicts

md0 CMS shows conflict warnings:

• "Conflict detected" notification
• Conflict icon on affected content
• Details in conflict panel

Resolving Conflicts

Option 1: Accept remote changes

• Discard your changes
• Use version from GitHub
• Your changes are lost

Option 2: Accept local changes

• Keep your changes
• Overwrite GitHub version
• Remote changes are lost

Option 3: Manual merge

• Download both versions
• Merge manually
• Upload final version

Best practice: Review both versions before deciding.

Preventing Conflicts

1. Communicate with team about who's editing what
2. Pull latest changes before starting work
3. Save frequently to push changes quickly
4. Use feature branches for major edits
5. Enable notifications for repository activity

Sync Status

Connection Status

Check sync status in header:

• Green dot: Connected, syncing normally
• Yellow dot: Warning, connection issue
• Red dot: Disconnected, no sync
• Syncing icon: Actively syncing

Sync Indicators

On individual content items:

• Checkmark: Saved and synced
• Cloud icon: Saving in progress
• Warning: Conflict detected
• Error: Sync failed

Last Sync Time

View last sync time:

• Per content item
• In sync status panel
• Hover over sync indicator

Working Offline

Offline Editing

md0 CMS requires internet connection:

• Content loads from GitHub
• Saves push to GitHub
• No offline mode currently

For offline editing:

1. Clone repository locally
2. Edit files with text editor
3. Commit and push when online
4. Changes sync to md0 CMS

Sync After Reconnection

When connection is restored:

• md0 CMS checks for conflicts
• Local changes are synced
• Conflicts are flagged
• User resolves conflicts

Advanced Sync Features

Batch Operations

Bulk updates:

1. Select multiple items
2. Apply changes
3. Single commit for all changes

Example commit:

Bulk update: Add tags to 5 blog posts

Scheduled Publishing

Use frontmatter date for scheduling:

---
title: "Future Post"
date: 2024-12-31
published: true
---

Content is committed immediately but your SSG only publishes when date arrives.

Draft Mode

Keep drafts out of production:

Method 1: Draft folder

Collection: Published Posts
Path: content/posts/**/!(draft-)*.md

Collection: Draft Posts
Path: content/drafts/**/*.md

Method 2: Frontmatter flag

---
published: false
---

Filter in SSG based on published field.

GitHub Integration

Repository Webhooks

md0 CMS doesn't require webhooks, but they can trigger:

• Build deployments (Vercel, Netlify)
• CI/CD pipelines
• Backup processes
• Notifications

Configure in GitHub repository settings.

GitHub Actions

Trigger actions on content changes:

# .github/workflows/content-update.yml
name: Content Update
on:
  push:
    paths:
      - "content/**"
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Build site
        run: npm run build

Commit History

View full commit history:

• In GitHub repository
• With author attribution
• With timestamps
• With file diffs

md0 CMS commits are indistinguishable from manual commits.

Security and Permissions

Access Control

md0 CMS respects GitHub permissions:

• Read access: View content only
• Write access: Edit and save content
• Admin access: Manage settings

Branch Protection

If branch protection is enabled:

• md0 CMS may require pull requests
• Direct commits may be blocked
• Status checks must pass
• Reviews may be required

Workaround:

1. Create feature branch
2. Make changes in md0 CMS
3. Create PR in GitHub
4. Merge after review

Audit Trail

Track all changes:

• Git commit history
• Author attribution
• Timestamps
• File diffs

Export commit history:

git log --all --pretty=format:"%h %an %ar %s"

Troubleshooting

Content Not Syncing

Check:

1. Internet connection is active
2. GitHub connection is authorized
3. Repository has write access
4. No branch protection conflicts
5. No file permission errors

Solutions:

• Reconnect GitHub account
• Refresh page and try again
• Check GitHub status page
• Contact support

Sync Taking Too Long

Possible causes:

• Large file uploads
• Slow internet connection
• GitHub API rate limits
• Many simultaneous changes

Solutions:

• Wait for sync to complete
• Upload smaller files
• Try again later
• Contact support if persistent

Conflicts Keep Appearing

Solutions:

1. Coordinate with team members
2. Use feature branches
3. Pull changes before editing
4. Enable conflict notifications
5. Establish content workflow

Changes Not Appearing on Site

Check:

1. Commits are in GitHub (check repository)
2. Build process completed
3. Cache is cleared
4. Correct branch deployed
5. No build errors

Remember: md0 CMS pushes to GitHub. Your SSG must rebuild to show changes.

Best Practices

Team Workflows

Establish conventions:

1. Who edits what content
2. When to use feature branches
3. How to handle conflicts
4. When to create pull requests

Communication:

• Notify team before major edits
• Use GitHub issues for planning
• Comment on pull requests
• Document changes in commits

Content Organization

1. Use collections to separate content types
2. Use folders for logical grouping
3. Use branches for different stages
4. Use tags/categories for taxonomy

Commit Hygiene

1. Save frequently but purposefully
2. Review changes before saving
3. Write clear commit messages
4. Don't commit broken content
5. Test before committing

Next Steps

• Markdown Editing - Create and edit content
• Media Management - Upload and manage media
• Integration Guides - Use content in your site

Related Documentation

• Connect Repository
• Create Collections
• Quick Start