resolves # 3923: static site generator page #3924
Conversation
|
|
||
| Jekyll has some native blog support, although this does not affect it's use of Asciidoctor. | ||
|
|
||
| === xref:maven-tools::index.adoc[Maven-tools] |
There was a problem hiding this comment.
Do we want to mention maven specifically, maybe better a generinc last section like "Build tools" explainig the shortcomings of those in general (maven, gradle, ant, gulp, etc)?
For name some example content "they help to aggregate and build sets of sources, manage resources(images, etc) locations, but not handle internal links, navigation (menus), etc."
There was a problem hiding this comment.
Hmmmm.... This was intended to list the SSGs specifically associated with Asciidoctor. Are there any other build tools that provide an attempt at Asciidoctor integration that integrates with some sort of site building behavior?
How about adding a phrase like "in common with other build tools that can incidentally generate sites,...."? (I haven't tried to fit that in anywhere yet.)
There was a problem hiding this comment.
I would make the case that the Gradle plugin does as well. It's not a 1-to-1 match with the Maven site generation, but it can be be effectively used for this purpose.
There was a problem hiding this comment.
I've investigated the Gradle plugin a bit and added a paragraph.... I'd like the maven tools and gradle plugin maintainers to review in case I've missed something obvious.
| @@ -0,0 +1,94 @@ | |||
| = Static Site Generators | |||
|
|
|||
| Asciidoctor fundamentally converts one source document into one output document. | |||
There was a problem hiding this comment.
I like the intro structure:
- Context
- Problem
- Solution
| 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? |
There was a problem hiding this comment.
We should either use "Static Site Generator" everywhere or use "standard casing" here since the term is used in a section title
There was a problem hiding this comment.
I'm not sure what "standard casing" is. Except for the doctitle, I've changed to lowercase 'static site generator' everywhere and the only 'SSG' is after the first occurrence.
There was a problem hiding this comment.
Sorry, the right term seems to be sentence case:
Sentence case is the conventional way of using capital letters in a sentence or capitalizing only the first word and any proper nouns.
| == What does a Static Site Generator (ssg) do? | |
| == What does a static site generator do? |
|
Maybe we should add a section to explain why Asciidoctor (or at least plain-text format) works great with static site generators? Not sure where it would fit though 😅 |
|
|
||
| == 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. |
There was a problem hiding this comment.
I think that's too much detail for one sentence, maybe:
"creates (or generates) a set of static assets which can be served by a web server)".
I feel like the "virtual/concrete file system" part is too specific/technical.
There was a problem hiding this comment.
yes....
A static site generator gathers sources from one or more locations, transforms them, and organizes the resulting static assets into a complete site ready for deployment directly to a web server.?
There was a problem hiding this comment.
Yes that's better!
Still a bit convoluted but let's hear what others think 😉
| == 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. |
There was a problem hiding this comment.
Maybe the specific example about Maven should be inside parenthesis?
| 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? |
There was a problem hiding this comment.
| == What does a Static Site Generator (ssg) do? | |
| == What is a static site generator? |
There was a problem hiding this comment.
I think the question of what a SSG is is too philosophical for me to answer, and all I could say was "it's something that does X", whereas if I ask what a SSG does, I can just start off explaining X.
| == 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. |
There was a problem hiding this comment.
| 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. | |
| Usually the content is embedded in "outer html" supplied by a template, but it can also be further transformed, as done by nav file processing in Antora. |
There was a problem hiding this comment.
I don't think we should mention Antora at this point. If you are not familiar with SSG you are probably not familiar with Antora so this does not help.
There was a problem hiding this comment.
I agree, though I think it would be fair to say somewhere that AsciiDoc is usually use for the main page content, but can be used in other, novel ways by the SSG.
There was a problem hiding this comment.
Yes that's a good idea.
What you suggested could replace this sentence:
"AsciiDoc is usually use for the main page content, but can be used in other, novel ways by the SSG."
We could even mention that some SSGs are using AsciiDoc to define navigation between pages.
There was a problem hiding this comment.
How about...
"Asciidoctor is used in static site generators to transform source documents in AsciiDoc into HTML.
Usually this is embedded in "outer HTML" supplied by a template to produce an output page.
Some static site generators also use specific AsciiDoc input for novel purposes, such as to generate navigation resources."
|
|
||
| === Unaffiliated site generators | ||
|
|
||
| A list of site generators using Asciidoctor in some capability is maintained https://gist.github.com/briandominick/e5754cc8438dd9503d936ef65fffbb2d[here]. |
There was a problem hiding this comment.
I'm a little hesitant about linking to this gist, though I don't have a good alternative suggestion. So perhaps it's the best resource we have. Perhaps we can say this is a community-maintained reference.
djencks
force-pushed
the
issue-3923-ssg-page
branch
from
9994ccc
to
185b9b7
Compare
First draft...