Branches

Guidebook Cloud supports branch-based documentation, allowing you to preview changes before merging and maintain documentation for different versions.

Branch URLs

Each branch has its own URL:

https://guidebook.dev/{org-slug}/{repo-slug}@{branch-name}/

Examples

Default Branch

The default branch is shown when accessing the repository URL without a branch specifier.

Setting the Default Branch

1. Go to Repository Settings
2. Under Repository Settings, select the Default Branch
3. Click Save Changes

The default branch is initially set to the GitHub repository's default branch (usually main or master).

Branch Previews

Branch previews allow you to view documentation changes before merging.

Automatic Branch Builds

When auto-deploy is configured:

• Pushing to a branch triggers a build
• The branch becomes accessible at its branch URL
• Useful for reviewing documentation changes in pull requests

Branch Patterns

Configure which branches trigger builds:

• Default branch only - Only the main branch
• All branches - Every push triggers a build
• Custom patterns - Use glob patterns like main, release/*, docs-*

Viewing Branches

To see all branches for a repository:

1. Go to the repository page
2. The branches section shows all built branches
3. Click a branch to view its documentation

Branch Deletion

When a branch is deleted from GitHub:

• Guidebook Cloud receives a webhook notification
• The branch is automatically removed
• Built content is deleted

Manual Branch Cleanup

If a branch was not automatically removed:

1. Branches sync when receiving GitHub events
2. Pushing to any branch in the repository triggers a sync
3. Old branches are cleaned up during the sync process

Build Status

Each branch shows its build status:

Build Logs

To view build logs:

1. Go to the repository page
2. Find the branch in the list
3. Click View Log or the status indicator

Use Cases

Version Documentation

Maintain documentation for different product versions:

v1.0 -> https://guidebook.dev/acme/docs@v1.0/
v2.0 -> https://guidebook.dev/acme/docs@v2.0/
main -> https://guidebook.dev/acme/docs/ (latest)

Feature Preview

Preview documentation changes in pull requests:

1. Push changes to a feature branch
2. Access the branch URL to review
3. Merge to main when ready

Staging Environment

Use branches as staging environments:

develop -> https://guidebook.dev/acme/docs@develop/ (staging)
main    -> https://guidebook.dev/acme/docs/ (production)