How This Blog Is Built

This page documents the technical setup behind the blog: the framework, content model, customization approach, and deployment flow. It is meant for anyone curious about how a simple personal site can be built and kept up to date with minimal overhead.

High-level architecture

Markdown / MDX content
        ↓
Astro static site generator
        ↓
Production build (HTML, CSS, JS)
        ↓
Git repository
        ↓
Cloudflare (auto-deploy on push)
        ↓
Custom domain

The site is fully static. There is no application server, database, or runtime backend. Pages are generated at build time and served as fast, cache-friendly files from the edge.

Starting point

The project began as the Bookworm Light Astro template — a minimal blog theme with posts, authors, categories, tags, search, and contact support. The template was then customized into a personal infrastructure-focused blog by:

• Replacing demo content with original writing
• Updating site metadata and navigation
• Adding dedicated learning pages under an Infrastructure section
• Turning the home page into a landing page with a post feed below
• Removing stock imagery and unused demo authors/posts

Core technology stack

Layer	Choice	Role
Framework	Astro	Static site generation, routing, content collections
Styling	Tailwind CSS	Layout, typography, responsive design
Content	Markdown + MDX	Blog posts and standalone pages
Interactivity	React (islands)	Search bar and a few UI helpers
Images	Astro image pipeline	Optimized images at build time
Deployment	Cloudflare	Hosting and automatic deploys from Git

Astro was a good fit because content lives in plain files, builds are fast, and the output is lightweight static HTML.

How content is organized

Content is stored under src/content/ using Astro content collections:

Collection	Purpose	Example route
posts	Blog articles	/blog/welcome
pages	Standalone pages	/docker-kubernetes
about	About page content	/about
contact	Contact page intro	/contact
authors	Author profile	/authors/{slug}

Each file has frontmatter at the top for metadata such as title, description, date, categories, and tags. Draft posts can be hidden by setting draft: true.

Configuration files

Site-wide settings live in JSON config files rather than being hard-coded into components:

• src/config/config.json — site title, description, SEO metadata, contact form endpoint
• src/config/menu.json — header and footer navigation
• src/config/social.json — social links in the footer
• src/config/theme.json — colors and fonts

This keeps routine updates out of the layout code.

Key customizations made

Home page

The default template showed only a post list. The home page was changed to include:

1. A hero section with site title and tagline
2. Quick-link cards to major sections
3. A Latest posts feed underneath

Infrastructure section

Technical learning notes were grouped under a dedicated Infrastructure navigation section:

• Overview hub page
• Docker & Kubernetes guide
• Veritas Clustering guide

New topics can be added by creating another page in src/content/pages/ and linking it from menu.json.

Contact form

Because the site is static, the contact form posts to a third-party form handler, which forwards messages to an inbox. No custom server code is required.

Local development workflow

# Install dependencies
pnpm install

# Start dev server
astro dev --background

# Production build
pnpm run build

# Preview production output locally
pnpm run preview

During development, Astro watches content and component files and reloads the browser when changes are saved.

Deployment with Cloudflare

The site is connected to a Git repository. When code is pushed to the main branch, Cloudflare automatically:

1. Pulls the latest source
2. Installs dependencies
3. Runs the Astro production build
4. Publishes the dist/ output
5. Serves the site on a custom domain registered through Cloudflare

The repo also includes wrangler.jsonc for Cloudflare Workers static asset deployment, with the build output directory set to ./dist.

{
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

That means updates follow a simple pipeline:

Edit content locally → commit → push to Git → Cloudflare rebuilds → site updates

No manual FTP uploads or server maintenance.

How a new blog post is added

1. Create a new .md or .mdx file in src/content/posts/
2. Add frontmatter (title, date, description, categories, tags, authors)
3. Write the article body in Markdown
4. Commit and push to Git
5. Cloudflare rebuilds and publishes the post automatically

Example frontmatter:

---
title: "My New Post"
description: "Short summary for SEO and previews"
date: 2026-07-16T12:00:00Z
categories: ["infrastructure"]
authors: ["Author Name"]
tags: ["linux", "automation"]
draft: false
---

How a new standalone page is added

1. Create a file in src/content/pages/ (for example my-topic.mdx)
2. Add frontmatter with title and description
3. Add a menu entry in src/config/menu.json if it should appear in navigation
4. Push to Git — the page is live after the next deploy

Search, categories, and tags

These features come from the original template and still work out of the box:

• Search — client-side search powered by Fuse.js over post metadata
• Categories — group posts by broad topic
• Tags — more specific labels for filtering related content

What was intentionally kept simple

• No CMS dashboard — content is edited directly in Markdown files
• No database — everything is file-based
• No comment system — keeps maintenance and moderation low
• No analytics enabled by default — can be added later if needed

Possible future improvements

• Move the contact form to a provider with a clearer activation dashboard
• Add an RSS feed for blog subscribers
• Automate social preview images per post
• Expand the Infrastructure section with more learning pages
• Add CI checks (astro check, build verification) before deploy

Summary

This blog is a customized Astro static site deployed through Git + Cloudflare. Content lives in Markdown files, configuration lives in JSON, and every push to the repository triggers an automatic rebuild. That keeps the setup fast, inexpensive, and easy to maintain while still supporting a proper blog, structured learning pages, and a contact form without running a server.

If you are building something similar, the main lesson is simple: start with a solid static template, keep content in files, automate deployment early, and add complexity only when you actually need it.