ht-base attribute

`ht-base` attribute reference

Overview

The ht-base attribute specifies the base URL to use for all relative URLs in a given element.

The ht-base attribute is inspired by the HTML <base> element which serves a similar purpose. Unlike the <base> element which can only only be used once per document, there can be multiple ht-base elements in a template.

NEW! Available in hyperctl version 0.15.0 and later.

Example

The ht-base attribute is used to resolve relative links. Let's take the following Markdown as an example. It defines an image with some alt text.

content/blog/hello-world/index.md

1---
2title: Hello World
3---
4
5![blog post cover image description](cover.png)
6
7Hello, world! 👋

This Markdown image references an image with the relative path cover.png. Given the page index file path of content/blog/hello-world/index.md we could expect to find the source image file at content/blog/hello-world/cover.png. This Markdown image would be rendered as follows:

1<img src='cover.png' alt='blog post cover image description' />

This would result in an image that is displayed correctly when viewed on the /blog/hello-world/ page of our website. But what would happen if this <img> tag were to appear in a feed on the /blog/ page? The browser would resolve src='cover.png to the URL /blog/cover.png instead of /blog/hello-world/cover.png.

This kind of templating challenge can be solved using the ht-base attribute. Let's look at how that works in the following example which shows the ht-base attribute being used to template a feed page <blog-post> element.

layouts/feed.html

 1<html lang='en-US'>
 2    <head>
 3        <meta ht-include='partials/head.html' />
 4        <style>/* insert feed styles here */</style>
 5    </head>
 6    <body>
 7        <header ht-include='partials/header.html'></header>
 8        <main>
 9            <feed-entry ht-template='entry:page.feed.pages' ht-base='src:entry.path'>
10                <entry-meta>
11                    <h3 ht-content='entry.title'>Post Title</h3>
12                </entry-meta>
13                <entry-summary ht-content='entry.summary,entry.content'></entry-summary>
14                <entry-link>
15                    <a ht-attrs='href:entry.path'>Continue reading &rightarrow;</a>
16                </entry-link>
17            </feed-entry>
18        </main>
19        <footer ht-include='partials/footer'></footer>
20    </body>
21</html>

The ht-base='src:entry.path' attribute instructs HyperTemplates to use the template data value of entry.path to resolve relative src attribute URLs. If we wanted to resolve href attributes as well, we could amend the attribute to ht-base='src:entry.path;href:entry.path'.

Specification

Supported elements

The ht-base attribute can be used with any HTML element.

Example

1<blog-feed>
2    <blog-post ht-template='post:page.feed.pages' ht-base='src:post.path'>
3        <!-- Blog post layout -->
4    </blog-post>
5</blog-feed>

Attribute syntax

The ht-base attribute is expressed as a semicolon-separated list of attribute:value pairs.

The attribute is an attribute selector sans the square brackets (e.g. src or href). HyperTemplates will wrap the provided attribute in square brackets, so src becomes [src] and query the rendered HTML for all child elements matching the attribute selector (i.e. src becomes element.querySelectorAll("[src]")).

The value is comma-separated list of dot-notation style references to one or more template data properties. If multiple properties are defined for a given template variable, the first non-empty property will be used.

Example

1<blog-feed>
2    <blog-post ht-template='page:page.feed.pages' ht-base='src:site.cdn,page.path; href:page.path'>
3        <!-- Blog post layout -->
4    </blog-post>
5</blog-feed>

In this example two ht-base directives are configured: one that will resolve src attributes, and one that will resolve href attributes.

The src:site.cdn,post.path attribute will use the site.cdn custom property as the base URL (if configured), otherwise it will use the page.path property. Being able to configure a global/default value like site.cdn is helpful in case we use an external image hosting service like Cloudflare Images.

NOTE: because this example uses ht-template='page:page.feed.pages' to remap the page. prefix to the contents of pages in a feed (see page.feed.pages) rather than the current page, it will effectively resolve relative links for each page in the feed using the correct path.

For example, let's assume page.feed.pages contains two pages with the following paths:

/blog/hello-world/

/blog/hello-again/

When ht-template processes the first page, the value of page.path will be /blog/hello-world/. When it processes the second page, the value of page.path will be /blog/hello-again/.

Absolute links

HyperTemplates uses the following rules to determine if a URL is "absolute":

URLs that begin with the http: or https: scheme are absolute links
URLs that begin with the data: scheme are absolute links (see data: URLs)
URLs that begin with / are absolute links

All other URLs are considered relative links and subject to resolution by ht-base, when configured.