Including hidden comments and metadata in FoldingText documents

1

It can be very useful to include non-printing lines in a plain text document.

One approach is to have some : separated key value pairs at the very top of a document (followed by a blank line). This is the MultiMarkdown approach to document metadata, and Brett Terpstra’s Marked will respect such lines and leave them unprinted.

<!-- Another approach is to use HTML comments -->

which can be single-line or multiline. They don’t have the MMD front matter advantage of being parsed, by some utilities, into key:value pairs, but they do have other advantages which can be useful. In particular:

  1. They can appear anywhere in the document
  2. You can put more or less anything in them.
  3. Foldingtext recognises them as htmlblocks, and highlights them differently from the rest of the text.

A tip for multiline HTML comments:

FoldingText automatically recognizes and parses single line HTML comments, but requires multiline HTML comments to be preceded by at least one other HTML tag.

In practice, I find the most useful approach is to precede a multiline comment with another single line comment, for example, a perspective-generating script which I am testing creates reports and views which have a hidden copy of the underlying query at the start of the text, before the headings and paragraphs begin:

<!-- QUERY -->
<!-- Plain text query: 
{
	"title": "## This WEEK",
	"for": "$item in //@due <= {today + 7d}",
	"let": "$day = fn:daypart($item@due)",
	"groupby": "$day",
	"orderby": "$day",
	"return": [
		"### {$day}",
		{
			"for": "$i in $item",
			"orderby": "$i@due",
			"return": "- fn:timepart({$i@due}) [{$i}](nvalt://fn:encode_for_uri({$i}))"
		},
		""
	]
}
-->
<!-- REPORT BEGINS HERE -->

FoldingText will highlight these in a different color, to show that they are HTML, and Brett Terpstra’s Marked will leave them unprinted.