= 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 currently functioning sub-commands, `init` and `build`, one of which must be chosen at the command line.

NOTE: Previous versions of `ssg` contained a `watch` 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 simply 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`


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