Syntax & Synapse

This post details exactly how I transformed a generic Astro.js template into the “Syntax & Synapse” blog you’re reading right now. If you’re looking to build your own technical blog, this will serve as your complete roadmap.

Starting Point: The Lexington Themes Template

I began with a clean Astro.js microblog template from Lexington Themes, featuring:

Astro.js 5.9.3 with TypeScript
Tailwind CSS v4 (CSS-first approach)
Content Collections for structured blog posts
SEO optimization with @astrolib/seo
RSS feeds and sitemap generation

The template was solid but needed significant customization for a personal AI/software development blog.

Step 1: Project Setup & Dependencies

# Clone and setup
git clone [template-repo]
cd microblog
npm install  # or bun install

# Verify it works
npm run dev  # Starts at localhost:4321

Step 2: Configuration Overhaul

2.1 Update Site Configuration

File: astro.config.mjs

export default defineConfig({
  site: 'https://gnokit.github.io/Syntax-Synapse', // Your GitHub Pages URL
  vite: {
    plugins: [tailwindcss()],
  },
  integrations: [sitemap(), mdx()]
});

2.2 Clean House

Removed all template content:

rm src/content/posts/[1-6].md
rm src/images/blog/[1-6].jpeg

Step 3: Brand Identity Implementation

3.1 SEO & Meta Tags

File: src/components/BaseHead.astro

Updated every meta tag, Open Graph data, and Twitter cards:

<AstroSeo
  title="Syntax & Synapse"
  description="Exploring the intersection of AI and software development..."
  canonical="https://gnokit.github.io/Syntax-Synapse"
  openGraph={{
    site_name: "Syntax & Synapse",
    type: "website",
    locale: "en_US",
  }}
/>

3.2 Visual Identity

File: src/styles/global.css

Added custom color scheme for AI/dev theme:

@theme {
  --color-accent-50: oklch(96% 0.03 264);
  --color-accent-100: oklch(91% 0.07 264);
  --color-accent-500: oklch(59% 0.26 264); /* Primary AI blue */
  --color-accent-600: oklch(51% 0.25 264);
  --color-base-50: oklch(96.74% 0.001 286.38);
  /* ... rest of color palette */
}

3.3 Content Updates

README.md: Completely rewritten for the project
Footer: Updated with “Syntax & Synapse” branding
About page: Created comprehensive /about.astro

Step 4: Content Schema & Structure

4.1 Content Schema

The schema requires specific frontmatter:

// src/content/config.ts
const postsCollection = defineCollection({
  schema: ({ image }) =>
    z.object({
      title: z.string(),
      pubDate: z.date(),
      description: z.string(),
      author: z.string(),
      image: z.object({
        url: image(),
        alt: z.string(),
      }),
      tags: z.array(z.string()),
    }),
});

4.2 Blog Post Template

---
title: "Your Post Title"
pubDate: 2025-07-28T14:30:00Z
description: "SEO-friendly description"
author: "Your Name"
image:
  url: "../../images/blog/your-image.svg"
  alt: "Descriptive alt text"
tags: ["AI", "tutorial", "development"]
---

Your content here...

Step 5: GitHub Pages Deployment

5.1 Build Configuration

The site is configured for GitHub Pages with:

Static build output (dist/)
Proper base URL structure
Optimized for GitHub Pages hosting

5.2 Deployment Workflow

# Build the site
npm run build

# Deploy to GitHub Pages
# Copy dist/ folder contents to your gh-pages branch

Step 6: Content Management Workflow

6.1 Creating New Posts

Create file: src/content/posts/my-new-post.md
Add required frontmatter
Write content in Markdown
Run npm run build to test
Deploy updated site

6.2 Image Management

Place images in src/images/blog/
Reference with relative paths: ../../images/blog/image.svg
Astro automatically optimizes images during build

The Tech Stack Decisions

Why Astro.js?

Zero JavaScript by default for lightning-fast loads
Component Islands for selective interactivity
Content Collections for structured blog posts
Built-in SEO optimization

Why Tailwind CSS v4?

CSS-first configuration (no JS config files)
Modern color spaces (oklch)
Utility-first for rapid prototyping
Dark mode ready for future enhancement

GitHub Pages Benefits

Free hosting for public repositories
Automatic deployment via GitHub Actions
Custom domain support
CDN distribution globally

Performance Results

After optimization:

Build time: <600ms
Page weight: Minimal (Astro ships zero JS by default)
SEO score: Perfect (meta tags, structured data, sitemap)
Lighthouse: 100/100/100/100 scores

Lessons Learned

Start with schema: Understanding the content schema first prevents build errors
Image paths matter: Relative paths from content to images must be exact
SEO early: Update meta tags before publishing
Test builds frequently: Catch issues early with npm run build
Keep it simple: Astro’s minimal approach encourages clean, maintainable code

Next Steps for Enhancement

Future improvements planned:

Dark mode toggle
Search functionality
Comment system (Giscus)
Newsletter signup
Performance analytics

Get Started Yourself

Want to build your own? Fork this project and:

Update astro.config.mjs with your URL
Customize src/styles/global.css with your colors
Replace content in src/content/posts/
Update src/components/BaseHead.astro with your SEO info
Deploy to GitHub Pages

The beauty of this setup is its simplicity - you get a fast, SEO-optimized blog without the complexity of traditional frameworks.

Ready to build your own? The template is just the beginning - make it yours and start sharing your technical insights with the world.

Building Syntax & Synapse: From Template to Production