Mapping AsciiDoc includes and level offsets to Jinja
Esc
Start typing to search...
Gabriel McGoldrick1 min read

Mapping AsciiDoc includes and level offsets to Jinja

Jinja natively supports including text files with {% include ... %}:

AsciiDoc to Markdown — part 7 of 7
  1. Migrating AsciiDoc to Markdown
  2. Why existing AsciiDoc converters lose your structure
  3. Why Jinja is the right target
  4. Mapping AsciiDoc variables to Jinja
  5. Mapping AsciiDoc conditionals to Jinja
  6. Mapping AsciiDoc ifeval to Jinja
  7. Mapping AsciiDoc includes and level offsets to Jinja — you are here
  • AsciiDoc:
    asciidoc
    include::snippets/deployment-config-deprecated.adoc[]
  • Jinja:
    jinja
    {% include "./snippets/deployment-config-deprecated.md" %}

That much is free. Level offsets are not.

Level offsets

By default Jinja does not support level offsets — shifting heading levels up or down when merging files together.

Level offsets solve a real problem in technical writing: modular reuse. They let you write a file as a standalone document, with its own primary = Title, and then embed it as a nested subsection inside a master book or assembly without breaking the global table of contents.

DogsBay extends Jinja with {% leveloffset ... %} and {% endleveloffset %}:

  • AsciiDoc:
    asciidoc
    include::modules/ldap-syncing-about.adoc[leveloffset=+1]

include::modules/ldap-syncing-config-rfc2307.adoc[leveloffset=+2]

include::modules/ldap-syncing-config-activedir.adoc[leveloffset=+2]

include::modules/ldap-syncing-running.adoc[leveloffset=+1]
  • Jinja:
    jinja
    {% leveloffset +1 %}{% include "./modules/ldap-syncing-about.md" %}{% endleveloffset %}

{% leveloffset +2 %}{% include "./modules/ldap-syncing-config-rfc2307.md" %}{% endleveloffset %}

{% leveloffset +2 %}{% include "./modules/ldap-syncing-config-activedir.md" %}{% endleveloffset %}

{% leveloffset +1 %}{% include "./modules/ldap-syncing-running.md" %}{% endleveloffset %}
Warning

Watch the code blocks. A heading shift must not change # characters that are shell prompts or comments inside a fenced code block. The shift has to be fence-aware, so # oc adm ... in a terminal block stays a comment and does not become a heading.

That warning is not hypothetical. In an operations corpus, # opens a large proportion of the lines inside code blocks — a naive regex shift corrupts them all, and the damage looks like ordinary prose in the diff.

Reference: Syncing LDAP groups

That completes the mapping. Back to the series index.