static site generator page

docs/antora.yml

@@ -34,3 +34,4 @@ nav:
 - modules/ROOT/nav-lang.adoc
 - modules/ROOT/nav-errors.adoc
 - modules/migrate/nav.adoc
+- modules/ROOT/nav-ssg.adoc

docs/modules/ROOT/nav-ssg.adoc

@@ -0,0 +1 @@
+* xref:static-site-generators.adoc[]

docs/modules/ROOT/pages/static-site-generators.adoc

@@ -0,0 +1,94 @@
+= Static Site Generators
+
+Asciidoctor fundamentally converts one source document into one output document.
+To convert more than one document, you need some amount of infrastructure.
+Simple situations may find it convenient to use built-in Asciidoctor capabilities or scripts, but are unlikely to be appropriate for any but the smallest sites.
+Static site generators organize the conversion of multiple source documents into a functioning static web site.
+
+== What does a Static Site Generator (ssg) do?
+
+A static site generator (ssg) gathers sources from one or more locations, transforms them, and writes the results into a file system, concrete or virtual, ready for deployment to a web server.
+Typical source locations are the local file system, remote Git repositories, and artifact repositories such as those used by Maven, e.g. Nexus.
+The most common transformations are converting source from text representations such as AsciiDoc or Markdown to HTML and embedding the results in additional HTML markup to supply a site theme and navigation.
+Other transformations include generating diagram images from text sources and optimizing images.
+Mavigation resources can be generated from explicit source or automatically.
+
+Some static site generators include features specifically targeted to particular website styles such as blogs.
+
+== What is Asciidoctor's role in static site generation?
+
+Asciidoctor is used in static site generators to transform source documents in Asciidoc into html.
+Most usually this is simply embedded in "outer html" supplied by a template, but it can also be further transformed, as done by nav file processing in Antora.
+It would also be possible to utilize the Document Object Model block structure generated before conversion to HTML, but this is likely to tie an SSG too tightly to AsciiDoc.
+
+From this point of view, Asciidoctor should not be concerned in any way with file system references, treating them as uninterpreted tokens and delegating interpretation to the SSG.
+Since this is not currently the case, a variety of workarounds are often needed to produce correct outputs from correct inputs.
+
+AsciiDoc natively has (page) attributes which may be supplied from the code calling Asciidoctor or set in the document header or body.
+Site generators have information about the context of page conversion and can translate this information into contextual page attributes, thus providing the ability to show page context in the transformed page itself.
+On the other hand, the template system wrapping the embedded HTML produced by Asciidoctor generally has some concept of variables to display in the template. Usually certain Asciidoc attributes defined in the header are made available as such "page variables".
+
+== Static site generators associated with the Asciidoctor project
+
+=== https://docs.antora.org[Antora]
+
+Antora (written in JavaScript/Node, using Asciidoctor.js) has the distinction of being the only static site generator constructed originally to natively support Asciidoctor.
+It is designed around a processing pipeline with well-defined stages.
+While there are several ways it could be extensible solely through configuration, currently modifying or extending it involves a straightforward code modification of the pipeline and adding a stage or modifying one of the existing stages.
+
+Sources can be in any number of Git repositories or local file system trees.
+These are combined, independent of the source, into components which end up as top-level divisions of the generated site.
+Source trees are laid out in a logical arrangement that well separates concerns and the source arrangement is mapped to the site structure.
+
+Antora supplies Asciidoctor extensions with extensive context information about the file being processed and the set of source files.
+
+AsciiDoc pages transformed to embeddable HTML are wrapped using resources, including templates, from a separately constructed UI bundle.
+Header attributes beginning with `page-` are made available as variables in the template system.
+The UI bundle may contain additional Javascript helper functions that can access variables from the page as well as global context information.
+
+Antora does not support multi-language sites and support is not amenable to implementation through an extension.
+
+Antora does not support blog-like sites natively but support can easily be added through the extension mechanism.
+
+=== xref:jekyll-integration::index.adoc[Jekyll integration]
+
+The Asciidoctor Jekyll integration (Ruby) consists of a Jekyll plugin that uses Asciidoctor to transform source to HTML.
+
+Jekyll supports sources from a single file system tree.
+There is limited location mapping support using a `permalink` page variable.
+
+Layout templates, in the `Liquid` template system, are part of a Jekyll site project.
+Header attributes beginning with `page-` are made available to the template system.
+
+Jekyll does not support multi-language sites in any obvious way.
+
+Jekyll has some native blog support, although this does not affect it's use of Asciidoctor.
+
+=== xref:maven-tools::index.adoc[Maven-tools]
+
+Maven is a very flexible build system and the maven-tools project allows use as a somewhat limited site generator in several ways.
+However, it appears that all uses are page-by-page with no possibility of communicating information about the set of pages.
+
+Using suitable maven plugins it's possible to pull sources in as artifacts from a maven repository.
+
+There appears to be no way to use document header attributes as template variables.
+
+=== https://github.com/middleman/middleman-asciidoc[Middleman integration]
+
+The Asciidoctor Middleman integration (Ruby) consists of a Middleman plugin that uses Asciidoctor to transform source to HTML.
+
+Configuration of Middleman is done through ruby scripting.
+
+Middleman supports sources from a single file system tree.
+It is possible to install an extension providing limited location mapping support using a `permalink` page variable.
+
+Layout templates are part of a Middleman site project.
+Header attributes beginning with `page-` are made available to the template system.
+
+Middleman does not support multi-language sites in any obvious way.
+
+Middleman has some native blog support, although this does not affect it's use of Asciidoctor.
+
+=== Unaffiliated site generators
+
+A list of site generators using Asciidoctor in some capability is maintained https://gist.github.com/briandominick/e5754cc8438dd9503d936ef65fffbb2d[here].