= 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.