haXtags

Embed HaXtatic tags anywhere in source contents, templates, snippets or *.haxproj files with a simple notation: {Prefix|Name|} or {Prefix|Name: Args|}.

Example: {P|date|} outputs in-place the currently set page date (using the built-in fallback date-time format since none was specified in the tag) when it is processed: 2016-12-18.

Available "prefixes" (or haxTag types) are (in order of simplicity) T, B, P and X:

Topics

• T-tags: named plain text/markup snippets

  {T| .. |} tags directly output named textual contents defined in a *.haxproj file.

• P-tags: page-specific outputs

  {P| .. |} tags refer to the current page context during rendering; outputting pre-computed values (page title, page date, etc.), custom per-page variables, or correct relative paths from the current location.

• B-tags: Blok info (name, title, desc, ..)

  A {B| .. |} tag outputs, for the (named or current) Blok, the value (as set in a *.haxproj |B| directive) of the requested property.

• X-tags: dynamic renderers

  An {X| .. |} tag invokes a programmatic output renderer (aka. X-renderer).

Processing

• All unprocessed haXtags (mispelled etc.) simply remain in the output, aiding swift detection
  • (exception: some X-tags requiring syntax — if unprocessable due to bad syntax, these output error details)
• Any haXtags may embed/output any other haXtags freely both in their definitions and invocations but
  • an otherwise-correct outer tag will typically not render with a (directly embedded) unprocessable inner tag (a "known non-issue", incidentally helping ensure later-stage inner tags provide correct input to their outer tags), and this can of course bubble outwards with deeper nestings
  • a direct-or-indirect recursive self-reference (self-invocation inside the "defining portion" of a haXtag's related declaration directive) will hang (and usually eventually prematurely abort with a <<loop>> farewell message) the entire generating process

Unnecessary knowledge 99% of the time until running into that one odd edge-case where it'll help: a haXtag will be processed during one of two possible (multi-pass each) "stages":

• Early stage — during the loading of project files needed before even the first page can be generated: *.haxproj, snippets, templates
• Page stage — per generated file: all the haXtags contained in the current content source file, plus any unprocessed left-overs from Early stage that come into play for this file and might now, with a page context current, be able to produce output (if not unprocessable)

Early stage by default: T-tags, named B-tags, most X-tags

Page stage by default: P-tags, unnamed B-tags, a few X-tags

Recall that as a general rule, a directly embedded unprocessable inner tag prevents processing of its outer tag(s). This reality both allows for the staged processing to function smoothly (usually/mostly) in the first place, and also suggests keeping in mind that Early-capable haXtags in non-page project files may still only process at page time.

For X-tags:

• They can be force-delayed to Page stage while investigating unexpected outputs.
• Each built-in X-renderer decides autonomously and documents explicitly its render stage.