118 lines
5.1 KiB
Plaintext
118 lines
5.1 KiB
Plaintext
= com.jessebrault.ssg
|
|
Jesse Brault
|
|
v0.2.0
|
|
:toc:
|
|
:source-highlighter: rouge
|
|
|
|
*com.jessebrault.ssg* is a static site generator written in Groovy, giving access to the entire JVM ecosystem through its templating system.
|
|
|
|
== Overview
|
|
|
|
`ssg` has two sub-commands, `init` and `build`, one of which must be chosen when running from the command line.
|
|
|
|
NOTE: Previous versions of `ssg` contained a `watch` sub-command; this will be re-introduced in future versions in a more abstracted way that will handle not only the file system changes but also database/external events as well.
|
|
|
|
=== Sub-command: `init`
|
|
|
|
`init` is a simple command which creates the expected file and folder structure for `ssg` in the current directory. The resulting directories and file (only `ssgBuilds.groovy`) are empty.
|
|
|
|
.resulting project structure after running `init`
|
|
[plantuml, width=25%, format=svg]
|
|
----
|
|
@startsalt
|
|
{
|
|
{T
|
|
+ <&folder> (project directory)
|
|
++ <&folder> pages
|
|
++ <&folder> parts
|
|
++ <&folder> templates
|
|
++ <&folder> texts
|
|
++ <&file> ssgBuilds.groovy
|
|
}
|
|
}
|
|
@endsalt
|
|
----
|
|
|
|
However, with the `--skeleton` option (short form `-s`), a simple text, page, template, and part are generated as well. Additionally, `ssgBuilds.groovy` contains some sample configuration for the site.
|
|
|
|
.resulting project structure after running `init --skeleton`
|
|
[plantuml, width=25%, format=svg]
|
|
----
|
|
@startsalt
|
|
{
|
|
{T
|
|
+ <&folder> (project directory)
|
|
++ <&folder> pages
|
|
+++ <&file> page.gsp
|
|
++ <&folder> parts
|
|
+++ <&file> head.gsp
|
|
++ <&folder> templates
|
|
+++ <&file> hello.gsp
|
|
++ <&folder> texts
|
|
+++ <&file> hello.md
|
|
++ <&file> ssgBuilds.groovy
|
|
}
|
|
}
|
|
@endsalt
|
|
----
|
|
|
|
=== Sub-command: `build`
|
|
|
|
`build` encompasses the primary functionality of `ssg`. It accepts two options:
|
|
|
|
* `-b | --build`: The name of the build to execute. This option can be specified multiple times to specify multiple builds. The default is only one build, the `default` build; if any builds are specified, `default` is ignored (unless it is specified by the user, of course).
|
|
* `-s | --script | --buildScript`: The path to the build script file to execute. This may only be specified once. The default is `ssgBuilds.groovy`.
|
|
|
|
.Examples of using `build`.
|
|
[source,shell]
|
|
----
|
|
ssg build # <1>
|
|
ssg build -b production # <2>
|
|
ssg build -b production -b preview # <3>
|
|
ssg build -s buildScript.groovy -b myBuild # <4>
|
|
----
|
|
<1> Builds the `default` build using the build script `ssgBuilds.groovy`.
|
|
<2> Builds the `production` build using the build script `ssgBuilds.groovy`.
|
|
<3> Builds both the `production` and `preview` builds using the build script `ssgBuilds.groovy`.
|
|
<4> Builds the build named `myBuild` using the build script named `buildScript.groovy`.
|
|
|
|
== The `default` Build
|
|
|
|
If `init` is used to generate the project structure (or the structure is created manually by the user), the project structure matches the expected layout for the `default` build which is automatically included in all available builds. With no further specification, it will generate HTML pages from the given Texts, Pages, Templates, and Parts into the `build` directory.
|
|
|
|
== Program Execution
|
|
|
|
When `ssg` is invoked with a build file (such as `ssgBuilds.groovy` in the working directory), the following will occur:
|
|
|
|
. The build script is evaluated and executed, producing a collection of `Build` domain objects.
|
|
. For each `Build` object:
|
|
.. TaskFactories are configured using the configuration closures in the build file.
|
|
.. TaskFactories produce Tasks, each containing all the information needed to complete the task, except for a `TaskCollection` containing all tasks.
|
|
.. Tasks are given a `TaskCollection` and then run in parallel.
|
|
|
|
== The Build Script
|
|
|
|
The build file is evaluated as a script whose base class is `BuildScriptBase`. The script instance fields are mutated by its execution, and it (the script) is run exactly once. Each call to `build` in the script produces a new `Build` domain object which is saved by the script. The `Build` object contains all necessary data for executing that particular build:
|
|
|
|
* `name`: the name of the build, in order to invoke it from the command line.
|
|
* `outDir`: the destination directory of the build, such as `build`.
|
|
* `siteSpec`: a domain object containing the following properties which are available in all templated documents processed by the build:
|
|
** `siteTitle`: a string.
|
|
** `baseUrl`: a string, denoting the base url of the whole site, such as `http://example.com`, used in building absolute urls in the various templated documents.
|
|
* `globals`: a `Map<String, Object>` containing any user-defined globals for that build.
|
|
* `taskFactories: Closure<Void>`: a configuration block for taskFactories.
|
|
// TODO: include what the `allBuilds` block does
|
|
|
|
The `Build` object also contains all the necessary configuration clousres to configure the various instances of `TaskFactory` that are used to produce instances of `Task`.
|
|
|
|
== Some Examples
|
|
|
|
.Tag Builder
|
|
[source,groovy]
|
|
----
|
|
def a = tagBuilder.a(href: 'hello.html', 'Hello!') // <1>
|
|
assert a == '<a href="hello.html">Hello!</a>'
|
|
out << a // <2>
|
|
----
|
|
<1> Create an <a> tag.
|
|
<2> Output the tag in the current script block. |