diff options
Diffstat (limited to 'man/blogc-template.7.ronn')
| -rw-r--r-- | man/blogc-template.7.ronn | 128 |
1 files changed, 10 insertions, 118 deletions
diff --git a/man/blogc-template.7.ronn b/man/blogc-template.7.ronn index 1530fb3..d010a1c 100644 --- a/man/blogc-template.7.ronn +++ b/man/blogc-template.7.ronn @@ -22,8 +22,7 @@ matches the requirements of the given block. Blocks can be defined more than once, but can't be nested. -The available blocks are: `entry`, `listing`, `listing_empty`, `listing_entry` -and `listing_once`. +The available blocks are: `entry`, `listing` and `listing_once`. ### entry block @@ -57,42 +56,6 @@ This is how a `listing` block is defined: will be included once for each entry. {% endblock %} -### listing_empty block - -This block is similar to the `listing` block, but its content is included -only when there are no entries to be listed, either because no source files -were provided or because there are no entries remaining after filtering (see -blogc-pagination(7)). - -This is how a `listing_empty` block is defined: - - {% block listing_empty %} - No entries available. - {% endblock %} - -### listing_entry block - -This block is identical to the `entry` block, but its content is included in -the output file only when blogc(1) is called with `-l` and `-e` <SOURCE> -options. The variables available in the block are provided by the source -file provided using `-e` <SOURCE> option. - -This is how a `listing_entry` block is defined: - - {% block listing_entry %} - This content will only be included when rendering a listing, but with - content provided by a single entry. - {% endblock %} - -When multiple `listing_entry` blocks are defined, blogc(1) should be called -with multiple `-e` <SOURCE> options. If a `listing_entry` block does not have -a corresponding `-e` <SOURCE> option, or if its value is an empty string, -the content of the `listing_entry` block is not included. - -`listing_entry` blocks inside iterator are evaluated as multiple blocks and -also require multiple `-e` <SOURCE> options. blogc(1) won't use the same -source for every iteration. - ### listing_once block The content of a `listing_once` block is included in the output file when @@ -111,8 +74,8 @@ This is how a `listing_once` block is defined: will be included only once. {% endblock %} -This is a 'real world' usage example of a `listing_once` block, supposing -that the `TITLE` variable is defined: +This is a 'real life' usage example of a `listing_once` block, supposing +that each source file defines a `TITLE` variable: {% block listing_once %} <ul> @@ -151,7 +114,7 @@ in the template. If user append `_FORMATTED` to the end of the variable name, a formatter will be applied, if available for the variable name: - Date formatter: if variable name starts with `DATE_`, it is formatted with - a strftime(3) format, provided by `DATE_FORMAT` variable. The `DATE_FORMATTED` + a strptime(3) format, provided by `DATE_FORMAT` variable. The `DATE_FORMATTED` "meta-variable" will return the formatted version of the `DATE` variable. If `DATE_FORMAT` is not provided, the original value will be returned. @@ -174,53 +137,6 @@ An existing variable is not overrided by the truncate syntax. That means that if `FOO_5` variable exists, it won't be handled as a truncate "meta-variable", and `FOO_5` variable value will be returned normally. -## PREDEFINED TEMPLATE VARIABLES - -blogc(1) provides some template variables, that can be used to display some build -metadata in your website. - -If some of the variables are not available in the system running the build, they -won't be defined. It is recommended to rely on template conditionals, mainly -`ifdef` and `ifndef` when using these variables. - -### Static variables - -These variables are always available, and are set during the blogc(1) binary -compilation. - - * `BLOGC_VERSION`: - The version of blogc(1) used to build. e.g.: `blogc 0.14.1`. - -### Resource usage variables - -It is not possible to measure the resource usage of blogc(1) until the end of -the execution, because the rendering of these variables itself is using resources, -and the evaluation of the used resources was already done. To get better values, -it is recommended to use these variables only in the website footer. - - * `BLOGC_RUSAGE_CPU_TIME`: - The CPU time used to build, up to the point where this variable was used for - the first time in the template (value is cached). e.g.: `12.345ms`. - - * `BLOGC_RUSAGE_MEMORY`: - The memory used to build, up to the point where this variable was used for the - first time in the template (value is cached). e.g.: `1.234MB`. - -### System information variables - - * `BLOGC_SYSINFO_HOSTNAME`: - The hostname of the machine where the build happened (short hostname only, not - FQDN). - - * `BLOGC_SYSINFO_USERNAME`: - The username of the user that executed the build. - - * `BLOGC_SYSINFO_DATETIME`: - The GMT datetime of the build. e.g. `2019-02-10 22:00:00`. - - * `BLOGC_SYSINFO_INSIDE_DOCKER`: - If built inside a docker container, this variable will be defined, with value `1`. - ## TEMPLATE CONDITIONALS Template conditionals are used to include content to the output, or not, @@ -317,40 +233,16 @@ This is how a `foreach` iterator is defined in a template: {% endforeach %} Where `TAGS` is the variable with space-separated list of items, and `FOREACH_ITEM` -is the variable defined by blogc(1), that will store the item for a given iteration. +is the variable defined by blogc(1), that will store the item value for a given +iteration. If the value of the `TAGS` variable is "item1 item2 item3", this template is -rendered 3 times, one for each item. - -It is possible to map the items to arbitrary strings by defining other variables -following a predefined for naming schema, like: - - TAGS__ITEM1 - -Where `TAGS` is the variable defined in the foreach iterator, and `ITEM1` is the -current iteration item (the value of `FOREACH_ITEM` for the current iteration, -converted to upper case and with special characters converted to `_`). - -This is how a `foreach` iterator using arbitrary string mapping is defined in a template: - - {% foreach TAGS %} - <a href="/tag/{{ FOREACH_ITEM }}/">{{ FOREACH_VALUE }}</a> - {% endforeach %} - -`FOREACH_VALUE` is the variable defined by blogc(1), that will store the arbitrary string -mapped to current iteration item. This variable can be checked using `ifdef` conditionals -(and similar) as usual: - - {% foreach TAGS %} - {% ifdef FOREACH_VALUE %} - <a href="/tag/{{ FOREACH_ITEM }}/">{{ FOREACH_VALUE }}</a> - {% endif %} - {% endforeach %} +rendered 3 times, one for each item value. -The `FOREACH_ITEM` and `FOREACH_VALUE` variables can be truncated, like: +The `FOREACH_ITEM` variable can be truncated, like: {% foreach TAGS %} - <a href="/tag/{{ FOREACH_ITEM_5 }}/">{{ FOREACH_VALUE_5 }}</a> + <a href="/tag/{{ FOREACH_ITEM }}/">{{ FOREACH_ITEM_5 }}</a> {% endforeach %} ## WHITESPACE CONTROL @@ -378,4 +270,4 @@ Rafael G. Martins <<rafael@rafaelmartins.eng.br>> ## SEE ALSO -blogc(1), blogc-source(7), strcmp(3), strftime(3) +blogc(1), blogc-source(7), strcmp(3) |