Design Decisions: Building a Modern Technical Blog

Starting a technical blog from scratch in 2026, I needed a framework that could support far more than static content. The vision included 3D visualizations, interactive charts, server-side API endpoints for GitHub integration and search, and a reading experience that felt more like an application than a document. Static site generators like Hugo excelled at content but couldn't support the interactivity I wanted. React-based solutions like Next.js carried virtual DOM overhead that seemed wasteful for a content-heavy site. Astro was compelling for its island architecture, but I needed deeper component interactivity than islands easily provide.

The task was to find a framework that compiled to minimal client-side JavaScript, provided explicit and predictable reactivity, and colocated frontend and backend code without the complexity of a separate API layer.

After evaluating Next.js, Astro, and Hugo against these requirements, I chose SvelteKit 2 with Svelte 5. The result is a framework that eliminates virtual DOM overhead entirely, provides explicit reactivity through runes, and lets me write API endpoints alongside the components that consume them — all while shipping less JavaScript to the client than any React-based alternative.

With a project featuring heavy interactive components and frequent iteration, slow build tools would have been a serious drag on development velocity. Traditional bundlers like Webpack require full rebuilds on changes, and the lag compounds when you're tweaking 3D graph parameters or CSS transitions and need instant visual feedback.

I needed a build tool that provided near-instant feedback during development while still producing optimized production bundles with proper code splitting. Vite 7 powers the development experience with:

• Hot Module Replacement (HMR) that updates in milliseconds
• Native ES modules during development (no bundling required)
• Optimized production builds with code splitting
• Built-in TypeScript support

The result is a development server that starts instantly and updates faster than I can switch windows.

The blog needed a hosting platform that could handle both static prerendered pages and dynamic API endpoints (GitHub commit fetching, newsletter subscriptions, link preview proxying) without managing separate infrastructure. Self-hosting would mean configuring a server, managing SSL certificates, and dealing with scaling — all distractions from writing content.

The task was to find a platform with native SvelteKit support, global edge distribution for API routes, and zero-config deployments from Git pushes. I chose Vercel because:

1. Native SvelteKit support: The @sveltejs/adapter-vercel handles all configuration
2. Edge functions: API routes run close to users globally
3. Automatic previews: Every PR gets a preview deployment
4. Analytics integration: Built-in performance monitoring

The vercel.json configuration enables aggressive caching:

{
  "headers": [
    {
      "source": "/fonts/(.*)",
      "headers": [
        { "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }
      ]
    }
  ]
}

Writing technical blog posts in Markdown quickly exposed its limitations. Code examples couldn't be executed or verified within the document, so they'd drift out of sync with the prose. Markdown's flat heading structure made reorganizing long posts cumbersome. And for literate programming posts — where the code is the content — Markdown had no concept of code tangling or noweb references.

I needed an authoring system that could execute code blocks inline, tangle source files from the document, support deep hierarchical organization, and export clean HTML. Rather than using Markdown or a CMS, I write all content in Emacs org-mode. The result is that every code example in a post can be verified at authoring time, documents restructure with a few keystrokes, and the same org file can produce both a blog post and a working program.

With content authored in org-mode but served by a SvelteKit application, I needed a bridge between the two worlds. Org-mode's HTML export produces standalone documents, but SvelteKit needs to extract metadata (title, author, date, description) for SEO and navigation, and the content needs to integrate with the blog's component system for features like table of contents and tag extraction.

The task was to build a pipeline that preserves org-mode's authoring power while producing content that SvelteKit can load, parse, and enhance with interactive features. The org-to-HTML pipeline works as follows:

1. Authoring: Write content in org/*.org files
2. Export: Emacs exports to HTML via C-c C-e h h
3. Storage: HTML files live in src/routes/[post]/
4. Loading: SvelteKit loads HTML server-side, extracts metadata
5. Rendering: Client-side components parse and enhance the HTML

With blog posts growing in length and number, readers needed a way to find specific content across all posts. But Algolia's record size limits (10KB per record) meant I couldn't simply index entire posts as single documents. Additionally, search results that link to an entire post aren't particularly helpful when the reader wants a specific section.

The solution was to chunk content by heading, creating one searchable record per section. This way, search results link directly to the relevant section with a highlight animation. For Algolia search integration, I created Python scripts that chunk content by heading:

# extract_html.py (simplified)
def extract_sections(html_content):
    soup = BeautifulSoup(html_content, 'html.parser')
    sections = []

    for heading in soup.find_all(['h2', 'h3', 'h4', 'h5', 'h6']):
        section_id = heading.get('id', '')
        section_title = heading.get_text()
        content = get_section_content(heading)

        sections.append({
            'anchor': section_id,
            'sectionTitle': section_title,
            'content': content[:5000]  # Max 5KB per record
        })

    return sections

Each heading becomes a searchable record, enabling jump-to-section from search results.

A content-heavy blog with interactive visualizations needed consistent spacing, colors, and typography without bloating the CSS bundle. The primary concern was keeping the styling layer lightweight — every kilobyte of CSS is render-blocking, and a blog should load fast on any connection.

The task was to find a system that provides design consistency (spacing scales, color palettes, easing curves) without the overhead of utility-class frameworks or the tooling complexity of preprocessors. Rather than Tailwind CSS, I chose Open Props — a CSS custom properties library providing design tokens at just ~14KB. The result is semantic variable names like --text-muted instead of opaque utilities like text-gray-400, direct CSS control without fighting framework abstractions, and a bundle that's a fraction of even Tailwind's JIT output:

@import "open-props/style";

/* Semantic variable mapping */
:root {
  --bg-primary: #fffefc;          /* Warm cream */
  --text-primary: var(--gray-8);
  --link-color: var(--indigo-7);
  --size-spacing: var(--size-4);  /* Consistent spacing */
}

Dark mode is table stakes for a modern developer-focused blog. Readers coding late at night expect a site to respect their OS preference, and developers in particular notice when a blog blinds them with a white page at 2 AM. Beyond just supporting dark mode, the system needed to handle the notoriously tricky "flash of wrong theme" problem — where server-rendered HTML briefly shows the wrong theme before JavaScript hydrates.

The task was to implement light, dark, and system (OS-following) modes with zero visual flash on page load, persisted user preferences, and clean CSS that doesn't require duplicating every style rule. The blog supports three theme modes: light, dark, and system (follows OS preference).

A technical blog's typography sets its entire visual tone. System fonts feel generic, and popular choices like Fira Code or JetBrains Mono appear on every other developer blog. I wanted a font that reinforced the terminal-inspired aesthetic while being genuinely readable for long technical prose — not just code blocks.

I chose the Terminus monospace font for its:

• Readability: Designed for long coding sessions
• Character distinction: Clear differentiation between similar characters (0/O, 1/l/I)
• Aesthetic: Technical, terminal-inspired appearance matching the blog's theme

Self-hosting with preloading ensures fast font delivery:

<link rel="preload" href="/fonts/TerminusTTF-4.49.3.woff2"
      as="font" type="font/woff2" crossorigin>

Traditional blog navigation — chronological lists, tag clouds, category pages — fails to represent how technical topics actually interconnect. A post about database optimization relates to performance profiling, which connects to observability, which ties back to system design. These relationships are inherently graph-shaped, not list-shaped. Readers browsing a flat list miss connections that could lead them to exactly the content they need.

The task was threefold: improve content discoverability by surfacing topic relationships, create a visual portfolio piece that demonstrates frontend engineering capability, and provide a homepage that's genuinely interesting rather than a static list of links. The result is an interactive 3D force-directed graph on the homepage showing relationships between blog posts, where nodes represent posts and edges represent shared concepts.

Static images of charts in technical blog posts are a missed opportunity. Readers can't zoom into dense scatter plots, rotate 3D visualizations, or hover over data points to see exact values. But embedding interactive charts introduces UX problems — chart drag gestures conflict with page scrolling, and accidentally interacting with a chart while reading is frustrating.

I needed interactive charts that stay out of the way during normal reading but become fully interactive on demand, with the ability to expand to fullscreen for detailed exploration. Interactive charts are defined in JSON and rendered with Plotly.js:

{
  "data": [{
    "type": "scatter3d",
    "x": [1, 2, 3],
    "y": [4, 5, 6],
    "z": [7, 8, 9],
    "mode": "markers"
  }],
  "layout": {
    "title": "3D Scatter Plot"
  }
}

A portfolio blog should demonstrate that the author is actively building, not just publishing static content. Visitors landing on the homepage should immediately see evidence of consistent coding activity — it builds credibility and shows the site is maintained. GitHub's contribution graph is effective at communicating this at a glance, but it's buried on a profile page most visitors won't find.

The task was to build a visible indicator of development activity directly on the homepage, with more flexibility than GitHub's single-scale yearly view. Inspired by GitHub's contribution graph, DevPulse shows my commit activity with five different time scales for different perspectives:

Technical blog posts are densely linked — to other posts, documentation, external resources. Every click takes the reader away from their current context, and the mental cost of deciding "is this link worth following?" disrupts reading flow. Readers either ignore links entirely (missing valuable context) or click them and lose their place in the original article.

The task was to let readers preview linked content without navigating away, maintaining their reading context while still providing access to referenced material. The result is hover-triggered preview popups with support for nested previews up to 10 levels deep — a reader can preview a link, then preview a link within that preview, following a chain of references without ever leaving the page.

As the number of posts grew, the table of contents and knowledge graph became insufficient for finding specific content. A reader who remembers reading about "WebGL performance" but can't recall which post it was in needs instant, typo-tolerant full-text search across all content.

Building search from scratch (inverted indices, ranking algorithms, typo tolerance) would be a massive undertaking for marginal benefit. The task was to integrate a hosted search service that provides sub-50ms results with section-level granularity, keyboard-driven UX, and minimal client-side code. Search is powered by Algolia with InstantSearch.js:

const searchClient = algoliasearch(APP_ID, API_KEY);

instantsearch({
  indexName: 'posts',
  searchClient,
  searchFunction(helper) {
    if (helper.state.query) {
      helper.search();
    }
  }
});

Every page includes comprehensive meta tags extracted from the org-mode source during the server-side loading phase:

<!-- Basic -->
<meta name="description" content="{description}">
<link rel="canonical" href="{url}">

<!-- Open Graph -->
<meta property="og:title" content="{title}">
<meta property="og:description" content="{description}">
<meta property="og:type" content="article">
<meta property="og:url" content="{url}">
<meta property="og:image" content="{image}">

<!-- Twitter Card -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="{title}">
<meta name="twitter:description" content="{description}">

Blog posts include schema.org structured data:

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Design Decisions: Building a Modern Technical Blog",
  "author": {
    "@type": "Person",
    "name": "Charlie Holland"
  },
  "datePublished": "2026-01-21",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://chiply.dev/post-design-decisions"
  }
}

This helps search engines understand content relationships.

Both are generated at build time by scanning the src/routes/[post]/ directory:

// sitemap.xml/+server.ts
export const GET: RequestHandler = async () => {
  const posts = await discoverPosts();

  const sitemap = `<?xml version="1.0" encoding="UTF-8"?>
    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
      ${posts.map(post => `
        <url>
          <loc>https://chiply.dev/${post.slug}</loc>
          <lastmod>${post.date}</lastmod>
          <priority>0.8</priority>
        </url>
      `).join('')}
    </urlset>`;

  return new Response(sitemap, {
    headers: { 'Content-Type': 'application/xml' }
  });
};

All pages are prerendered at build time:

export const prerender = true;

export const entries: EntryGenerator = async () => {
  const posts = await discoverPosts();
  return posts.map(post => ({ post: post.slug }));
};

This ensures search engines receive fully-rendered HTML.

The first layer is Vercel's built-in analytics, requiring just two lines of code to track page views and Web Vitals:

import { inject } from '@vercel/analytics';
inject();

Real User Monitoring (RUM) captures Core Web Vitals:

• LCP (Largest Contentful Paint)
• FID (First Input Delay)
• CLS (Cumulative Layout Shift)

Page views alone don't distinguish between a reader who bounced after 3 seconds and one who spent 20 minutes reading every section. Standard analytics tools track navigation but not engagement depth. I wanted to know: do readers who start a 5000-word post actually finish it?

I built custom engagement tracking to answer these questions about reading behavior:

// Track scroll depth milestones
const milestones = [25, 50, 75, 100];

const handleScroll = debounce(() => {
  const scrollPercent = (scrollTop / scrollHeight) * 100;

  milestones.forEach(milestone => {
    if (scrollPercent >= milestone && !reached[milestone]) {
      reached[milestone] = true;
      trackEvent('scroll_milestone', { depth: milestone });
    }
  });
}, 100);

Metrics tracked include:

• Scroll depth (25%, 50%, 75%, 100%)
• Time on page (active time, excluding hidden tabs)
• Read completion (>90% scroll depth)

Clarity provides heatmaps and session recordings for UX analysis:

// Secure initialization with validation
const clarityId = import.meta.env.VITE_CLARITY_ID;
if (clarityId && /^[a-zA-Z0-9]+$/.test(clarityId)) {
  const script = document.createElement('script');
  script.src = `https://www.clarity.ms/tag/${clarityId}`;
  script.async = true;
  document.head.appendChild(script);
}

I chose Buttondown for its developer-friendly API and minimal UI — it handles deliverability, unsubscribes, and confirmation emails while I just call one endpoint. Newsletter subscriptions use Buttondown's API:

// /api/subscribe/+server.ts
export const POST: RequestHandler = async ({ request }) => {
  const { email } = await request.json();

  // RFC 5321 validation
  if (!isValidEmail(email)) {
    return json({ error: 'Invalid email' }, { status: 400 });
  }

  const response = await fetch('https://api.buttondown.com/v1/subscribers', {
    method: 'POST',
    headers: {
      Authorization: `Token ${BUTTONDOWN_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ email })
  });

  return json({ success: true });
};

Buttondown handles confirmation emails, ensuring GDPR compliance and reducing spam.

The most critical defense layer, since the site dynamically renders HTML from multiple sources (org-mode exports, external link previews). All user-facing HTML is sanitized with DOMPurify using strict allowlists:

import DOMPurify from 'dompurify';

const ALLOWED_TAGS = [
  'article', 'section', 'nav', 'header', 'footer',
  'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
  'p', 'ul', 'ol', 'li', 'a', 'strong', 'em',
  'pre', 'code', 'blockquote', 'table', 'tr', 'td', 'th',
  'img', 'figure', 'figcaption', 'svg', 'path'
];

const ALLOWED_ATTR = [
  'id', 'class', 'href', 'src', 'alt', 'title',
  'aria-label', 'aria-hidden', 'role',
  'data-*', 'width', 'height'
];

export const sanitizeHtml = (html: string) => {
  return DOMPurify.sanitize(html, {
    ALLOWED_TAGS,
    ALLOWED_ATTR,
    ALLOWED_URI_REGEXP: /^(?:https?|mailto|tel):/i
  });
};

The CSP header restricts resource loading:

// hooks.server.ts
const csp = [
  "default-src 'self'",
  "script-src 'self' 'unsafe-inline' 'unsafe-eval' cdn.jsdelivr.net cdnjs.cloudflare.com",
  "style-src 'self' 'unsafe-inline' cdn.jsdelivr.net",
  "img-src 'self' data: blob: https:",
  "font-src 'self' data: cdn.jsdelivr.net",
  "connect-src 'self' api.github.com *.algolia.net",
  "frame-src 'self'",
  "object-src 'none'",
  "base-uri 'self'",
  "upgrade-insecure-requests"
].join('; ');

response.headers.set('Content-Security-Policy', csp);

Additional headers prevent common attacks:

response.headers.set('X-Frame-Options', 'SAMEORIGIN');
response.headers.set('X-Content-Type-Options', 'nosniff');
response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
response.headers.set('Permissions-Policy', 'geolocation=(), microphone=(), camera=()');
response.headers.set('Strict-Transport-Security', 'max-age=31536000; includeSubDomains');

All API inputs are validated:

// Email validation (RFC 5321 compliant)
const isValidEmail = (email: string): boolean => {
  if (typeof email !== 'string') return false;
  if (email.length > 254) return false;

  const [local, domain] = email.split('@');
  if (!local || !domain) return false;
  if (local.length > 64) return false;
  if (/\.\./.test(email)) return false;

  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
};

// URL validation
const isValidUrl = (url: string): boolean => {
  try {
    const parsed = new URL(url);
    return ['http:', 'https:'].includes(parsed.protocol);
  } catch {
    return false;
  }
};

The foundation of accessibility is semantic HTML, and org-mode's export helps here by default — headings, paragraphs, lists, and tables all use correct elements. Org-mode exports clean semantic HTML:

<article>
  <header>
    <h1>Post Title</h1>
    <time datetime="2026-01-21">January 21, 2026</time>
  </header>
  <section id="introduction">
    <h2>Introduction</h2>
    <p>Content...</p>
  </section>
</article>

Interactive elements include ARIA attributes:

<button
  aria-label="Toggle theme"
  aria-pressed={isDark}
  onclick={toggleTheme}
>
  <i class="fa-solid fa-moon" aria-hidden="true"></i>
</button>

<dialog
  role="dialog"
  aria-modal="true"
  aria-labelledby="modal-title"
>
  <h2 id="modal-title">Search</h2>
</dialog>

All functionality is keyboard accessible:

• Tab: Navigate between interactive elements
• Enter/Space: Activate buttons
• Escape: Close modals
• Cmd/Ctrl+K: Open search
• Arrow keys: Navigate search results

Modals trap and restore focus:

let previouslyFocusedElement: HTMLElement | null = null;

function openModal() {
  previouslyFocusedElement = document.activeElement as HTMLElement;
  modalElement.focus();
}

function closeModal() {
  previouslyFocusedElement?.focus();
  previouslyFocusedElement = null;
}

A skip link allows keyboard users to bypass navigation:

<a href="#main-content" class="skip-link">
  Skip to main content
</a>

Heavy components load on demand, triggered only when they enter (or approach) the viewport:

// IntersectionObserver for viewport-triggered loading
const observer = new IntersectionObserver(
  (entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        loadComponent();
        observer.unobserve(entry.target);
      }
    });
  },
  { rootMargin: '100px' }
);

Dynamic imports split the bundle:

// Only load Algolia when search opens
const loadSearch = async () => {
  const { default: algoliasearch } = await import('algoliasearch');
  const { default: instantsearch } = await import('instantsearch.js');
  // Initialize search...
};

Different resources have different cache lifetimes:

Images are optimized with:

• WebP format where supported
• Lazy loading via loading"lazy"=
• Appropriate sizing with srcset
• Placeholder aspect ratios to prevent CLS

The project uses SemVer with automated releases, where the version bump is determined entirely by commit message prefixes:

Google's release-please automates version management:

1. Conventional commits trigger Release PRs
2. PRs include changelog updates
3. Merging creates GitHub releases and tags
4. package.json version updates automatically

Changelogs are auto-generated from commit messages:

## [0.1.0] - 2026-01-21

### Features
- Add share button with social media platforms
- Add 3D knowledge graph visualization

### Bug Fixes
- Fix theme flash on page load
- Correct chart modal focus management