GitHub Sync
Automatic version control and synchronization with GitHub
Sleeve's GitHub integration provides version control and synchronization with your repositories, keeping your documentation in sync with your codebase.
Why GitHub Integration?
Version Control
Every change is tracked with full Git history
Automatic Backups
Your docs are safely stored in GitHub repositories
Code Co-location
Keep documentation close to your code
Collaboration
Use familiar Git workflows for documentation
GitHub integration is optional but recommended. You can use Sleeve without GitHub integration, but you won't be able to bring in projects/static sites and manage those docs as well.
Setting Up GitHub Integration
Step 1: Create a Personal Access Token
Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
Click "Generate new token" and give it a descriptive name (e.g., "Sleeve Integration")
Choose an expiration period or select "No expiration" for continuous access
Select the repositories you want to sync:
- All repositories: Full access to all your repos
- Select repositories: Choose specific repos
Set these repository permissions:
Contents: Read and write
Pull requests: Read and write
These permissions allow Sleeve to read docs from GitHub and push changes back.
Click "Generate token" and copy it immediately (you won't be able to see it again)
Step 2: Connect GitHub to Sleeve
In your Sleeve workspace, click the Settings icon in the top-right corner
Select "Integrations" from the sidebar
Click "Add Integration" and choose GitHub
Paste your personal access token and click "Connect"
Sleeve will verify the token and show you which repositories are accessible
Your GitHub account is now connected! You can now link repositories to your spaces.
Linking Repositories to Spaces
Once GitHub is connected, you can link specific repositories to your spaces for automatic synchronization.
Adding a Repository
Go to the space where you want to add a repository
Click the "Add Repository" button
Choose a repository from the dropdown list (shows all repos you have access to)
Select the branch to sync from:
- main: Default production branch
- develop: Development branch
- docs: Dedicated documentation branch
- Custom: Any other branch name
Sleeve will bring over all documentation files from the repository. You don't select a specific path - it imports all docs.
Sync Behavior
Currently, sync is manual only - you have to press the sync buttons. Sleeve will intelligently compare new information and bring it over while maintaining version control. Automated syncing is coming soon.
How Syncing Works
Pull Request Creation
Sleeve creates pull requests back to the branch you were working on:
Version History
Every change is tracked with full version history:
Click the "History" button in any document to see all versions
Select two versions to see a side-by-side diff of changes
Roll back to any previous version if needed
Branch Management
Working with Branches
You can edit docs from any branch and create pull requests back to that branch. Other branches can be accessed in the repos view of the sidebar.
Documentation Structure
docs.json Configuration
Having docs.json in the docs folder of your repository will automatically bring the organized structure. Here's how to organize it:
{
"title": "My Documentation",
"pages": [
"index",
"getting-started",
"api-reference",
"troubleshooting"
]
}{
"title": "API Documentation",
"pages": [
"index",
{
"title": "Getting Started",
"pages": [
"installation",
"quickstart",
"examples"
]
},
{
"title": "API Reference",
"pages": [
"authentication",
"endpoints",
"errors"
]
}
]
}File Format Support
Sleeve imports these file formats:
| Format | Extension | Support |
|---|---|---|
| Markdown | .md | ✅ Full support |
| MDX | .mdx | ✅ Full support with components |
| MDC | .mdc | ✅ Full support |
For best results, use .mdx files to take advantage of Sleeve's custom components in both the editor and GitHub.
Troubleshooting
Best Practices
Dedicated Docs Folder
Keep docs in a /docs folder for cleaner organization
Use Frontmatter
Add title and description in frontmatter for better metadata
Meaningful Names
Use descriptive filenames (e.g., getting-started.md not doc1.md)
Regular Commits
Commit frequently with clear messages
With GitHub sync, your documentation stays synchronized, version-controlled, and backed up automatically!