ht-base directive

`ht-base` directive reference

Overview

The ht-base directive specifies a base URL to use for relative attribute URLs. The ht-base directive applies to the target element and its child elements.

The ht-base directive is inspired by the HTML <base> element, which serves a similar purpose. However, unlike the HTML element (which can only only be used once per document), multiple ht-base directives can be used to configure more flexible relative URL resolution.

Example

The ht-base directive 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
3canonical_url: https://example.com/blog/hello-world/
4---
5
6![blog post cover image description](cover.png)
7
8Hello, world! 👋

This Markdown contains an image with alt text and a relative path (cover.png), which would be rendered as follows:

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

If this <img> element is rendered on a page at https://example.com/blog/hello-world/, the relative src='cover.png' attribute is implicitly resolved to https://example.com/blog/hello-world/cover.png.

However, if this same <img> element is rendered in a feed page at https://example.com/blog/, the relative src='cover.png' attribute is implicitly resolved to https://example.com/blog/cover.png.

This kind of templating challenge can be solved using the ht-base directive. Note how the ht-base directive is used to resolve src attribute URLs in the following layout:

layouts/feed.html

 1<html lang='en-US'>
 2    <head>
 3        <!-- standard head elements go here -->
 4    </head>
 5    <body>
 6        <header ht-include='fragments/header.html'></header>
 7        <main>
 8            <blog-feed>
 9                <blog-post ht-each='page in ${ page.feed.pages }' ht-base='src on ${ page.canonical_url }'>
10                    <post-meta ht-if='${ page.title }'>
11                        <h3 ht-apply>${ page.title }</h3>
12                    </post-meta>
13                    <post-summary ht-apply>
14                        ${ markdown(page.summary, page.content) }
15                    </post-summary>
16                    <post-link>
17                        <a ht-apply href='${ page.canonical_url }'>Continue reading &rightarrow;</a>
18                    </post-link>
19                </blog-post>
20            </blog-feed>
21        </main>
22        <footer ht-include='fragments/footer'></footer>
23    </body>
24</html>

The ht-base='src on ${ page.canonical_url }' directive instructs HyperTemplates to use the template data value of page.canonical_url to resolve relative src attribute URLs.

NOTE: If we wanted to resolve href attributes in addition to src attributes, we could add a second ht-base directive (see multiple directives).
1<blog-post ht-each='page in ${ page.feed.pages }'
2           ht-base='src on ${ page.canonical_url }'
3           ht-base='href on ${ page.canonical_url }'>
4    
5</blog-post>

Specification

Supported elements

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

Example

1<blog-feed>
2    <blog-post ht-each='post in ${ page.feed.pages }' ht-base='src on ${ post.canonical_url }'>
3        <!-- post preview -->
4    </blog-post>
5</blog-feed>

Attribute syntax

Each ht-base directive may contain exactly one attribute on ${ variable } expression: The attribute is any attribute name that contains URL values (e.g. src or href). The variable is any template variable that resolves to an absolute URL.

Example

1<blog-feed>
2    <blog-post ht-each='post in ${ page.feed.pages }' ht-base='src on ${ post.canonical_url }'>
3        <!-- post preview -->
4    </blog-post>
5</blog-feed>

In this example, ht-base resolves all child src attributes using the value of post.canonical_url.

Multiple directives

Use multiple ht-base directives to configure URL resolvers for multiple attributes. When using multilple ht-base directives the attribute selectors must be unique (i.e. you cannot set two ht-base='href on ${ ... }' directives).

1<blog-feed>
2    <blog-post ht-each='page in ${ page.feed.pages }'
3               ht-base='src on ${ site.cdn.base_url, page.canonical_url }'
4               ht-base='href on ${ page.canonical_url }'>
5        <!-- post preview -->
6    </blog-post>
7</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 ${ site.cdn.base_url, page.canonical_url } portion of the directive will use the site.cdn.base_url custom property as the base URL (if configured), otherwise it will use the page.canonical_url 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.

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.