Ask HN Digest Weekly HN signal

When selecting a static site generator (SSG) for a documentation portal, several key factors come into play, including Markdown support, fast build times, flexible deployment, and budget constraints. A particularly intriguing challenge for many is the desire for robust search functionality without relying on client-side JavaScript.

Top Static Site Generator Recommendations

A diverse range of SSGs are highly recommended, each offering unique strengths for documentation sites:

  • Lume: A JavaScript-based SSG known for its flexibility and plugin ecosystem. While it offers search plugins, the "no-JS search" requirement remains a point of discussion for complex implementations.
  • Hugo Book: A specialized theme built on the popular Hugo SSG, praised for its ease of use in creating documentation sites. Hugo itself is renowned for its blazing-fast build speeds, making it ideal for large projects.
  • Starlight (Astro): This generator, part of the Astro ecosystem, allows for comprehensive configuration via astro.config.js and leverages Markdown for content, offering a modern approach to static site development.
  • Middleman: A long-standing, robust Ruby-based framework that provides extensive features and supports both HAML and Markdown for content creation.
  • 11ty (Eleventy): A flexible JavaScript-based SSG valued for its simplicity, ability to work with various templating languages, and strong community support.
  • Nikola: A Python-based SSG that provides another comprehensive and open-source option for generating static websites.
  • Deepsite: Noted for its capability to generate extremely fast pages using only HTML and CSS. It can also smoothly integrate jQuery and JavaScript when required for specific functionalities.
  • Mintlify & Gitbook: These are often highlighted as more comprehensive, opinionated documentation platforms that can generate static sites and frequently include integrated search features, often with free tiers available.

The "Search Without JavaScript" Conundrum

The requirement for search functionality without JavaScript emerges as a significant point of debate and clarification. Experts generally explain that achieving dynamic, in-site search on a purely static site without any client-side scripting or a backend system is inherently difficult, if not practically impossible, for a truly integrated experience.

Practical solutions and insights for this challenge include:

  • External Search Engines: The most common and effective workaround is to direct users to perform a site-specific search using major search engines. For example, instructing users to type site:yourdomain.com [keyword] into Google or DuckDuckGo offloads the entire indexing and search logic to these powerful external services.
  • External Search Providers: Utilizing third-party search services (like Algolia or similar providers). While these often involve their own backend indexing and might require some client-side JavaScript for integration, they completely abstract away the complexity of managing a search infrastructure for the site owner.
  • Backend Necessity: For truly custom, deeply integrated search functionalities, a dedicated backend indexing service is typically required. While this moves beyond a purely "static" definition, it represents a realistic component for advanced search needs on a larger scale.
  • Client-Side JS for Simple Searches: It's important to note that even what appear to be "simple static site searches" on the client side often involve JavaScript. This JS typically filters or displays results from a pre-indexed data file (e.g., a large JSON file) that is generated during the build process.

Deployment and Budget Considerations

All recommended static site generators are open-source and free to use, perfectly aligning with a $0 budget. Deployment on platforms like GitHub Pages is a natural fit for static sites, offering free hosting. Other popular and free options, such as Cloudflare Pages, are also excellent choices. Markdown support is a universal feature across virtually all modern static site generators, ensuring content creation remains simple, intuitive, and portable. Furthermore, fast build times are a significant advantage of SSGs, with many, particularly tools like Hugo, capable of building extensive sites in mere seconds.

Get the most interesting Hacker News discussions delivered as a weekly brief.