merox-erudite: A Customized Astro Theme

#automation#open-source

A fork of astro-erudite v1 with comments, analytics, SEO schemas, and an enhanced homepage — built for production blogging.

I started this blog on astro-erudite — a clean, minimal template. Over several months I kept adding things: comments, analytics, schema markup, a homepage that actually said something about me. At some point the diff was large enough that keeping it as silent local patches didn’t make sense anymore, so I published it as a fork: merox-erudite.

Most of this was built with Claude Code and Cursor. I gave it well-defined prompts, reviewed everything, kept pushing until it was clean with no workarounds. I’m a sysadmin, not a web developer — this was a genuine experiment in how far you can get with AI tooling when you know what you want but don’t know the framework well.

Important (Update — June 2026)

This post documents merox-erudite, a fork of astro-erudite v1. merox.dev has since migrated to astro-erudite v2, which is a complete rewrite: no Tailwind, no React, no MDX by default, IBM Plex Sans fonts, Sätteri Markdown pipeline, native callout directives, and collapsible code sections. The merox-erudite fork remains available for v1 users, but I no longer maintain it actively.

Warning

Built out of passion with basic programming knowledge. It works for my use case but may contain bugs or suboptimal code. Use at your own discretion — issues and PRs welcome on GitHub.

merox-erudite theme preview

The reason for a fork rather than contributing back: some features (AdSense) don’t fit the original theme’s minimal philosophy, and the scope of changes is too personal to be a reasonable upstream PR. astro-erudite stays minimal; merox-erudite is batteries-included.

What I added

Giscus comments — GitHub Discussions, lazy-loaded, surviving Astro view transitions, following the theme. Unconfigured, the component doesn’t render at all. Needs a public repo with Discussions enabled.

Analytics — Google Analytics and Umami, both off unless the env vars exist:

Terminal window
PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX
PUBLIC_UMAMI_WEBSITE_ID=your-umami-id

SEO schemas — reusable FAQ and HowTo components for structured data.

Homepage — experience timeline, skills badges, a hero that says something. The timeline is data, configured in src/pages/index.astro:

const experience: ExperienceItem[] = [
  {
    role: 'Your Role',
    company: 'Company Name',
    period: '2020 - Present',
    current: true,
    icon: 'lucide:briefcase',
    key: 'Your achievements and responsibilities'
  },
]

Design — Geist variable fonts, better contrast in dark mode, visible focus rings for keyboard navigation.

Against the original

Feature astro-erudite v1 merox-erudite
Comments ❌ ✅ Giscus (GitHub)
Analytics ❌ ✅ GA & Umami
SEO Schemas Basic ✅ FAQ & HowTo
Homepage Standard ✅ Enhanced with timeline
Fonts System ✅ Geist variable fonts
AdSense ❌ ✅ Built-in component

Getting started

  1. Click “Use this template” on the merox-erudite repository
  2. Clone and install:
    Terminal window
    git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git
    cd YOUR_REPO_NAME
    npm install
  3. Start dev server:
    Terminal window
    npm run dev
    Available at http://localhost:1234
  4. Update src/consts.ts with your site info
  5. Configure optional features via environment variables
Warning

For the original theme’s architecture and design documentation, see the astro-erudite repository by @jktrn.

Deploying it

Free tier, global CDN, deploys on push, and environment variables you can edit without a CLI.

Astro is auto-detected, but if it isn’t:

  • Build command: npm run build
  • Output directory: dist
  • Node version: 20.x+

Environment variables go in Cloudflare Dashboard → Settings → Environment Variables. They’re read at build time, so a change here needs a redeploy to take effect:

PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX
PUBLIC_UMAMI_WEBSITE_ID=your-umami-id


PUBLIC_GISCUS_REPO=username/repo
PUBLIC_GISCUS_REPO_ID=your-repo-id
PUBLIC_GISCUS_CATEGORY=Blog Comments
PUBLIC_GISCUS_CATEGORY_ID=your-category-id
Tip

Get your Giscus values from giscus.app after enabling Discussions on your repo.

What I’d tell anyone considering the same fork: the moment your changes stop being patches and start being a philosophy the upstream doesn’t share, fork it. AdSense was never going to land in a theme whose whole point is minimalism, and pretending otherwise just meant carrying an unmergeable diff in silence.

References