Builtins reference

Overview

The HyperTexting CMS provides some automatic templating features that are powered by builtin layout fragments. Built-in layout fragments can be disabled or overriden by adding empty fragment files to your theme.

NEW: HyperTexting builtins are available in hyperctl version 0.20.0 and newer.

Example

HyperTexting automatically provides several built-in features via HTML <head> elements, including:

HTTP redirects (i.e. <meta http-equiv='refresh'> elements)
CMS discovery (i.e. <meta name='generator'> elements)
Feed discovery (e.g. <link rel='alternate' type='application/rss+xml'> elements)
Canonical URL references (i.e. <link rel='canonical'> elements)

All four of these built-in features are provided by a single template fragment called fragments/builtin/head_start.html. To disable these features, create an empty fragments/builtin/head_start.html fragment in your theme.

Specification

Builtin includes

HyperTemplates builtins are implicitly included at specific positions in a layout. These implicit includes take place after ht-include directives have been processed to ensure they are correctly positioned in the layout (see [Builtin positioning] for more information).

Builtin positioning

All HyperTemplates builtins are inserted using a position mode, and a CSS selector. The four position modes are prepend, append, before, and after.

prepend

The builtin fragment is inserted as the first child of the selected element.

Example

A builtin with prepend main positioning includes fragments as the first child of the <main> element:

layouts/default.html

 1<html>
 2    <head>
 3        <title ht-apply>${ page.title }</title>
 4        <meta ht-apply name='description' content='${ page.description }'>
 5    </head>
 6    <body>
 7        <header></header>
 8        <main>
 9            <!-- prepend main builtin fragments go here -->
10            <h1 ht-apply>${ page.title }</h1>
11        </main>
12        <footer></footer>
13    </body>
14</html>

append

The builtin fragment is inserted as the last child of the selected element.

Example

A builtin with append main positionining includes fragments as the last child of the <main> element:

layouts/default.html

 1<html>
 2    <head>
 3        <title ht-apply>${ page.title }</title>
 4        <meta ht-apply name='description' content='${ page.description }'>
 5    </head>
 6    <body>
 7        <header></header>
 8        <main>
 9            <h1 ht-apply>${ page.title }</h1>
10            <!-- append main builtin fragments go here -->
11        </main>
12        <footer></footer>
13    </body>
14</html>

before

The builtin fragment is inserted before the selected element, as a sibling.

Example

A builtin with before main positionining includes fragments immediately before the <main> element:

layouts/default.html

 1<html>
 2    <head>
 3        <title ht-apply>${ page.title }</title>
 4        <meta ht-apply name='description' content='${ page.description }'>
 5    </head>
 6    <body>
 7        <header></header>
 8        <!-- before main builtin fragments go here -->
 9        <main>
10            <h1 ht-apply>${ page.title }</h1>
11        </main>
12        <footer></footer>
13    </body>
14</html>

after

The builtin fragment is inserted after the selected element, as a sibling.

Example

A builtin with after main positionining includes fragments immediately after the <main> element:

layouts/default.html

 1<html>
 2    <head>
 3        <title ht-apply>${ page.title }</title>
 4        <meta ht-apply name='description' content='${ page.description }'>
 5    </head>
 6    <body>
 7        <header></header>
 8        <main>
 9            <h1 ht-apply>${ page.title }</h1>
10        </main>
11        <!-- after main builtin fragments go here -->
12        <footer></footer>
13    </body>
14</html>

NOTE: If a builtin targets a selector that doesn't match any elements in the layout, it is ignored.

Builtin fragments

HyperTexting currently includes a single builtin:

head_start

The head_start.html builtin uses prepend head positioning.

Source

fragments/builtin/head_start.html

1<!-- fragments/builtin/head_start.html begin -->
2<meta ht-apply ht-if='page.redirect' http-equiv="refresh" content='0; url=${page.refresh}' />
3<meta ht-apply name='generator' content='${ site.generator, "hypertexting" }'>
4<link ht-apply rel='canonical' href='${ page.canonical_url }'>
5<link ht-apply rel='icon' type='image/jpeg' href='${ site.favicon.href, "/favicon.ico" }' sizes='${ site.favicon.size, "32x32"}'>
6<link ht-template='link:site.links' rel='${ link.rel, "" }' href='${ link.href }' type='${ link.type, "" }' title='${ link.title, "" }'>
7<!-- fragments/builtin/head_start.html end -->

To disable or override the head_start.html builtin, add a fragments/builtin/head_start.html fragment to your theme.

Builtins reference

Overview

Example

Specification

Builtin includes

Builtin positioning

Builtin fragments

💬 Join the community