Setup Git-Based Blog

This guide shows you how to connect a Git repository for blog content. It assumes you’re comfortable with Git and version control.

Prerequisites

• Git repository (GitHub, GitLab, Bitbucket, or self-hosted)
• Repository containing MDX files in a posts/ directory
• Access credentials (SSH key or access token for private repos)

Repository Structure

Your repository should follow this layout:

your-repo/
├── posts/              # MDX blog posts
│   ├── post-1.mdx
│   └── post-2.mdx
└── assets/
    └── images/         # Post images

Configure in Admin

Note

Go to Brokerage Settings → Content tab in the admin dashboard.

Basic Settings

1. Git Repository URL — Enter your repository URL

   • HTTPS: https://github.com/your-org/blog-content.git
   • SSH: git@github.com:your-org/blog-content.git

2. Branch — Specify the branch to sync from (usually main)

3. Content Path — Directory containing posts (default: posts)

4. Enable Content Sync — Toggle on to enable automatic syncing during builds

Authentication

Public Repository

No authentication needed. Use the HTTPS URL and leave authentication fields empty.

Access Token

For private repositories using HTTPS:

1. Generate a token with read access:

   • GitHub: Settings → Developer settings → Personal access tokens → Fine-grained tokens
   • GitLab: Preferences → Access Tokens
   • Bitbucket: Personal settings → App passwords

2. Paste the token in the Access Token field

3. Select Access Token as the authentication method

SSH Key

For SSH authentication:

1. Generate a deploy key:

   ssh-keygen -t ed25519 -C "blog-content-deploy" -f ~/.ssh/blog_deploy

2. Add the public key (blog_deploy.pub) to your repository as a deploy key:

   • GitHub: Repo Settings → Deploy keys → Add deploy key (read-only)
   • GitLab: Repo Settings → Repository → Deploy keys
   • Bitbucket: Repo Settings → Access keys

3. Paste the private key contents into the SSH Private Key field

4. Select SSH Key as the authentication method

Test the Connection

1. Click Save to store your configuration

2. Click Sync Now to test the connection

3. Check the sync status:

   • Success: Shows last synced time and commit hash
   • Error: Review error message and fix authentication/URL issues

Sync Behavior

Content syncs at these times:

• Manual: Click “Sync Now” in the admin panel
• Automatic: During each site build/deploy
• Scheduled: Daily sync (if enabled in platform settings)

Caution

Changes in your repository don’t appear immediately. They sync during the next build or manual sync.

Troubleshooting

Authentication Failed

• Verify token/key has read access
• Check if token has expired
• Confirm repository URL is correct
• For SSH, ensure private key matches public key added to repo

Branch Not Found

• Confirm branch name exists (check for main vs master)
• Verify spelling and case sensitivity

No Posts Found

• Ensure MDX files are in the configured content path
• Verify files have .mdx extension (not .md)
• Check frontmatter syntax is valid YAML

Invalid Frontmatter

Posts must have:

• title field
• date field in YYYY-MM-DD format

Optional but recommended:

• description for SEO
• author for attribution
• image for featured image
• tags for categorization

Best Practices

Use meaningful commit messages — Help your team understand content changes

Test in staging branch — Preview changes before publishing to main

Optimize images before committing — Compress to < 200KB for faster loading

Regular syncs — Manually sync after pushing changes to see them reflected quickly

Monitor sync status — Check the admin panel for warnings about missing frontmatter or sync errors