md0 CMS uses GitHub OAuth to securely connect to your repositories. This guide explains the connection process, permissions, and repository management.
GitHub OAuth Connection
Initial Connection
- Click "Connect GitHub" on the md0 CMS homepage
- You'll be redirected to GitHub's authorization page
- Review the permissions md0 CMS requests
- Click "Authorize md0 CMS"
- You'll be redirected back to md0 CMS
Required Permissions
md0 CMS requests the following GitHub permissions:
- Read repository contents: To display your files and collections
- Write repository contents: To save content changes
- Read repository metadata: To list repositories and branches
- User email: To attribute commits to you
These permissions allow md0 CMS to function as a content editor while keeping your content in GitHub.
Selecting a Repository
After authorization, you'll see a list of your accessible repositories.
Repository Requirements
- Must be a public repository (private repo support coming soon)
- You must have write access to the repository
- Repository should contain markdown files (or be ready for them)
Selecting Your Repository
- Browse or search your repositories
- Click on the repository you want to manage
- md0 CMS will analyze the repository structure
- You'll be taken to the collection setup screen
Repository Settings
Once connected, you can configure repository-specific settings.
Branch Selection
By default, md0 CMS works with your default branch (usually main or master).
To change branches:
- Go to Settings > Repository
- Select "Change Branch"
- Choose from available branches
- Content will load from the selected branch
Branch Protection
If your repository has branch protection rules:
- md0 CMS respects pull request requirements
- Changes may require review before merging
- Status checks must pass before commits
Multiple Repositories
You can connect multiple repositories to md0 CMS.
Adding Additional Repositories
- Click your profile icon
- Select "Add Repository"
- Authorize access if needed
- Select the new repository
Switching Between Repositories
Use the repository switcher in the top navigation to move between connected repositories.
Repository Structure
md0 CMS works with any repository structure. Common patterns:
Blog Structure
my-blog/
├── content/
│ ├── posts/
│ │ ├── 2024-01-01-first-post.md
│ │ └── 2024-01-15-second-post.md
│ └── pages/
│ ├── about.md
│ └── contact.md
└── public/
└── images/
Documentation Structure
my-docs/
├── docs/
│ ├── getting-started/
│ │ ├── installation.md
│ │ └── quick-start.md
│ ├── guides/
│ └── api/
└── static/
Multi-Site Structure
monorepo/
├── blog/
│ └── content/
├── docs/
│ └── pages/
└── marketing/
└── content/
md0 CMS collections use path patterns to target specific directories within any structure.
Security and Privacy
Data Security
- OAuth tokens are encrypted and stored securely
- Repository access is scoped to only what you authorize
- No data storage: Content remains in your GitHub repository
- Secure connections: All communication uses HTTPS
Revoking Access
To revoke md0 CMS access to your GitHub account:
- Go to GitHub Settings > Applications
- Find "md0 CMS" in Authorized OAuth Apps
- Click "Revoke"
Alternatively, disconnect from md0 CMS settings.
Audit Trail
All changes made through md0 CMS appear in your GitHub commit history:
- Commits are attributed to your GitHub user
- Commit messages indicate the action taken
- Full Git history is preserved
Connection Management
Reconnecting
If your connection expires or is revoked:
- You'll see a "Reconnect GitHub" prompt
- Click to reauthorize
- Your settings and collections are preserved
Connection Status
Check your connection status:
- Green indicator: Connected and active
- Yellow indicator: Connection warning (token expiring)
- Red indicator: Disconnected (reauthorization needed)
Troubleshooting
Can't See My Repository
Possible causes:
- Repository is private (not yet supported)
- You don't have write access
- Repository is archived
Solutions:
- Make repository public
- Request write access from repository owner
- Unarchive the repository
Authorization Failed
Common issues:
- GitHub is down or experiencing issues
- Browser blocking third-party cookies
- Ad blocker interfering with OAuth flow
Solutions:
- Try again in a few minutes
- Allow cookies for md0.io and github.com
- Temporarily disable ad blocker
- Try a different browser
Repository Not Loading
Possible causes:
- Very large repository (thousands of files)
- Network connectivity issues
- GitHub API rate limits
Solutions:
- Wait a moment and refresh
- Check your internet connection
- Contact support if issue persists
Best Practices
Repository Organization
- Use clear, consistent folder structures
- Keep content separate from code
- Use descriptive file names
- Follow a naming convention
Branch Strategy
- Use
mainormasterfor production content - Create feature branches for major content updates
- Use branch protection for team workflows
- Merge via pull requests for review
Commit Messages
md0 CMS generates commit messages automatically:
Create new post: "Getting Started with md0 CMS"
Update post: "Quick Start Guide"
Delete post: "Deprecated Tutorial"
You can customize commit message templates in settings.
Next Steps
Once your repository is connected:
- Create Collections to organize content
- Define Schemas for frontmatter validation
- Start Editing your content
Related Documentation
- GitHub Sync - How synchronization works
- Collection Patterns - Path pattern configuration
- Media Management - Managing repository assets