Links and URLs

Templates never assemble an address from strings. A document’s address comes from its route, so it is read from the entry; a literal path, a type’s index and another site are built by helpers that add the site’s path prefix and the locale prefix; and an editor’s link comes from a link field that resolves its target, its text and its attributes. If a route or a locale prefix changes, every link follows.

A minimal exampleCopy Anchor Link

<nav>
  <a href="{{ path('/') }}">{{ t("nav.home") }}</a>
  <a href="{{ path('event') }}">{{ t("nav.whats_on") }}</a>
  <a href="{{ path('/visit/accessibility') }}">{{ t("nav.access") }}</a>
</nav>

{% for article in items %}
  <a href="{{ article.uri|url }}">{{ article.title }}</a>
{% endfor %}

{% if entry.bookingUrl %}{{ entry.bookingUrl.link(text=t("event.book"), class="button") }}{% endif %}

• path('/') is the home page with the locale prefix the site’s strategy needs.
• path('event') is the index page of the event type in the request’s locale, whatever segment its route gives it in that locale.
• article.uri is the article’s own path; a variable in href goes through |url.
• bookingUrl.link() prints the editor’s link with the text, rel, new-tab announcement and class the editor chose.

The url filter ruleCopy Anchor Link

engine-dmo check refuses a variable printed into href, src, action, formaction, srcset or poster unless it goes through the url filter:

<a href="{{ entry.uri|url }}">          {# accepted #}
<a href="{{ entry.uri }}">              {# error: a variable inside href must go through |url #}

The filter validates the scheme. Relative paths, #fragment, ?query, http, https, mailto, tel, sms and otpauth pass; anything else (javascript:, data:, a protocol-relative //host) becomes #. It also escapes the value for the attribute.

Values built by the engine’s own helpers are already safe, so these need no filter: path(...), url(...), siteUrl(...), assets.url(...), feedUrl(...), calendarUrl(...), the icsUrl filter, and a field value’s method called with parentheses, such as entry.heroImage.url('hero'). A property read without parentheses (entry.uri, entry.url, item.url, pagination.next, localeUrl('fr')) needs |url.

HelpersCopy Anchor Link

path()Copy Anchor Link

A path starts with /. Anything without a leading slash is read as a type key.

url()Copy Anchor Link

url(...) takes the same arguments as path() and returns an absolute URL on the origin the visitor is on (scheme, host and port of the request). Use it where an absolute address is needed and the visitor’s own host is right, such as a share link. For an address search engines read (canonical, hreflang, sitemaps, structured data), the engine uses the site’s configured domain itself; see SEO and structured data.

siteUrl()Copy Anchor Link

An absolute URL on any site of the project, for a link from one site to another:

<a href="{{ siteUrl('/', site='county') }}">{{ t("nav.county_site") }}</a>
<a href="{{ siteUrl('listing', site='county', locale=locale.code) }}">{{ t("nav.places") }}</a>

The host is the target site’s domain. When the visitor came in on a port (in development, town.localhost:8080), the link keeps the port. An absolute URL as the first argument is an error.

localeUrl() and the language switcherCopy Anchor Link

<ul>
{% for code, tr in entry.translations %}
  {% if tr.exists %}<li><a href="{{ tr.path|url }}" hreflang="{{ code }}" lang="{{ code }}">{{ code }}</a></li>{% endif %}
{% endfor %}
</ul>

An entry’s addressCopy Anchor Link

Use uri for a link on the page, {{ item.uri|url }}: it is a path, so the link stays on whatever host the visitor is on. Use url only where an absolute address is needed, such as a share link or an email. Both are correct in href; the examples in this handbook use uri.

A document with no route on the site has no uri or url. Relations, list items, children and ancestors are entries too, so item.uri works everywhere. Navigation items carry url, isExternal, isCurrent and isActive (Navigation).

Index pages give pagination.prev and pagination.next as paths that keep the selected facets, and each facet value its own url:

{% if pagination.next %}<a rel="next" href="{{ pagination.next|url }}">{{ t("pager.next") }}</a>{% endif %}

Link fieldsCopy Anchor Link

A link field stores an editor’s link to a document, an asset, a web address, an email address, a phone number, another site or an anchor. Its value resolves the target at render, so a link to a document follows the document when its address changes, and a link to a document that is not live in the locale is reported as broken. How kinds, styles and editor attributes are configured is in the link field.

{# the whole <a>, with everything the editor set #}
{{ entry.cta.link() }}
{{ entry.cta.link(text=t("more"), class="button button--primary", data-track="cta") }}

{# your own element around the editor's attributes #}
<a {{ entry.card.attributes(class="card__link") }}>
  <span class="card__title">{{ entry.card.text }}</span>
</a>

{# a list of links #}
{% for l in entry.links %}<li>{{ l.link() }}</li>{% endfor %}

HelpersCopy Anchor Link

href is the link’s own and is refused as a keyword. style= and inline event handlers are refused. engine-dmo check warns when a literal aria-label= does not contain the literal text=, since the visible text must be part of the accessible name.

PropertiesCopy Anchor Link

Printing the value itself, {{ entry.cta }}, prints its url. With multiple: true the value is a list.

Links to other websitesCopy Anchor Link

Every link to another website, in a link field or in rich text, takes the site’s outbound rules on top of the editor’s own choices:

# config/sites/<key>/site.yaml
links:
  outbound:
    new_tab: true                 # open in a new tab, announced, with noopener
    rel: [noopener, noreferrer]   # tokens every outbound link carries

A link counts as outbound when its host is not one of the install’s sites. The new-tab announcement text is the string link.new_tab in the string catalogue.

Asset linksCopy Anchor Link

Any asset value has link(), a download link that names the file’s type and size in the request locale:

{{ entry.report.link() }}                         {# Annual report (PDF, 2.1 MB) #}
{{ entry.report.link(text=t("download.report")) }}

{{ entry.report }} prints the original file’s URL. For images, see Images.

Static filesCopy Anchor Link

assets.url(path) is a file under the site’s public directories with a version query from its modification time, so a changed file is fetched again and an unchanged one stays cached for a year:

<link rel="icon" href="{{ assets.url('favicon.svg') }}" type="image/svg+xml">

Files resolve along public/<site>/, public/_shared/, then public/. See Frontend build.

Feeds and calendarsCopy Anchor Link

Feeds and calendars are configured on the route (routes reference).

RelatedCopy Anchor Link

• Sites, locales and routes: how a route and a locale strategy make an address.
• Redirects and URLs: what happens to an old address.
• Multisite templates: linking between sister sites.