GitHub-Hosted Websites: How It Works — Own Your Content Forever

Most website platforms store your content in their database. If you stop paying, your content disappears. If you want to migrate, you’re stuck exporting a fraction of what you built. And your revision history? Gone.

We think that’s backwards. Your content should belong to you — every page, every edit, every revision. That’s why we built a website service where your entire site lives in your own GitHub repository, hosted for free on GitHub Pages.

This guide explains exactly how it works, from the technical architecture to the day-to-day editing experience.

The Problem With Traditional CMS Platforms

WordPress, Squarespace, Wix, and similar platforms all share the same model: your content lives in their database, on their servers. You’re renting access to your own words.

This creates three problems:

Vendor lock-in — migrating away means losing formatting, structure, and revision history
Ongoing hosting costs — you pay £10–50/month just to keep your site online, even if nothing changes
Security maintenance — databases need patching, plugins need updating, and you’re one missed update away from a vulnerability

Static sites hosted on GitHub solve all three.

The Architecture

Here’s how our GitHub-hosted website service works end-to-end:

flowchart LR
    User([You])
    SystemDox[SystemDox App]
    Sync[GitHub Sync API]
    Repo[(Your GitHub Repo)]
    Actions[GitHub Actions]
    Pages([GitHub Pages])
    Domain([yourdomain.com])

    User -->|Create & edit pages| SystemDox
    SystemDox -->|Auto-sync on save| Sync
    Sync -->|Commit markdown files| Repo
    Repo -->|Trigger build| Actions
    Actions -->|Deploy static HTML| Pages
    Pages -->|Custom domain| Domain

Every component in this pipeline is either free or included in your SystemDox subscription. There are no hidden infrastructure costs.

Step 1: We Build Your Site Template

When you sign up, we design and build a professional website template in a GitHub repository under your account (or ours, linked to yours — your choice). This template includes:

A pre-configured static site generator (Astro) that turns markdown files into beautiful HTML pages
Your brand — colours, fonts, logo, and layout customised to your business
A GitHub Actions workflow that automatically rebuilds your site whenever content changes
SEO foundations — meta tags, JSON-LD structured data, sitemap, and robots.txt

The template is a real codebase, not a drag-and-drop theme. It’s built with the same tools and standards we use for our own sites.

What’s in the repository

your-website/
├── src/
│   ├── pages/           # Your website pages (markdown)
│   │   ├── index.md     # Homepage
│   │   ├── about.md     # About page
│   │   ├── services.md  # Services page
│   │   └── blog/        # Blog posts
│   │       ├── first-post.md
│   │       └── second-post.md
│   ├── layouts/         # Page templates (we maintain these)
│   └── components/      # Reusable UI blocks
├── public/              # Static assets (images, favicon)
├── .github/
│   └── workflows/
│       └── deploy.yml   # Auto-deploy on every push
└── astro.config.mjs     # Site configuration

Every page is a simple markdown file with YAML frontmatter:

---
title: "About Us"
description: "Learn about our company and team."
---

# About Our Company

We've been serving customers in Hampshire since 2015...

Step 2: SystemDox Connects to Your Repository

SystemDox is our AI-powered document editor. It has a built-in GitHub Sync feature that connects your SystemDox account to your website’s GitHub repository.

How the sync works

You install the PuglieseWeb GitHub App on your repository (a one-click authorisation)
We link your SystemDox project to the repository
From that point on, every page you create or edit in SystemDox automatically commits to your GitHub repo

Under the hood, the sync uses the GitHub Contents API. When you save a page:

SystemDox converts your content to markdown with frontmatter
The GitHub Sync API checks if the file already exists (to get its SHA for updates)
It creates a commit with your changes — a real Git commit, visible in your repo’s history
GitHub Actions detects the new commit and triggers a site rebuild

You never touch Git, the terminal, or any deployment tool. The entire flow is invisible to you — you just write and save.

What happens to your revision history

Every save creates a Git commit. This means:

You can see every version of every page in your GitHub repo
You can compare any two versions side by side (GitHub’s diff view)
You can roll back to any previous version at any time
Your entire content history is permanent — it doesn’t expire or get pruned

This is the same version control system used by every major software company in the world. It’s battle-tested, reliable, and free.

Step 3: You Create Content With a Visual Editor

You don’t need to know markdown, HTML, or Git. SystemDox gives you a clean visual editor where you can:

Write and format text — headings, bold, italic, lists, links, quotes
Add images — drag and drop, with automatic optimisation
Create new pages — choose a page type (Home, About, Blog Post, Service Page) and start writing
Preview your changes — see how the page will look before publishing
Use AI assistance — generate drafts, improve copy, or restructure content

The editor works in your browser on any device. Changes sync to GitHub the moment you save.

Page types we set up for you

Page Type	Purpose	GitHub Path
Homepage	Your main landing page	`src/pages/index.md`
About	Company or personal info	`src/pages/about.md`
Services	What you offer	`src/pages/services.md`
Blog Post	Articles and updates	`src/pages/blog/[slug].md`
Contact	Contact form and details	`src/pages/contact.md`
FAQ	Frequently asked questions	`src/pages/faq.md`

You can create as many pages as you want. Each one becomes a file in your repo and a page on your site.

Step 4: Your Site Publishes Automatically

When a commit lands in your repository (from SystemDox or any other source), GitHub Actions runs the build:

Checkout — pulls the latest code
Install — installs dependencies (cached for speed)
Build — Astro compiles your markdown into static HTML, CSS, and JavaScript
Deploy — pushes the built files to GitHub Pages

The entire process takes 30–90 seconds. Your changes are live on the internet within two minutes of clicking “Save” in SystemDox.

GitHub Pages hosting

GitHub Pages is a free static site hosting service provided by GitHub. It includes:

Free hosting — no monthly fees, no bandwidth limits for normal usage
Free SSL — HTTPS with an automatically provisioned certificate
Global CDN — your site is served from edge locations worldwide
Custom domains — point yourdomain.com to your GitHub Pages site
99.9% uptime — backed by GitHub’s infrastructure SLA

Because your site is static HTML (no database, no server-side code), it’s inherently fast and secure. There’s nothing to hack, nothing to patch, and nothing to maintain.

AI-Powered Search — Built In

Every site we build includes semantic search — an AI-powered search feature that understands what your visitors mean, not just the exact words they type.

How it works

When you publish or update a page, the deploy pipeline automatically sends your content to our shared semantic search service. This service:

Reads your content — the full text of every page
Generates an embedding — a mathematical representation of the page’s meaning, using AWS Bedrock (the same AI infrastructure used by enterprise companies)
Stores the embedding — in a central, multi-tenant database indexed by your site

When a visitor searches your site, their query is also converted to an embedding, and the service finds pages with the most similar meaning — not just keyword matches.

What this means for your visitors

Search for “opening hours” and find your “When we’re available” page — even though the words don’t match
Search for “how much does it cost” and find your pricing page — even if the page title is “Our Plans”
Search for “get in touch” and find your contact page — semantic understanding, not string matching

Architecture

flowchart LR
    Deploy([Site Deploy])
    Index[Indexing API]
    Bedrock[AWS Bedrock]
    DB[(Embeddings DB)]
    Search[Search Widget]
    Query[Search API]
    Results([Ranked Results])

    Deploy -->|POST content| Index
    Index -->|Generate embedding| Bedrock
    Bedrock -->|1024-dim vector| Index
    Index -->|Store| DB

    Search -->|User query| Query
    Query -->|Embed query| Bedrock
    Query -->|Cosine similarity| DB
    DB -->|Ranked matches| Results

What you don’t have to do

No search plugins to install or configure
No manual tagging or keyword entry
No third-party search service subscriptions (Algolia, etc.)
No JavaScript to add — the search widget is part of your site template

Search is included in every plan at no extra cost.

What “Owning Your Content” Actually Means

Here’s a concrete example of what ownership looks like:

Scenario: You decide to leave PuglieseWeb

Your GitHub repository still exists — it’s yours
Your entire site, with full history, is still there
You can continue editing markdown files directly in GitHub
GitHub Pages continues hosting your site for free
You owe us nothing. Your site keeps running.

Compare this to cancelling a WordPress hosting plan or a Squarespace subscription — your site goes dark immediately.

Scenario: You want to switch to a different developer

Give your new developer access to your GitHub repository
They can see every page, every revision, and the complete site structure
They can modify the template, add features, or migrate to a different framework
Your content (the markdown files) works with any static site generator

No export tools, no data migration headaches, no lost formatting.

Scenario: GitHub shuts down (extremely unlikely)

Your content is a standard Git repository. You can clone it to your local machine, push it to GitLab or Bitbucket, or host it anywhere. A single command (git clone) gives you everything:

git clone https://github.com/your-account/your-website.git

That’s your entire website — every page, every image, every revision — in a folder on your computer.

Pricing

Component	Cost
Initial setup (design, build, deploy)	From £499 one-off
SystemDox subscription (visual editor + GitHub sync)	From £9.90/month
GitHub Pages hosting	Free
SSL certificate	Free
AI-powered search	Included
Custom domain	£10–15/year (you buy from any registrar)

No hidden fees. No hosting markup. The only ongoing cost is the SystemDox subscription for the visual editor — and even without it, your site keeps running and you can edit files directly in GitHub.

Who Is This For?

This service is ideal for:

Small businesses that want a professional website without ongoing hosting costs
Freelancers and consultants who want full control over their content
Anyone burned by vendor lock-in from WordPress, Squarespace, or Wix
Tech-savvy clients who appreciate that their content is in Git (but non-technical clients benefit equally — they never see Git)

Getting Started

Book a discovery call — we’ll discuss your needs and show you a demo
We build your template — branded, responsive, SEO-optimised
We connect SystemDox — one-time setup, takes minutes
You start creating — pages, blog posts, updates. Save and it’s live.

Your content. Your repository. Your revision history. Forever.

Get started today or explore the service page for more details.