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:

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

Build context

Every build has a context - a combination of time, event, and environment – that make up the inputs to a given build. This context is exposed to layout templates as template data.

The build context includes the following template data scopes:

ht

ht.* prefixed template data properties about HyperTemplates itself and its internal logic. The ht.* template data object includes:

• ht.version: the HyperTemplates version used to perform a build
• ht.release_date: the release date of the HyperTemplates version used to perform the build
• Template iterator properties: ht.index, and ht.count (see the ht-template directive)

build

build.* prefixed template data properties generated by the hyperctl build command. The build.* template data object includes:

• build.id: the build ID
• build.date: the build timestamp in RFC3339 format

env

env.* prefixed template data properties sourced from HT_ environment variables (see environment data).

site

site.* prefixed template data properties sourced from site.yaml or site.json. The site.* template data object includes all website properties, including custom website properties.

data

data.* prefixed template data properties sourced from static namespace data files and computed namespaces in site.data_dir (see namespaces).

theme

theme.* prefixed template data properties sourced from static namespace data files and computed namespaces in theme.data_dir (see namespaces).

layout

layout.* prefixed template data sourced from <meta> elements with layout: prefixed name attributes (see layout data).

page

page.* prefixed template data sourced from page data files (supports Markdown, YAML, and JSON formats; includes custom page properties).

Build pipeline

1. Loads website template data and configuration settings from site.yaml or site.json
2. Loads namespaced template data from the configured site.config.data_dir (default: ./data)
3. Discovers website pages from the configured site.config.content_dir (default: ./content)
4. Loads build pages
5. Loads discovered website pages (for incremental builds)
6. Loads build page feeds
7. Loads build page tag feeds (auto-generates tag pages as needed)
8. Generates computed namespaces
9. Validates the build
10. Writes build assets to disk
11. Writes build feeds to disk (atom.xml files)
12. Writes pages to disk (index.html files)
13. Calculates build statistics

Complete builds

By default, HyperTemplates performs complete builds like a traditional static site generator. Complete builds scan the configured site.config.content_dir (default: ./content) for page files 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.

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 $