GitHub Integration

Keep your documentation in sync with your codebase by connecting your GitHub repository to Playbook. Write in markdown, collaborate through Git, and let Playbook handle the publishing.

Getting Started

First, you'll need to install the Playbook GitHub App in your organization. This gives us permission to sync your documentation.

Next up, create a site with GitHub. You will need to select the repository you want to connect to and set the root directory where your docs live (like docs/ or documentation/). This is where we'll look for your documentation files.

Once you have connected and set up your GitHub repository, your docs will begin importing. This includes all the markdown files, images, links, and other assets. This process typically takes a few minutes depending on the number of pages you have.

That's it! Your documentation will automatically update whenever changes are merged to your main branch.

Directory Structure

Place your documentation in your chosen root directory within your repository. Create folders for different sections (one level of nesting supported) and store all images in the _images directory at the root level.

Here's a recommended structure:

docs/
├── _images/              # All your images go here
│   ├── screenshots/
│   └── diagrams/
├── getting-started/      # Each folder is a section
│   ├── quickstart.md
│   ├── installation.md
│   └── configuration.md
├── guides/
│   ├── authentication.md
│   ├── deployment.md
│   └── monitoring.md
└── api-reference/       
    ├── endpoints.md
    ├── errors.md
    └── webhooks.md

Managing Your Documentation

With GitHub integration enabled, all content edits happen through your Git repository. This keeps your documentation workflow aligned with your code workflow. You maintain full control over your site's appearance and settings through the Playbook interface.

Sync and Updates

Documentation updates automatically trigger when:

• Pull requests with documentation changes merge to your main branch
• Manual sync is initiated from Settings > Integration
• Images are added to the _images directory

While content is managed through GitHub, you can customize your site directly in Playbook:

• SEO: Configure site and page SEO
• Content structure: move pages or sections around
• Custom domains: add custom domain to your site

Security

Your GitHub tokens are encrypted and securely stored. The integration uses read-only repository access to ensure your code remains secure.

Benefits of GitHub Integration

Store and manage your documentation directly in your codebase to leverage Git's powerful features. Use branches for documentation changes, collaborate through pull requests, and maintain version control. Playbook automatically handles the publishing while our AI helps you generate and improve documentation.

Best Practices

1. Keep your documentation close to your code
2. Use meaningful directory names for sections
3. Store all images in the _images directory
4. Use branches for major documentation updates
5. Take advantage of Git features like PR reviews for documentation changes
6. When creating links between documentation pages:
   • Playbook automatically resolves markdown links between pages
   • For best reliability, use root-relative paths from your documentation directory (e.g., /getting-started/quickstart.md)
   • Avoid using relative paths with ../ as these can be difficult to resolve correctly