Git Content Architecture

This document explains the design decisions behind the Git-based content system and how it works under the hood.

Why Git for Content?

The platform uses Git for blog content instead of a traditional CMS. This architectural choice provides several advantages.

Version Control Built In

Every change to your content is tracked automatically. You can see who changed what and when. If something breaks, you can roll back to a previous version. This is standard practice in software development, but rare in content management.

Collaboration Without Complexity

Multiple team members can work on content simultaneously. Git’s branching model means writers can work independently and merge changes when ready. No need for complex permission systems or locking mechanisms.

Separation of Content and Platform

Your content lives in your repository, not locked in our database. If you ever decide to move to a different platform, your content is already in a portable format (MDX). You own it completely.

Preview Before Publishing

Because Git supports branches, you can maintain a staging branch to preview changes before publishing to production. This is built into Git rather than being a platform feature we have to maintain.

How Sync Works

Understanding the sync process helps you troubleshoot issues and plan your content workflow.

Sync Triggers

Content syncs from your repository in three scenarios:

Manual Sync — When you click “Sync Now” in the admin panel, the system immediately fetches the latest content from your configured branch.

Site Deploys — Every time the site rebuilds (typically after configuration changes), content is pulled automatically.

Scheduled Sync — If enabled, a daily background job checks for new content and syncs it.

The Sync Process

When a sync runs:

1. Clone/Pull — The system clones your repository (first time) or pulls the latest changes (subsequent syncs)

2. Parse MDX — Each .mdx file in your content path is parsed to extract frontmatter and content

3. Validate — Posts are checked for required fields (title, date). Missing fields generate warnings but don’t fail the sync

4. Filter — If multiple brokerages share a repository, posts are filtered by brokerage metadata

5. Import — Valid posts are imported into the database and associated with your brokerage

6. Asset Handling — Images in the assets/ directory are copied to the site’s public assets

What Gets Synced

The system syncs:

• All .mdx files in the configured content path
• Images referenced in frontmatter or content
• Metadata changes (title, tags, author updates)

The system ignores:

• Files without .mdx extension
• Draft posts (where draft: true in frontmatter)
• Files outside the content path
• Hidden files and directories (starting with .)

Note

Deletions in your repository are reflected during sync. If you delete a post file, it disappears from the website on the next sync.

MDX Format

MDX is Markdown with the ability to embed React components. For blog content, this provides flexibility most platforms don’t offer.

Basic Markdown

Standard Markdown works as expected:

# Heading
## Subheading

**Bold text** and *italic text*

- Bullet lists
- Work as normal

[Links](https://example.com) work too

Why MDX Over Plain Markdown

MDX allows custom components in content:

<Callout type="tip">
  This is a special callout box with custom styling
</Callout>

This means writers can use platform-specific features without learning a proprietary system. If you move platforms, you can either keep the components or replace them with standard Markdown.

Frontmatter Schema

Frontmatter is YAML between --- markers. The platform expects certain fields:

Required:

• title (string) — Post title
• date (YYYY-MM-DD) — Publication date

Optional:

• description (string) — SEO meta description
• author (string) — Author name
• image (string) — Featured image path
• tags (array) — Category tags
• draft (boolean) — Hide from public

Tip

The schema is intentionally minimal. We only require what’s necessary for the platform to function. Everything else is optional.

Multi-Brokerage Repositories

Multiple brokerages can share a single content repository. This is useful for franchise networks or multi-office operations.

How Filtering Works

Posts can include brokerage-specific metadata in frontmatter:

---
title: "Market Update"
date: 2024-01-15
brokerage: "elevate-idaho"
---

During sync, the platform filters posts to only import those matching the brokerage identifier. Posts without a brokerage field are imported by all brokerages sharing that repository.

Benefits

Shared Content — Franchise networks can maintain corporate blog content in one place

Brokerage-Specific Posts — Individual offices can add their own content to the same repository

Simplified Management — One repository to secure, backup, and manage rather than multiple per brokerage

Authentication Security

The platform supports two authentication methods, each with different security characteristics.

SSH Keys

SSH keys are the recommended approach for production use:

Pros:

• No expiration (tokens often expire)
• Can be scoped to a single repository (deploy keys)
• Read-only access can be enforced

Cons:

• Slightly more complex initial setup
• Key management requires care

Access Tokens

Personal access tokens are simpler but have tradeoffs:

Pros:

• Easy to generate and revoke
• Work with HTTPS URLs

Cons:

• Expire and need renewal
• Often have broader permissions than necessary
• Can be accidentally exposed in logs

Caution

Never commit access tokens or SSH private keys to your content repository. They should only exist in the platform’s secure configuration storage.

Performance Considerations

The sync system is designed to handle content repositories of varying sizes efficiently.

Incremental Pulls

After the initial clone, syncs only pull changes since the last sync. This means adding a single new post doesn’t require re-downloading the entire repository.

Caching

Parsed MDX and processed images are cached. If a file hasn’t changed between syncs (determined by Git commit hash), it’s not re-parsed.

Sync Duration

For most brokerages:

• Initial sync: 10-30 seconds
• Subsequent syncs: 2-5 seconds (with new content)
• Subsequent syncs: < 1 second (no changes)

Large repositories (hundreds of posts) may take longer on initial sync but remain fast for incremental updates.

Design Philosophy

The Git content architecture reflects a specific philosophy about content ownership and portability.

Your Content, Your Repository — We don’t lock your content in our database. It lives in your Git repository where you control it.

Standard Formats — MDX is an open format. You’re not learning a proprietary system that only works with our platform.

No Vendor Lock-In — If you leave, your content leaves with you. No export process needed because it was never locked in.

Leverage Existing Tools — Git’s branching, merging, and history are powerful. Rather than rebuild those features poorly, we use Git as it was designed.

This approach trades some convenience (no in-platform content editor) for ownership and portability. It’s a deliberate choice that aligns with giving brokerages control over their data.