[Memorandum] Architectural Decisions and Considerations When Creating This Blog

📅 Created: 2023/01/01, Updated: 2023/04/08 ⏱️ Estimated reading time ~6 mins (1,115 words)

A comprehensive memorandum covering static vs dynamic site choices, hosting platform evaluation, custom Pandoc SSG architecture, Confluence-inspired UI design, and multilingual SEO.

Table of Contents

(Consideration 1) Static Site vs. Dynamic Site?
1. Differences Between Static and Dynamic Sites
(Consideration 2) Choosing a Static Site Hosting Platform
(Consideration 3) Choosing a Static Site Generator
(Consideration 4) Custom UI & Information Design
(Consideration 5) SEO Strategy & Best Practices
Summary

(Consideration 1) Static Site vs. Dynamic Site?

Evaluating whether a static site generator or a dynamic CMS aligns better with your technical requirements is a critical architectural decision when building a website.
The choice between these two paradigms fundamentally impacts feature set, developer experience, maintainability, scalability, and security posture.

Differences Between Static and Dynamic Sites

Static Site
- Composed purely of pre-rendered static assets (HTML, CSS, JavaScript, media files). Making content changes requires rebuilding or editing files directly.
- Ideal for technical documentation, personal blogs, and informational sites where content remains relatively consistent and real-time user-specific database writes are not required.
Dynamic Site
- Renders content on-the-fly via server-side runtimes, databases, and application frameworks upon every HTTP request.
- Ideal for interactive applications, multi-tenant collaboration platforms, e-commerce, or scenarios involving frequent real-time user interactions.
Below is a comparison of pros and cons between static and dynamic architectures. High-priority criteria are italicized.

Advantages of Static Sites

Fast page load speeds and superior user experience (TTFB / Core Web Vitals).
No compute load on origin servers, easily scaling to high traffic spikes via CDN caching.
Stable content delivery with near-zero downtime or server crashing risks.
Solid security posture with minimal attack surface (no direct database injection or backend vulnerabilities).
Extremely low running and hosting costs compared to dynamic server instances.

Disadvantages of Static Sites

Content updates require running a build/deploy pipeline.
Inability to execute arbitrary backend logic without client-side APIs, limiting interactive server-side workflows.
Unsuitable for complex applications requiring transactional database writes or personalized server sessions.

Advantages of Dynamic Sites

Rich real-time interactivity facilitating active user communication and community features.
Easy content editing directly from browser GUIs backed by relational or document databases.
High extensibility with dynamic plugins and on-demand server-side scripting.

Disadvantages of Dynamic Sites

Slower page response times and potential degradation of user experience without aggressive caching.
Heavy server and database load, incurring higher infrastructure and operations costs.
Continuous security maintenance (patching CMS vulnerabilities, SQL injections, CVEs).

While dynamic sites make cross-cutting features like tagging and search simpler to implement, a static site architecture was chosen to eliminate maintenance overhead and keep operational costs near zero.
Reference:
- Differences Between Static and Dynamic Sites, Pros and Cons | Xserver Business

(Consideration 2) Choosing a Static Site Hosting Platform

Deploying a static site requires reliable storage and CDN distribution infrastructure.
While Google Cloud’s Firebase Hosting was the primary candidate due to familiarity with GCP, alternative platforms were systematically evaluated.
According to Comparing Static Site Hosting Platforms | JavaScript Notice , the leading hosting providers include:

Netlify
Vercel
Firebase Hosting
Cloudflare Pages
GitHub Pages
GitLab Pages

Evaluated across four key criteria: “Edge CDN PoP in Japan”, “Automated deployment via GitHub / Cloud Build”, “Sufficient free tier quota”, and “Permitted commercial usage”.

Hosting Service	Japan CDN PoP	GitHub / Cloud Build Deploy	Generous Free Tier	Commercial Use
Netlify	×	⚪︎	⚪︎	⚪︎
Vercel	⚪︎	⚪︎	⚪︎	×
Firebase Hosting	⚪︎	⚪︎	⚪︎	⚪︎
Cloudflare Pages	⚪︎	⚪︎	⚪︎	⚪︎
GitHub Pages	⚪︎	×	⚪︎	×
GitLab Pages	⚪︎	×	⚪︎	?

Firebase Hosting and Cloudflare Pages emerged as the top contenders.
While Cloudflare Pages offered compelling edge-worker features as detailed in Cloudflare Pages vs Firebase Hosting | Bejamas , Firebase Hosting was selected because it leverages our existing Google Cloud account infrastructure, seamlessly integrates with Google Analytics, and natively connects with Cloud Build pipelines.

(Consideration 3) Choosing a Static Site Generator

Static site generators (SSGs) compile source markup (Markdown, AsciiDoc) and templates into production-ready static assets.
Three representative static site generators were evaluated:
The initial intention was to adopt Hugo to minimize setup overhead.
However, finding an existing theme closely matching an Atlassian Confluence documentation aesthetic proved difficult. Consequently, a custom Python-driven build pipeline utilizing Pandoc was developed.

Jekyll Pros

Native GitHub Pages integration.
Intuitive templating via Liquid and Markdown.
Rich plugin ecosystem.

Jekyll Cons

Ruby environment management and slower build times on large sites.

Hugo Pros

Extremely fast compilation speed written in Go.
Clean separation of themes and content.
Straightforward Markdown authoring workflow.

Hugo Cons

Go templating syntax learning curve and comparatively fewer specialized community themes.

Gatsby Pros

Powerful GraphQL data layer and rich React component ecosystem.
Vast plugin library integrating headless CMS backends.

Gatsby Cons

High architectural complexity, dependency bloat, and steep learning curve.

(Consideration 4) Custom UI & Information Design

Pandoc transforms documents across formats (Markdown, HTML, PDF, Word). By specifying custom HTML templates with the --template flag, static pages can be formatted with custom layouts and CSS styling.
- Pandoc User’s Guide - Templates

Developed using Python and JavaScript to replicate the clean navigation of Atlassian Confluence space sidebars, enabling users to jump between categories and posts effortlessly.
- Reference: Atlassian Confluence Space Sidebar Documentation

Table of Contents (ToC)

Implemented a Python script to parse HTML heading tags ( h2 , h3 ) and dynamically generate an interactive table of contents.
- Reference: DevelopersIO - Generating Table of Contents from HTML Headings via Python

Syntax Highlighting for Code Blocks

Integrated Prism.js with the “Tomorrow Night” theme and custom CSS color adjustments.
- Reference: Prism.js Official Site
- Language bundles include Bash, Python, Docker, YAML, JSON, Git, and Markdown.

Site Search

Integrated Google Custom Search Engine (CSE), providing powerful search capabilities across all indexed blog pages without requiring an in-memory search server.

Favicon

Generated using GIMP and resized via online favicon tools (512x512 down to 256x256, 32x32, 16x16) to ensure crisp rendering across desktop and mobile devices.

(Consideration 5) SEO Strategy & Best Practices

Search Engine Optimization (SEO) ensures that technical articles rank well in search engine results pages (SERPs) and reach developers seeking solutions.

1. Multilingual & Global SEO

Initially focused on Japanese readership, the site transitioned to a bilingual (English / Japanese) architecture to reach a wider global engineering audience.
Configured proper lang attributes on the <html> root and implemented reciprocal <link rel="alternate" hreflang="..."> tags to help Google deliver the correct localized page.
Deployed distinct XML sitemaps ( sitemap.xml and sitemap_en.xml ) for comprehensive search crawler discovery.

2. Image Optimization

Targeted an optimal content width of 786px with responsive dimensions.
Utilized JPG for complex photographic media and compressed PNG/SVG for technical architecture diagrams.
Continuously monitored Google PageSpeed Insights to minimize Core Web Vitals layout shifts (CLS) and ensure rapid Largest Contentful Paint (LCP).

3. Semantic HTML & Tag Optimization

Preserved proper heading hierarchies and leveraged custom Open Graph Protocol (OGP) meta tags (title, description, image, URL) to optimize social card previews across X (Twitter) and Slack.
Streamlined navigational structure into a single semantic <nav> container for clean screen-reader accessibility and crawlability.

Equipped each post with quick social share buttons (X, Hatena Bookmark, and native URL copy) to encourage developer syndication and discussion.

5. Permalink Optimization

Standardized clean, alphanumeric permanent slugs to prevent URL percent-encoding issues and safeguard crawl indexing integrity.

Summary

By combining static site simplicity (Pandoc + Python) with Firebase Hosting and automated Cloud Build CI/CD, the blog achieves near-zero running costs, sub-second load times, and rock-solid reliability across both Japanese and English audiences.