doxx Key Files

What is a Key File?

It is command central for project builds. The key file contains definitions for the build file paths and the text replacements to be performed during the build. The file is divided into two sections where these data are defined.

The Key File Structure

doxx Keys Include:

  1. YAML build specification header section
  2. YAML named replacement tag + string replacement definition section
  3. key.yaml default filename

Build Specification Header Section

The first section of the key file is defined with --- (three dash symbols) delimiters above and below the data:

---

template: example.doxt

---

This section includes build specification data:

Available Exclusive Build Specification Header Fields:

  • template:
  • templates:
  • project:

Available Non-Exclusive Build Specification Header Fields:

  • textfiles:

Exclusive Build Specification Header Fields

template: use the key to perform replacements in a single template (one-to-one mapping)

templates: use the key to perform replacements in multiple templates (one-to-many mapping)

project: use the key to build from a tar.gz or .zip project archive file (one-to-one or one-to-many mapping)

These are exclusive fields that are defined as follows:

For template: or templates: fields:

For project: fields:

Beware

These template and project path fields are exclusive field types. Only include one per template file. You can comment out ones that you are not using with a # character.

To comment out unused fields, place a # character at the beginning of the line like this:

---

template: example.doxt
# templates:
# project:

---

This is useful for users who generate key file stubs with the make command (which includes all three fields) or who need to alternate between fields during template testing.

Non-Exclusive Build Specification Header Fields

The following build specs can be used with any of the exclusive fields above:

textfiles: use the key to pull verbatim text files into your project by URL (added in v0.9.3)


How to Use the textfiles Build Specification Field

You can use this field to pull one or more text files into a project root directory or sub-directories by URL.

An example use case includes tracking a Github repository file or a set of files in your project. For instance, you can pull the Font Awesome minified and non-minified CSS files from the master branch of the Font Awesome Github repository by adding the following build specs to your key file:

---

textfiles:
    font-awesome.css: "https://raw.githubusercontent.com/FortAwesome/Font-Awesome/master/css/font-awesome.css"
    font-awesome.min.css: "https://raw.githubusercontent.com/FortAwesome/Font-Awesome/master/css/font-awesome.min.css"

---

textfiles Build Specification Field Usage

  • Change the file write root directory default to a sub-directory by changing the file path key to the left of the : character
  • Use POSIX path syntax in your project files irrespective of your target users. doxx modifies file write path separators as necessary on systems that require it.
  • It is not necessary for project users to create build directories in advance of the build. doxx performs recursive directory writes as needed based upon the build specification definitions.
  • Include each file on a new line
  • Insert four spaces relative to the textfiles: field before your file definition

In the above example, the files will be pulled to the root directory. To change the write directory to a different sub-directory, change the filepath key to the left of the : symbol. For example, to write the above files to the css directory in your project, modify the above build specs to the following:

---

textfiles:
    css/font-awesome.css: "https://raw.githubusercontent.com/FortAwesome/Font-Awesome/master/css/font-awesome.css"
    css/font-awesome.min.css: "https://raw.githubusercontent.com/FortAwesome/Font-Awesome/master/css/font-awesome.min.css"

---

Note the new file path and path separator that was used: css/[font awesome file name]. Also note that each new file is on a separate line and four spaces are used (relative to the textfiles field) before the file defintion.

Key File Build Specification Field Best Practices

In the Key Build Specification Section:

  • Use POSIX file path strings with forward slashes (/) between directories and files (including Windows/DOS systems)
  • Use single or double quotes around URL strings and other strings that include special YAML characters
  • Use brackets around comma delimited file path or URL lists with the templates: field
  • Multiple file paths or URL's used with the templates: field can be listed on newlines to improve legiblity (see examples below)
  • Include four spaces before each new file path definition with the textfiles: field

Build Specification Field Formatting

Single Template Builds

One:One Key-Template Mapping

For single template builds the key meta data for local and remote templates should look like this:

---

template: test.doxt

---
---

template: 'https://coolsite.com/templates/test.doxt'

---

Multiple Template Builds

One:Many Key-Template Mapping

For multiple template builds, include the template file paths or URL as a comma separated list inside [ and ] characters:

---

templates: [templ1.doxt, templ2.doxt, templ3.doxt]

---

If you have a long list of template files, you can place each of them on a new line:

---

templates: [templ1.doxt,
            templ2.doxt,
            templ3.doxt,
            templ4.doxt,
            templ5.doxt,
            templ6.doxt,
            templ7.doxt,
            templ8.doxt,
            templ9.doxt]

---

Remote templates are defined with comma separated URLs that are enclosed in single or double quotes:

---

templates: ['https://coolsite.com/templates/test1.doxt',
            'https://coolsite.com/templates/test2.doxt',
            'https://coolsite.com/templates/test3.doxt']

---

Project Archive File Builds

It is possible to build from tar.gz or .zip project archive files that contain a combination of text files, binary files, and doxx templates. An archive packages the entire doxx project directory into a single file and the project: field is defined with this file path. The project archive can be a local or remote file.

Here is an example of a local .zip project archive definition:

---

project: projects/example.zip

---

and of a remote tar.gz project archive definition:

---

project: 'https://coolsite.com/projects/example.tar.gz'

---

Verbatim Text File Pull Builds

Include the textfiles: build spec and one or more keys with local file path definitions that are defined as follows:

---

textfiles:
    [local file path]: [ URL ]
    [local file path 2]: [ URL ]
    [local file path ...]: [ URL ]

---

Note that the file path definitions are on separate lines and that there are four spaces before your definition string.

Key File Section Delimiters vs. Template File Section Delimiters

It is important to note that the delimiter is three dashes --- for the sections of a key file. This differs from the delimiter that is used to separate sections in a template file which is ---doxx---. These file types will not parse properly without the appropriate delimiter type.

Template String Replacement Section

The second section of the key file includes key names that correspond to template replacement tag names. The values associated with these key names are used as text replacement strings at the corresponding sites in template files. The text replacements take place at every site of the named text replacement tag in the corresponding template file(s).

Here are examples of keys that will lead to the insertion of 'Joe' and '2015' at the site of {{name}} and {{year}} template replacement tags, respectively:

name: Joe
year: 2015

doxx provides support for strings that include characters from the UTF-8 character set in text replacement definitions:

name: Анатолий
greeting: здравствуйте

Now let's bring both of these sections together to create a complete doxx key file. Here is an example of a simple key file that will perform the 'Joe' and '2015' replacements in a template file named example.doxt that is located in the same directory as the key file:

---

template: example.doxt

---

name: Joe
year: 2015

And here is an example of a key file that will perform the text replacements in a remote example.doxt template file:

---

template: 'https://coolsite.com/templates/example.doxt'

---

name: Joe
year: 2015

Key File YAML Formatting Issues

Quoting Text Replacements

Your replacement text can be placed in the key file without surrounding single or double quotes if you do not use special YAML characters. If you are encountering YAML parsing errors with your replacement text, try placing double quotes around it and run your build command again.

Long Strings

You can split long replacement strings over multiple lines in your key file. Here is an example of how a block of multi-line text should appear in a key:

name: Chris
multiline:
    This is a multiple line string
    with more input
month: January

Note that the newline characters that split the string on separate lines are not preserved when you do this. Place explicit newline characters in your text if you intend to maintain the new line formatting in the output. A less error-prone approach is to maintain formatting in the template and use different replacement tags for text that should be placed on separate lines.

Comments

Comments are included in the template file with the comment line indicator character #. The entire line of text following the # character is treated as a comment.

This is useful as a means to provide instructions to users who build from a key file that is distributed with a project:

---

template: 'https://coolsite.com/templates/example.doxt'

---

# Enter a name to be inserted at the site of the To: address in your message
name: Joe

# Enter the current year
year: 2015

or to provide additional instructions in the build spec header section:

---

# Change to the URL 'https://coolsite.com/templates/example2.doxt' for alternate format
template: 'https://coolsite.com/templates/example.doxt'

---

name: Joe
year: 2015

Key File Naming

Key files named key.yaml are executed in the current working directory by default with the command:

$ doxx build

If you decide to use a different key file name, the key file path must be included as an argument to the doxx build command:

$ doxx build [key file path]

See the build command documentation for more details.

Key File Stub Generator

The doxx make command generates a key file stub in the working directory. See the make command documentation for details.


just blimpin doxx documentation is licensed under the CC-4.0-Attribution LicenseImprove this page