Undocumented foibles in referencing .liquid files in #DocFX liquid templates

I’ve recently been working on a couple of DocFX templates for auto-generating documentation on different projects (watch this space for a couple of projects coming soon!).

One the main things I wanted to do to ease development and maintenance was to rip out the horrible Moustache templates and replace it with Liquid templates – primarily because I know it better (as do most PowerApps Portal developers) but also because I think it’s more powerful, from what I know of it.

As I was sharing some functionality between different templates, I wanted to make fairly extensive use of the include keyword to include partial blocks, but it took me a while to figure out how to make them work, so thought I’d share here for future reference.

The only thing the documentation says on the subject is:

Renderers in Liquid syntax MUST end with .liquid extension. Liquid contains include tag to support partials, we follow the ruby partials naming convention to have _<partialName>.liquid as partial template.

Here’s the rules for referencing .liquid files:

Do

1. Name the target liquid file starting with an underscore

2. Provide the filename as an unescaped string in the include block

{% include partials/mermaid-diagrams %}

Don’t

1. Don’t use any string literals (single or double quotes)

<!-- wrong -->
{% include "partials/mermaid-diagrams" %}

<!-- wrong -->
{% include 'partials/mermaid-diagrams' %}

2. Don’t include the file names underscore prefix in the relative path (even though you must in the actual file!)

<!-- wrong -->
{% include partials/_mermaid-diagrams %}

3. Don’t include the .liquid file extension

<!-- wrong -->
{% include partials/mermaid-diagrams.liquid %}

Additional foible!

Note that the above is only for referencing liquid files with the include keyword. These rules don’t seem to apply to the custom DocFX master keyword.

For example, this works just fine, despite breaking all the rules above:

{% master "layout/_master.liquid" %}

Apologies for the excessive use of the word ‘foible’ in this post ;]