hax.htmlAnchors

Helps with page-level tables-of-content: outputs a sequence of  <a href="#.."> .. </a> or  <outerhtmltag ..><a href="#.."> .. </a></outerhtmltag> — one per  <gatherhtmltag> element found in the content source file.

In a nutshell

1. Declaration of an |X|hax.htmlAnchors:myTag:gatherhtmltag: .. directive in a *.haxproj file,
   • further configuring: considerEmpty, outputIfEmpty, xmlEscapeHref
2. Usage anywhere: {X|myTag:outerhtmltag: attr = [..] |}

This topic is in a compact format for users already familiar with the essentials of declaring X-tags and invoking them. If found challenging, try the more-elaborate-and-introductory topics first to form a better grasp on the basics and overall mechanisms.

Stage:

Page — this X-renderer requires a page context for rendering: therefore any hax.htmlAnchors-invoking X-tags encountered during pre-templating (at start-up time) will be skipped over, thus only process per-page, once present.

To demonstrate valid *.haxproj directives declaring hax.htmlAnchors X-tags:

|X|hax.htmlAnchors:pagefootnotes:sup

|X|hax.htmlAnchors:pagechapters:h2:
	considerEmpty = 0,
	outputIfEmpty = "Nothing to show — put eg. CSS here to hide",
	xmlEscapeHref = False

To elaborate, for example the last one of the above, as all |X| directives declaring X-tags do:

• begins with |X| followed by the X-renderer identifier (here hax.htmlAnchors)
• followed by  : colon and the desired X-tag name to be used to invoke it (here pagechapters),
• followed by  : colon and now hax.htmlAnchors-specific configuration:
• The markup-tag name to "gather" from the current content source file
• followed by a  : colon if an optional syntax-sensitive properties block follows, comprised (if present at all) of all the following properties in this very order:
  1. considerEmpty — any number  0 (the default) or greater. The listing will only commence if the number of gathered page elements exceeds this (eg. one might not want to show a table-of-content with just  1 "section" gathered from the page).
  2. outputIfEmpty — the output (if any, default is none) to produce only when no listing is rendered
     • No HTML/XML/etc.-escaping of inputs is performed, provide correct values for the intended output format.
  3. xmlEscapeHref — False (the default) or True: whether to HTML/XML-escape the dynamically generated href attribute values of all rendered <a> elements.
     • If False: No HTML/XML/etc.-escaping of inputs is performed, provide correct values for the intended output format.

For example: {X|pagefootnotes:div:attr = [ ("class" , "my-footnotedetail") ] |}

(No HTML/XML/etc.-escaping of inputs is performed, provide correct values for the intended output format.)

attr (same mechanics as the one for hax.htmlLinks) is syntax-sensitive but optional: <ul class="toc">{X|pagechapters: li |}</ul> outputs a <li><a href="#heading content">heading content</a></li> for every <h2 id="heading content">heading content</h2> in the content source file.

In the present version, a known issue: this does not currently really read the id attribute of the gathered elements, only their entire inner contents, so the only way for hax.htmlAnchors linkage to work at present is for id to have the exact same content as the element's inner content. To be rectified in a future release.