dohwi.com

Architecture and engineering details of dohwi.com, an independently designed and operated static technical blog and portfolio platform built with Astro and TypeScript without external CMS dependencies. The project encompasses an equal-footing multilingual architecture, build-time static full-text search, Satori-powered dynamic OG image rendering, and a self-hosted Nginx container deployment pipeline.

Item	Details
Site URL	https://dohwi.com
Key Stack	Astro, TypeScript, Tailwind CSS, MDX, Pagefind
Features	KO/EN i18n routing, client-side static search, Satori dynamic OG generation, RSS feed, sitemap
Deployment	Docker container and self-hosted Nginx (dist_tmp → rsync build pipeline)

---

Why I Built It

Commercial blogging services and heavy full-stack frameworks often impose rigid layout constraints or ship unnecessary client-side JavaScript runtimes for reading-focused document sites. As articles and project records grow, orchestrating accurate multilingual metadata and search capabilities without relying on recurring external SaaS tools becomes equally challenging.

• Eliminating Runtime Overhead: Since content consumption is paramount, client JS is kept minimal to achieve instant initial page loads.
• Complete Multilingual Control: Supporting Korean and English as first-class citizens within a symmetrical repository structure rather than segregated subdomains.
• Self-hosted Independence: Decoupling the platform from PaaS lock-in by packaging static artifacts into lightweight Docker and Nginx environments.

---

Challenges

1. Static Multilingual (i18n) Routing and Metadata Consistency
   • Pairing ko and en files under content directories (contents/blog, contents/projects) while strictly synchronizing canonical URLs, hreflang alternates, and Open Graph tags without desynchronization.
2. Full-Text Search Without a Dedicated Backend
   • Delivering instantaneous multilingual search across static files without operating an Elasticsearch cluster or paid third-party search APIs.
   • Managing language-scoped filtering (lang:ko, lang:en) and handling modal UI lifecycles (instance creation/teardown, lazy script loading) directly.
3. Build-Time Indexing and Atomic Deployment Integrity
   • Because pagefind indexes generated static artifacts on disk, build outputs and search indices needed to switch atomically to prevent serving inconsistencies during rebuilds.

---

Design Decisions

• Strict Schema Validation via Content Collections
  • Configured Astro’s glob loader with Zod schemas in src/content.config.ts to enforce lang, translationKey, and metadata contracts at compile time.
• Client-Side Pagefind Search with Locale Scoping
  • Configured SearchModal.astro to lazy-load Pagefind assets on user interaction and bound DOM filters (data-pagefind-lang, data-pagefind-filter) to restrict queries to the active locale.
• Automated OG Pipeline via Satori & Resvg
  • Synthesizes SVGs from article/project frontmatter at build time and rasterizes them to PNGs (src/lib/og.ts), providing customized, cohesive branding without third-party graphics generation services.
• Staged Build and rsync Deployment Pipeline
  • Scripted the build workflow (astro build --outDir dist_tmp && pagefind --site dist_tmp; rsync -a --delete --exclude='.prerender' dist_tmp/ dist/) to ensure the live document root is updated atomically only after indexing finishes.

Projects grid with a shared language, tag, and link system.

---

Next Improvements

To ensure sustained reliability in production, the following items identified during deployment audits are being addressed in phases:

• Resilient Pagefind Retries: Strengthening fallback logic to detect transient network interruptions during search asset fetching and attempt safe retries.
• Image Layout Stability: Standardizing container bounding boxes and aspect ratios to prevent Cumulative Layout Shift (CLS) during responsive viewport transitions.
• Atomic Release Strategy: Integrating symlink switching into the artifact release process to provide stronger guarantees for zero-downtime deployments.

---

Retrospective

Article detail view that combines a table of contents with an OG visual.

Building dohwi.com demonstrated that pairing static site generation with intentional design—covering multilingual SEO, client search lifecycles, and container caching policies—can yield an exceptionally robust platform. Stripping away unnecessary runtime layers and focusing on core web standards created an efficient, long-term foundation for technical publishing.