A Deep Dive Into My Blog's Technical Setup

Published: at 12:00 AM

Welcome to a behind-the-scenes tour of my blog’s technical architecture! My goal with this post is to share the choices I’ve made, the custom features I’ve implemented, and why I believe this setup provides a fantastic experience for both me as a developer and you as a reader.

Core Technologies

At the heart of this blog are a few key technologies that work together to deliver a fast, modern, and maintainable website.

While many of the features are custom-built, the blog’s development started with the “Astro Paper” theme by Sat Naing (https://github.com/satnaing/astro-paper). This theme provided a solid and well-structured foundation, especially for the basic blog functionalities and styling. On top of this base, I’ve layered custom features such as the interactive resume page with PDF download, an advanced table of contents component, and various specific UI/UX enhancements to tailor the site to my needs.

Theme and Styling

I wanted a unique look and feel for the blog, so I opted to build a custom theme from scratch rather than using an off-the-shelf solution.

Custom-Built Theme

Every aspect of the visual design, from typography to color schemes, has been carefully considered and implemented using Tailwind CSS.

Light & Dark Mode

A crucial feature of modern web design is a robust light and dark mode. Here’s how it’s implemented:

Tailwind Configuration

Theme-Aware Syntax Highlighting

Even code blocks adapt to the current theme! Astro uses Shiki for syntax highlighting. The toggle-theme.js script includes logic to dynamically adjust Shiki’s styling. For dark mode, I provide a custom color map (githubDarkColorMap) to ensure code is readable and aesthetically pleasing.

// Conceptual snippet from toggle-theme.js related to Shiki
function updateShikiTheme(theme) {
  const shikiBlocks = document.querySelectorAll('pre.shiki');
  if (theme === 'dark') {
    // Apply dark theme styles, potentially by adding/removing classes
    // or directly manipulating style properties based on githubDarkColorMap
  } else {
    // Apply light theme styles
  }
}

Content Management & Structure

Astro’s content collections are the backbone of how blog posts and other content are managed.

Key Layouts

Spotlight on Custom Features

Beyond the core setup, I’ve implemented several custom features to enhance the blog.

Dynamic Open Graph Image Generation

// Simplified conceptual example from src/utils/generateOgImages.tsx
// (Actual implementation involves Astro's build hooks)

// import { satori } from 'satori';
// import { Resvg } from '@resvg/resvg-js';
// import { siteOgImage } from './siteOgImage'; // A React component

// async function generateImage() {
//   const svg = await satori(
//     siteOgImage({ title: 'My Awesome Blog Post' }),
//     {
//       width: 1200,
//       height: 630,
//       fonts: [/* font data */],
//     }
//   );
//   const resvg = new Resvg(svg);
//   const pngData = resvg.render();
//   const pngBuffer = pngData.asPng();
//   // fs.writeFileSync(..., pngBuffer);
// }

Interactive Resume with PDF Generation

Reusable Astro Components

The src/components/ directory is filled with reusable Astro components that promote a modular and maintainable UI. Examples include:

Helper Utilities

The src/utils/ directory houses various helper functions to keep the codebase organized:

SEO and Performance

Search engine optimization and site performance are top priorities.

SEO Best Practices

Performance Optimizations

// Example snippet from astro.config.mjs (or .ts) for Vite options
// import { defineConfig } from 'astro/config';

// export default defineConfig({
//   vite: {
//     build: {
//       rollupOptions: {
//         output: {
//           manualChunks(id) {
//             if (id.includes('node_modules')) {
//               // Group vendor modules into a separate chunk
//               return 'vendor';
//             }
//           }
//         }
//       }
//     }
//   }
// });

Hosting and Deployment

The blog is hosted on Cloudflare Pages, which provides a seamless and robust platform for deploying static sites. The deployment process is tightly integrated with my Git workflow, making it highly efficient:

This CI/CD (Continuous Integration/Continuous Deployment) setup offers several benefits:

Development Experience

A smooth development workflow is essential for productivity and code quality.

Step-by-Step Deployment Guide

This guide will walk you through deploying this Astro-based blog using Cloudflare Pages, leveraging its seamless integration with GitHub.

I. Prerequisites:

II. Setting Up Cloudflare Pages:

  1. Log in to Cloudflare: Navigate to your Cloudflare dashboard.
  2. Select Pages: In the sidebar, go to “Workers & Pages” and then select “Pages”.
  3. Create a New Project: Click on “Create a project” and choose “Connect to Git”.
  4. Connect to GitHub:
    • Authorize Cloudflare to access your GitHub repositories. You can choose to give access to all repositories or select specific ones.
    • Select the repository for your blog.
  5. Configure Build Settings:
    • Project Name: This will be part of your *.pages.dev subdomain (e.g., my-blog).
    • Production Branch: Select your main branch (usually main or master).
    • Framework Preset: Choose “Astro” from the dropdown. Cloudflare will often auto-detect this.
    • Build Command: This should be pre-filled by the Astro preset. Common commands are:
      • npm run build (if your package.json has a build script like "build": "astro build")
      • Or directly astro build
    • Build Output Directory: This should also be pre-filled. For Astro, it’s dist/.
    • Root Directory (Advanced): Leave this as is unless your Astro project is in a subdirectory of your repository.
    • Environment Variables (Advanced):
      • This is where you can add any necessary environment variables. For example, if your src/config.ts or other parts of your application rely on environment variables (e.g., API_KEY, ALGOLIA_SEARCH_KEY), add them here.
      • Click “Add variable” for each one. You can set different values for “Production” and “Preview” environments if needed.
      • Common variables for Astro projects might include those for analytics services or image optimization plugins, if not already hardcoded or managed via Astro’s config files.
  6. Save and Deploy:
    • Click “Save and Deploy”. Cloudflare will pull your code, build it according to your settings, and deploy it.
    • The first deployment might take a few minutes. You can watch the progress in the Cloudflare dashboard.

III. The Build and Deployment Process:

IV. Automatic Preview and Production Deployments:

V. Custom Domains (Optional):

  1. Navigate to Custom Domains: In your Cloudflare Pages project dashboard, go to the “Custom domains” tab.
  2. Set up a Custom Domain: Click “Set up a custom domain” and follow the instructions.
    • If your domain is already managed by Cloudflare (i.e., you use Cloudflare as your DNS provider), this process is very straightforward. You’ll typically just need to add a CNAME record.
    • If your domain is hosted elsewhere, Cloudflare will provide instructions on what DNS records (usually CNAME or A records) to set up with your domain registrar or DNS provider.
  3. Cloudflare will automatically handle SSL/TLS certificates for your custom domain, providing HTTPS.

VI. Troubleshooting Common Issues:

This detailed guide should help users successfully deploy their version of the blog. Remember to replace placeholders like your-project with actual project names or examples.

Conclusion

This deep dive has covered the main technical aspects of my blog’s setup. The combination of Astro’s performance, Tailwind’s styling flexibility, TypeScript’s safety, and a host of custom features creates a platform that I’m truly proud of. It’s a testament to how modern web technologies can be leveraged to build highly personalized and efficient online experiences.

I believe this setup not only provides a fast and enjoyable experience for you, the reader, but also a productive and maintainable environment for me as the developer.

Do you have any questions about this setup? Or perhaps you have your own interesting blog architecture to share? Feel free to reach out or leave a comment!