Builds reference

Overview

A build is a set of rendered HTML files and their associated stylesheets, scripts, images, and other files.

Example

 1$ hyperctl build -c site.yaml
 2build "74df6813-ca02-4794-9942-06f5e247ec15" starting
 3website "site.yaml" load
 4theme "theme.json" warning: open theme.json: no such file or directory
 5asset "static/styles.css" discovered
 6data "data/nav.yaml" loading
 7page "content/index.md" loading
 8page "content/blog/hello-again/index.md" loading
 9page "content/about/index.md" loading
10page "content/blog/hello-world/index.md" loading
11page "content/blog/index.md" loading
12tag "blog" loading
13copying "static/styles.css" to "builds/74df6813-ca02-4794-9942-06f5e247ec15/styles.css"
14writing 1615 bytes to builds/74df6813-ca02-4794-9942-06f5e247ec15/tags/blog/atom.xml
15writing 3323 bytes to builds/74df6813-ca02-4794-9942-06f5e247ec15/blog/atom.xml
16writing 2590 bytes to builds/74df6813-ca02-4794-9942-06f5e247ec15/about/index.html
17writing 2421 bytes to builds/74df6813-ca02-4794-9942-06f5e247ec15/tags/blog/index.html
18writing 2420 bytes to builds/74df6813-ca02-4794-9942-06f5e247ec15/blog/hello-world/index.html
19writing 2392 bytes to builds/74df6813-ca02-4794-9942-06f5e247ec15/index.html
20writing 3587 bytes to builds/74df6813-ca02-4794-9942-06f5e247ec15/blog/index.html
21writing 2483 bytes to builds/74df6813-ca02-4794-9942-06f5e247ec15/blog/hello-again/index.html
22
23Pages:         6 (15.5 KB)
24Assets:        1 (649 B)
25Feeds:         2 (4.8 KB)
26Tags:          1
27----------------
28TOTAL        5ms

Build inputs

Builds have three primary inputs:

A website configuration file path
A build output path
A list of page file paths to include in the build
A boolean flag indicating if an incremental build should be performed

Build pipeline

Loads website template data and configuration settings from site.yaml or site.json
Loads namespaced template data from the configured site.config.data_dir (default: ./data)
Discovers website pages from the configured site.config.content_dir (default: ./content)
Discovers website draft pages from the configured site.config.drafts_dir (default: ./drafts)
Loads build pages
Loads discovered website pages (this is a no-op for full-site builds)
Loads build page feeds
Loads build page tag feeds (auto-generates tag pages as needed)
Validates the build
Writes build assets to disk
Writes build feeds to disk (atom.xml files)
Writes pages to disk (index.html files)
Calculates build statistics

Full-site builds

By default, HyperTemplates performs full-site builds like a traditional static site generator. Full site builds scan the configured site.config.content_dir (default: ./content) for page index files (index.md, index.markdown, index.yaml, index.yml, or index.json) and provides a list of all discovered paths with the build input parameters.

Incremental builds

HyperTemplates provides support for performing partial builds of a website. A typical incremental build provides a single page path with its build input parameters. Incremental builds are executed within the context of the complete website, enabling HyperTemplates to determine if the page being built matches any feed filters, and if so, the corresponding feed(s) (atom.xml files) and feed page(s) (index.html files) are included in the build. Incremental builds may also trigger new tag pages to be generated if page.content contains a hashtag (for index.md files only), or if page.tags are provided.

Reproducible builds

HyperTemplates builds are deterministic. Given identical inputs, builds will always produce identical outputs.

NOTE: Reproducible builds means that two full-site builds performed with identical inputs will be identical. But HyperTemplates reproducible builds guarantees even extend to incremental builds, if layered on top of a full-site build. In other words, if a third incremental build were to be performed with no changes to the inputs, and the incremental build output is layered on top of one of the first two builds, both builds will still be identical.

Example

In the following example, two builds are performed and then compared using the macOS diff command.

 1
 2$ ls -al builds/
 3total 0
 4drwxr-xr-x@ 2 calebhailey  wheel   64 Jun 11 16:53 .
 5drwxr-xr-x@ 9 calebhailey  wheel  288 Jun 11 09:55 ..
 6
 7macbook $ hyperctl build -c site.yaml -i alpha
 8build "alpha" starting
 9website "site.yaml" load
10theme "theme.json" warning: open theme.json: no such file or directory
11asset "static/styles.css" discovered
12data "data/nav.yaml" loading
13page "content/index.md" loading
14page "content/blog/hello-again/index.md" loading
15page "content/blog/hello-world/index.md" loading
16page "content/about/index.md" loading
17page "content/blog/index.md" loading
18tag "blog" loading
19copying "static/styles.css" to "builds/alpha/styles.css"
20writing 3323 bytes to builds/alpha/blog/atom.xml
21writing 1615 bytes to builds/alpha/tags/blog/atom.xml
22writing 2392 bytes to builds/alpha/index.html
23writing 2483 bytes to builds/alpha/blog/hello-again/index.html
24writing 2420 bytes to builds/alpha/blog/hello-world/index.html
25writing 2421 bytes to builds/alpha/tags/blog/index.html
26writing 3587 bytes to builds/alpha/blog/index.html
27writing 2590 bytes to builds/alpha/about/index.html
28
29Pages:         6 (15.5 KB)
30Assets:        1 (649 B)
31Feeds:         2 (4.8 KB)
32Tags:          1
33----------------
34TOTAL        7ms
35
36macbook $ hyperctl build -c site.yaml -i beta
37build "beta" starting
38website "site.yaml" load
39theme "theme.json" warning: open theme.json: no such file or directory
40asset "static/styles.css" discovered
41data "data/nav.yaml" loading
42page "content/index.md" loading
43page "content/blog/hello-again/index.md" loading
44page "content/blog/hello-world/index.md" loading
45page "content/about/index.md" loading
46page "content/blog/index.md" loading
47tag "blog" loading
48copying "static/styles.css" to "builds/beta/styles.css"
49writing 1615 bytes to builds/beta/tags/blog/atom.xml
50writing 3323 bytes to builds/beta/blog/atom.xml
51writing 2420 bytes to builds/beta/blog/hello-world/index.html
52writing 2421 bytes to builds/beta/tags/blog/index.html
53writing 2590 bytes to builds/beta/about/index.html
54writing 2392 bytes to builds/beta/index.html
55writing 3587 bytes to builds/beta/blog/index.html
56writing 2483 bytes to builds/beta/blog/hello-again/index.html
57
58Pages:         6 (15.5 KB)
59Assets:        1 (649 B)
60Feeds:         2 (4.8 KB)
61Tags:          1
62----------------
63TOTAL        4ms
64
65macbook $ diff -r builds/alpha builds/beta
66macbook $

NOTE: the lack of output from the diff -r builds/alpha builds/beta command indicates that the builds are identical, as documented in the following excerpt from the macOS diff manpage:

The diff utility compares the contents of file1 and file2 and writes to the standard output the list of changes necessary to convert one file into the other. No output is produced if the files are identical.