Static Site Generator

A static site generator (SSG) is a type of general-purpose documentation platform which embraces the principle of truth proximity, and the tenets of change reactivity and decoupled rendering in particular, by clearly separating the process of authoring documents from that of rendering them.

Some of the most popular static site generators, geared toward general documentation use cases, are:

DocOps Automation

Static site generators are the easiest to integrate with DocOps automation workflows because the input documents are regular files encoded using Markdown and can be easily generated or pre-processed, before they are made available to the static site generator. Furthermore, the same source document files can be fed into other render build pipelines for, say, ebook and paper-oriented use cases.

Static site generators also facilitate embracing the tenet of consistent layout, given that they render all documents uniformly using a default template, and ‘extra effort’ is required to break this pattern. In addition, unlike other documentation platforms, nearly all tools use off-the-shelf templating engines, which facilitates customization.

Limitations

While static site generators are the most DocOps-friendly documentation platforms in terms of headless automation use cases, they are not as aligned as wiki engines, in terms of embracing the principle of shared responsibility. Collaborative documentation efforts requires users to posses access to Git, or similar. Furthermore, adding new content requires creating file-system files and hyperlinking them manually, which is a far cry from the way a similar process works on a wiki engine.

Static site generators, because of their nature, are also typically unconcerned with the following documentation system tenets:

• Contemporary prompt - Given that the unique selling proposition of static site generators is that the rendered content can be served for free, or cheaply, using static content serving services such as GitHub Pages, Netlify, or Amazon S3, they can’t bundle a database-backed search engine (let alone a large language model) with them. This limitation, however, allows the DocOps engineer to integrate a third-party, best of breed search engine and prompt.
• Uniform addressability and flat namespace - Most static site generators recreate the underlying file system’s directory structure when rendering to HTML.
• Implicit versioning - This is left to the file system. This works well if the files are maintained using a source code management system such as Git. However, in this case, version comparison and tracking must be performed on Git; most static site generators would not decode Git’s internal file structures but look directly into the current branch only.
• Emergent structure and connected content- Renaming or moving files break links pointing to them, if using a simple text editor which does not track references. Also, many static site generators do not translate links to .md files to HTTP URIs and users are forced to use only HTTP URIs which do not work in edit mode. These two problems discourage the linking of individual words and text fragments and may lead to a documentation base characterized by long monolithic documents connected through jump-off pages or menus.
• Authoring delight - Again, static site generators are not turnkey documentation solutions; they provide an effecting render mechanism specifically for the HTML target. In this sense, static site generators are headless. The authoring experience must be addressed separately.

Other Static Site Generators

• GitBook imports Markdown (among other formats) but is offered as a cloud service, similarly to proprietary wiki engines.
• Slate is a specialized static site generator for documenting APIs.