v0.6.0

Dactyl version 0.6.0 introduces two new features:

• Stricter consistency checks on the config file, so subtle errors are more likely to raise an error rather than passing silently.
• The html field of pages is now optional; if omitted, Dactyl chooses a filename for the page automatically.

Additionally, the custom templates in the examples/ folder show how to list pages in a category-index page.

Consistency Checks

Version 0.6.0 is backwards compatible in most cases, but reacts differently to some consistency errors in the config file by default. Some errors that prior Dactyl versions silently ignore result in Dactyl exiting with an error instead.

In most cases, you can try to build anyway if you pass the --bypass_errors commandline option; however, you should probably fix the errors in your config file instead.

Some common errors include:

Invalid targets array

Previous versions of Dactyl mishandled the case where the targets array that didn't parse as array syntax in YAML. For example:

    -   name: Correct Page
        md: correct.md
        html: correct-page.html
        targets:
            - mytarget

    -   name: Broken Page
        md: broken.md
        html: broken-page.html
        targets:
            -mytarget
        # Without the space after the -, the above target list 
        # parses as a string instead of a one-item array

Prior to Dactyl v0.6.0, the broken page would be silently omitted from all targets because its targets parameter was present but not formatted as the correct type. Dactyl v0.6.0 exits immediately with an error if it reads a config file containing such an error.

Reused HTML Filename

Previous versions of Dactyl silently overwrote a page if a later page in the same target used the same HTML filename as output. For example:

    -   name: Losing Page
        md: losing.md
        html: overlap.html
        targets:
            - mytarget

    -   name: Winning Page
        md: winning.md
        html: overlap.html
        targets:
            - mytarget

With old versions of Dactyl, the file overlap.html ends up with the contents of Winning Page when you build mytarget. With v0.6.0, Dactyl exits with an error if you try to build mytarget with the above config file.

Default HTML Filenames

Prior to v0.6.0, you had to specify an HTML filename in the html field for each page in the Dactyl config. Starting with v0.6.0, the html field is optional; if omitted, Dactyl chooses a filename based on the following rules:

1. If the page has an md field, Dactyl uses that to make a .html filename. Dactyl replaces .md with .html and replaces the OS's path separator (typically /) with a dash (-) instead.
   • If you want to output HTML files in folders that mimic the input structure, add flatten_default_html_paths: true to the top level of your Dactyl config file. This might not work with PDF output for all versions of Prince on all platforms.
2. If the page doesn't have an md field but does have a name field, Dactyl uses a "slug" version of the name, appending .html.
3. If the page doesn't have an html, md, or name field, Dactyl generates a filename from the current time() value, replacing the . with a - character. Because this value is different each time you run Dactyl, continuously building the same target results in an ever-growing number of files, so this is not advised.