The Art and Engineering of Building Custom Static Site Generators

In the landscape of web publishing, static site generators have emerged as elegant solutions for creating fast, secure, and maintainable websites. While many developers readily adopt established tools like Hugo, Jekyll, or Eleventy, there exists a compelling alternative path: building your own static site generator. This approach, as demonstrated by one developer's journey from a simple Makefile to a sophisticated sub-100ms build system, offers unique technical insights and practical benefits that deserve careful consideration.

At its core, a static site generator must perform several fundamental operations: reading plaintext content, incorporating reusable HTML components, managing article metadata, parsing content into structured formats, applying quality checks, generating navigational elements, transforming content to HTML, producing syndication feeds, and assembling the final pages. The beauty of this architecture lies in its simplicity—each component can be developed and optimized independently, creating a system where the whole is greater than the sum of its parts.

The author's technical journey reveals several critical architectural decisions that contributed to exceptional performance. Initially starting with a basic Makefile that concatenated header, markdown content, and footer, the system evolved through careful optimization to achieve remarkable build times: approximately 120ms for clean builds and 50ms for incremental builds. This performance is particularly noteworthy when compared to many established static site generators that often require several seconds or even minutes for similar operations.

One of the most significant technical insights involves the intelligent use of Git for article metadata retrieval. Rather than querying Git for each article individually—an approach that leads to the N+1 query problem—the author employs a single, comprehensive command: git log --format='%aI' --name-status --no-merges --diff-filter=AMDR --reverse '*.md'. This approach retrieves all necessary metadata in one operation, dramatically reducing overhead. The periodic execution of git gc --aggressive --prune=now further optimizes Git's performance, demonstrating how understanding the underlying tools can lead to system-wide improvements.

The parsing architecture represents another cornerstone of the system's success. By working with Abstract Syntax Trees (ASTs) rather than raw markdown, the author gains complete control over content transformation. This approach enables sophisticated features like syntax highlighting at build time, precise linting rules, and flexible HTML generation. The AST serves as a universal intermediate representation that can be processed for multiple purposes—HTML generation, table of contents creation, search indexing, and quality assurance—without repeatedly parsing the source content.

The linting system exemplifies the power of this approach. Operating on the AST, it can enforce various quality standards: detecting invalid links between markdown and HTML pages, ensuring code snippets specify their language for proper syntax highlighting, maintaining consistent style for units (preferring "1 KiB" over other variants), and enforcing heading hierarchy rules. Additional potential lints mentioned—such as prohibiting single-element lists or requiring alt text for images—highlight how the AST enables comprehensive content quality assurance that would be significantly more complex to implement at the string level.

Table of contents generation demonstrates elegant algorithmic thinking. Rather than building a hierarchical tree of titles, the author performs a linear scan through a flat array of title elements, tracking depth changes and appropriately nesting HTML list elements. This approach, while seemingly simple, avoids unnecessary allocations and complexity while maintaining clean, readable code. The handling of duplicate titles through counters ensures proper linking even when articles contain sections with identical names.

The search functionality implementation reveals an important lesson about premature optimization. Initially using a trigram-based search index, the author discovered that at their scale, a simple linear search performed adequately (<1ms) and required minimal data transfer. This realization underscores a broader principle: modern hardware capabilities often make straightforward solutions viable, eliminating the need for complex data structures and algorithms for many use cases.

The live reloading system, built with Server-Sent Events (SSE) rather than WebSockets, demonstrates thoughtful consideration of communication patterns. The implementation, approximately 100 lines of code, efficiently watches file system changes and broadcasts updates to connected clients with minimal overhead. The conditional activation of live reloading (only locally, not on GitHub Pages) shows awareness of deployment contexts and user experience considerations.

Caching represents another critical optimization strategy. By using a hash of inputs as keys and storing generated outputs in memory, the system avoids redundant work while maintaining consistency by always writing files to disk. This approach leverages the principle of pure functions—where identical inputs always produce identical outputs—to enable safe incremental builds. The author wisely notes that caching should address genuine bottlenecks rather than serve as a band-aid for general slowness, emphasizing the importance of identifying and optimizing the true performance constraints.

The implementation of light and dark mode through CSS's light-dark() function showcases modern web capabilities. By specifying both color variants and allowing the browser to handle detection and application, the system provides a seamless user experience with minimal code complexity. This approach respects the browser's native capabilities while providing manual override options for user preference.

Beyond the technical implementation, the author draws an insightful parallel between static site generators and compilers. Both involve parsing source code into abstract representations, applying transformations, enforcing rules, and generating output. This perspective reveals the fundamental principles that underpin many transformation systems, regardless of their specific domain.

The value proposition of building a custom static site generator extends beyond technical performance. The author notes that the entire system comprises approximately 1.5k lines of code, suggesting that such an endeavor is accessible to developers with intermediate skills. More importantly, the process offers rich learning opportunities in areas like AST processing, caching strategies, real-time communication, and performance optimization—knowledge that transfers to many other domains of software development.

However, this approach is not without considerations. For projects with limited time constraints, teams requiring rapid deployment, or those needing extensive ecosystems of plugins and themes, established static site generators may offer more immediate value. The decision to build versus buy should consider factors such as project requirements, team expertise, maintenance burden, and the specific performance needs of the application.

The author's experience also highlights an important philosophical stance: modern computers are capable of remarkable performance, and many tools fail to leverage this potential adequately. This perspective challenges developers to question established tools and consider whether custom solutions might better serve their specific needs, particularly when performance and control are paramount.

In conclusion, building a custom static site generator represents a compelling intersection of technical craftsmanship and practical problem-solving. The journey from a simple Makefile to a high-performance system demonstrates how thoughtful design, algorithmic efficiency, and careful optimization can create tools that outperform established alternatives. While not suitable for every project, this approach offers significant benefits for developers seeking maximum performance, complete control over their publishing workflow, and opportunities to deepen their technical understanding. As web publishing continues to evolve, the principles demonstrated in this implementation—efficient data structures, intelligent caching, and thoughtful architecture—will remain valuable regardless of the specific tools employed.