Skip to main content

Configuration

Most configuration for hexdoc can be done in the hexdoc.toml (or doc/hexdoc.toml) file.

File paths​

Most file paths in the hexdoc.toml file are resolved relative to the location of the config file, not the working directory of the hexdoc command or the root of the Git repository.

For example, in the below file structure, the following hexdoc.toml file would correctly reference the src/main/resources directory, regardless of where the hexdoc command is executed from:

.
├── doc/
│   └── hexdoc.toml
└── src/
    └── main/
        └── resources/
doc/hexdoc.toml
resource_dirs = [
    "../src/main/resources",
]

TOML placeholders​

The hexdoc.toml parser includes a custom placeholder interpolation system, similar to JSONPath, that allows referencing other values in the config file (eg. for reusing common values).

Placeholders are added to strings in the format {key}, similar to Python's f-strings. The string may also contain other text outside of the placeholder. By default, placeholder keys are resolved relative to the table containing the placeholder.

key = "foo {var} baz"
var = "bar"

Placeholders must reference keys containing string values; the following example is invalid and would raise an error.

key = "{var}"
var = 0

Parent references​

The key ^ may be used to reference the table containing the current table (ie. the parent table). It can be used multiple times to reference grandparents, great-grandparents, and so on. Parent references may optionally be separated and/or followed by . characters.

[foo]
key1 = "{^baz.var}"

[foo.bar]
key2 = "{^^baz.var}"
key3 = "{^.^.baz.var}"

[baz]
var = "value"

Root references​

The key $ may be used at the start of a placeholder key to reference the root table of the TOML file. It may optionally be followed by a . character.

[foo]
key1 = "{$baz.var}"

[foo.bar]
key2 = "$.baz.var"

[baz]
var = "value"

Arrays​

Placeholders in arrays are resolved relative to the table containing the array. However, placeholders in tables within arrays are resolved relative to the table in the array.

key1 = [
    "{var}",
    { key2="{^var}" }
]

var = "value"

For this reason, it is usually more readable to use root references within arrays.

key1 = [
    "{$var}",
    { key2="{$var}" }
]

var = "value"

Custom fields​

To make your hexdoc.toml file easier to maintain, you can add custom fields starting with the prefix _. All fields starting with _ will be silently ignored by hexdoc (instead of raising a validation error for unrecognized fields).

For example, custom fields and placeholders are used by the hexdoc project templates to define common paths that are used in multiple places:

doc/hexdoc.toml
resource_dirs = [
    "{$_common.src}/main/resources",
    { path="{$_common.src}/generated/resources", required=false },
]

[[extra.hexcasting.pattern_stubs]]
path = "{$_common.package}/Patterns.java"

[_common]
src = "../common/src"
package = "{src}/main/java/com/example"

Note that since the _common table starts with _, the fields within that table (eg. _common.src) are not parsed by hexdoc, so they don't need to start with _.

note

This is similar to Docker Compose's Extensions feature.

Intrinsic functions​

Intrinsic functions are tables with a key starting with the prefix ! that are handled specially by the TOML parser.

To use an intrinsic function, create a table with a single entry, where the key is the name of the function, and the value is the input to the function. For example:

key1 = "value"             # normal value
key2."!Raw" = "value"      # !Raw function (option 1)
key3 = { "!Raw"="value" }  # !Raw function (option 2)
note

The last two examples above are logically equivalent in TOML, and are both equivalent to the following JSON value before being parsed by hexdoc.

{
    "key": {
        "!Raw": "value"
    }
}

!Raw​

Outputs the value passed to this function as-is, without any further processing (eg. string placeholders and intrinsic functions will not be expanded). Useful for defining regular expressions.

pattern1."!Raw" = "^{.+}$"
pattern2 = { "!Raw"="^{.+}$" }

!None​

Outputs None. The input value is ignored. This function is necessary because TOML does not have a null keyword.

null1."!None" = ""
null2 = { "!None"="" }

JSON Schema​

If you use a TOML validator with JSON Schema support (eg. the Even Better TOML VSCode extension), you can get autocomplete and validation for hexdoc.toml files by using the autogenerated JSON Schema definition.

With Taplo-based tools like Even Better TOML, you can enable the schema by adding the following comment to the top of hexdoc.toml (docs):

#:schema https://hexdoc.hexxy.media/schema/core/Properties.json