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
- Edit Content: Make changes in md0 CMS editor
- Save: Click Save button
- Commit: md0 CMS creates a Git commit
- Push: Changes are pushed to GitHub
- 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
mainormaster - Configured in repository settings
- Can be changed in md0 CMS settings
Working with Branches
Select different branch:
- Go to Settings > Repository
- Click "Change Branch"
- Select from available branches
- Content loads from new branch
Create new branch:
- Go to Settings > Repository
- Click "Create Branch"
- Enter branch name
- Branch is created from current HEAD
Branch-Based Workflows
Feature branches:
main (production)
└── feature/new-docs (work in progress)
Work in feature branch:
- Create branch in GitHub
- Select branch in md0 CMS
- Make content changes
- Create pull request in GitHub
- 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
- Communicate with team about who's editing what
- Pull latest changes before starting work
- Save frequently to push changes quickly
- Use feature branches for major edits
- 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:
- Clone repository locally
- Edit files with text editor
- Commit and push when online
- 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:
- Select multiple items
- Apply changes
- 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:
- Create feature branch
- Make changes in md0 CMS
- Create PR in GitHub
- 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:
- Internet connection is active
- GitHub connection is authorized
- Repository has write access
- No branch protection conflicts
- 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:
- Coordinate with team members
- Use feature branches
- Pull changes before editing
- Enable conflict notifications
- Establish content workflow
Changes Not Appearing on Site
Check:
- Commits are in GitHub (check repository)
- Build process completed
- Cache is cleared
- Correct branch deployed
- No build errors
Remember: md0 CMS pushes to GitHub. Your SSG must rebuild to show changes.
Best Practices
Team Workflows
Establish conventions:
- Who edits what content
- When to use feature branches
- How to handle conflicts
- 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
- Use collections to separate content types
- Use folders for logical grouping
- Use branches for different stages
- Use tags/categories for taxonomy
Commit Hygiene
- Save frequently but purposefully
- Review changes before saving
- Write clear commit messages
- Don't commit broken content
- Test before committing
Next Steps
- Markdown Editing - Create and edit content
- Media Management - Upload and manage media
- Integration Guides - Use content in your site