Introducing merox-erudite: My Customized Astro Blogging Theme

When I started this blog, I chose astro-erudite as my base theme. It’s an excellent, minimal template that gave me exactly what I needed to get started. But as I used it more, I found myself adding features that I needed for a production blog—newsletter integration, comments, analytics, and more.

After several months of customizations, I realized I had made enough changes that it made sense to share my version as a separate theme: merox-erudite.

Why a Fork Instead of Contributing Back?

I considered contributing these features back to astro-erudite, but there were a few reasons I decided to fork instead:

1. Different philosophy - Some features (like AdSense) might not align with the original theme’s minimal goals
2. Optional features - Many additions are optional and might clutter the base theme
3. Extensive customization - The modifications are quite extensive and personal
4. Easier maintenance - Maintaining as a separate theme is simpler for me

What I Added

Newsletter Integration (Brevo)

One of the first things I needed was newsletter functionality. I chose Brevo (formerly Sendinblue) because they offer a generous free tier and have a straightforward API.

The integration includes:

• GDPR-compliant consent checkbox
• Double opt-in support
• Centralized configuration

1
// Configure in src/consts.ts
2
export const BREVO = {
3
  apiKey: import.meta.env.BREVO_API_KEY || '',
4
  listId: import.meta.env.BREVO_LIST_ID || '',
5
  templateId: import.meta.env.BREVO_TEMPLATE_ID || '5',
6
}

Disqus Comments

I wanted comments on my blog posts, so I integrated Disqus with:

• Lazy loading (comments only load when visible)
• View transition support for Astro
• Proper error handling
• Accessibility improvements

Analytics Support

I added support for both Google Analytics and Umami Analytics. Both are optional and configured via environment variables:

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

SEO Enhancements

I created reusable components for FAQ Schema and HowTo Schema markup. These help with voice search optimization and structured data for search engines.

Enhanced Homepage

I customized the homepage with:

• Experience timeline component
• Skills showcase with animated tech badges
• Better hero section

The experience timeline is particularly useful for showcasing your professional journey. You can customize it in src/pages/index.astro:

1
const experience: ExperienceItem[] = [
2
  {
3
    role: 'Your Role',
4
    company: 'Company Name',
5
    period: '2020 - Present',
6
    current: true,
7
    icon: 'lucide:briefcase',
8
    key: 'Your achievements and responsibilities'
9
  },
10
]

Design Improvements

• Geist font family - I switched to Geist variable fonts for better typography
• Improved contrast - Better accessibility compliance
• Enhanced dark mode - Refined color palette
• Better focus indicators - Improved keyboard navigation

What’s Different?

Getting Started

If you want to use merox-erudite for your blog:

1. Use the template - Click “Use this template” on the merox-erudite repository to create your own repository
2. Clone your repository:

   git clone https://github.com/YOUR_USERNAME/YOUR_REPO_NAME.git
   cd YOUR_REPO_NAME

3. Install dependencies:

   npm install

4. Start the development server:

   npm run dev

   Your site will be available at http://localhost:1234
5. Configure - Update src/consts.ts with your site information (title, description, author, etc.)
6. Optional features - Set up newsletter, comments, or analytics if needed (see Deployment section for environment variables)

Deployment on Cloudflare Pages

I recommend deploying merox-erudite on Cloudflare Pages—it’s free, fast, and makes handling environment variables (especially for Brevo) very straightforward.

Why Cloudflare Pages?

• Free tier - Generous limits for personal blogs
• Fast global CDN - Your site loads quickly worldwide
• Easy environment variables - Simple UI for managing secrets
• Automatic deployments - Connects directly to GitHub
• Built-in analytics - Optional Web Analytics included

Setting Up Environment Variables

After connecting your repository to Cloudflare Pages, you’ll need to add environment variables for optional features:

1. Go to your project in Cloudflare Dashboard
2. Navigate to Settings → Environment Variables
3. Add the following variables:

For Newsletter (Brevo):

1
BREVO_API_KEY=your-api-key-here (set as Secret)
2
BREVO_LIST_ID=your-list-id-here (can be Text)
3
BREVO_TEMPLATE_ID=5 (can be Text)

For Analytics:

1
PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX (can be Text)
2
PUBLIC_UMAMI_WEBSITE_ID=your-umami-id (can be Text)

For Disqus:

1
PUBLIC_DISQUS_SHORTNAME=your-shortname (can be Text)

Build Settings

Cloudflare Pages will auto-detect Astro, but if needed, use these settings:

• Build command: npm run build
• Build output directory: dist
• Node version: 20.x or later

That’s it! Once you push to your repository, Cloudflare Pages will automatically build and deploy your site. The environment variables are securely stored and only accessible during the build process and at runtime (for PUBLIC_* variables).

Development Process

Since I’m not a professional programmer, I used Cursor to help me build this theme. The process involved:

• Iterative conversations with Cursor’s AI assistant
• Learning code concepts through AI explanations
• Testing and refining features
• Building on the excellent foundation of astro-erudite

While the code was written with AI assistance, all decisions about features, design, and implementation were made by me based on my actual needs as a blogger. The theme has been tested and is fully functional. All features work as documented.

Credits

• Original theme: astro-erudite by @jktrn - All credit for the original design and architecture
• Inspiration: Astro Micro by trevortylerlee
• Development tool: Cursor AI coding assistant

Try It Out

Ready to use merox-erudite? Head over to the GitHub repository and click “Use this template” to get started!