Hey guys,
tl;dr i’m looking for a feature a la Asciidoctor’s Include Content by Tagged Regions
Background
When writing a blog post about programming or complementary documentation for software, you normally have some code listings that show important snippets of code, example configurations, and so on. But most of the time, you only want to show the important parts to the reader and not a whole file. Therefore, you just copy the relevant parts into a code listing.
One problem with copying is that the software may change, but you forget to update the listings accordingly. Or you write the listing manually but make mistakes, and the listing shows code that does not compile.
Due to these problems, I want to include “real” code that passes compilation and testing. But as I said, not whole files, just the relevant regions.
Asciidoctor
In my opinion Asciidoctor provides here a really cool feature to include regions from other files into a document.
Example
Code:
// We need a main function to run the code but it is not relevant to the reader
fn main() {
do_epic_shit();
}
// tag::my_function[]
pub fn do_epic_shit() {
todo!("epic shit comming soon!");
}
// end::my_function[]
Usage:
Use the function below to do epic shit on your own:
[source,rust]
----
include::main.rs[tag=my_function]
----
Result:
Use the function below to do epic shit on your own:
pub fn do_epic_shit() {
todo!("epic shit comming soon!");
}
shortcodes
I implemented a shortcode to include parts of files where regions are tagged similar to how Asciidoctor does it:
Shortcode:
{% set start_pattern = "^.*\stag::" ~ tag ~ "$" -%}
{% set end_pattern = "^.*\send::" ~ tag ~"$" -%}
{% set content = load_data(path=path) -%}
{% set capture = false -%}
{% set output = [] -%}
{% for line in content | split(pat="\n") -%}
{% if line is matching(start_pattern) -%}
{% set_global capture = true -%}
{% continue -%}
{% elif line is matching(end_pattern) -%}
{% set_global capture = false -%}
{% break -%}
{% endif -%}
{% if capture -%}
{% set_global output = output | concat(with=line) -%}
{% endif -%}
{% endfor -%}
{% if output | length > 0 -%}
{{ output | join(sep="\n") -}}
{% else -%}
{{ throw(message="Include 'tag::" ~ tag ~"' from '" ~ path ~ "' results in empty output!") -}}
{% endif -%}
Usage:
{{ include(path="main.rs",tag="my_function") }}
Please be lenient, I’m new to zola and this is my first shortcode. So maybe there is room for improvements but I think this should not be implemented in a templating language. Especially my shortcode covers only the simplest case. Asciidoctor’s include directive is much more powerful.
Proposal
Zola should provide a mechanism to include regions of external content. Similar to the load_data function but with a builtin functionality to select the relevant passages.
I’m interested in your opinion!
Disclaimer
- I hope I read Zola’s documentation carefully and didn’t miss a feature that already provides similar functionality.
- I’m not sure if this feature should be part of Zola or Tera.