{% tableofcontents %}

A build-time application of <base> to HTML (without relying on <base>) by modifying a[href], video[src], audio[src], source, img[src], [srcset], and more.

• Read about HTML’s <base> element on MDN

If you want to deploy your project in a different directory without changing the content, Eleventy provides a Path Prefix feature to specify the target directory.

• via --pathprefix on the command line
• or via pathPrefix object key in your configuration file return object

Historically, we then recommended to use the provided url filter in your templates to transform any local URL with the path prefix. The downside of this method was that it required you to remember and opt-in every URL transformation in your content!

With this new plugin, you no longer need to use the url filter in your HTML content. This plugin adds an Eleventy Transform that will modify your HTML output and inject your Path Prefix in your template content.

• Behind the scenes, this plugin transforms URLs found in a[href], video[src], audio[src], source, img[src], [srcset] and a whole bunch more (via posthtml-urls).

You can, if you’d like! Some folks have found it to be a bit [unreliable]({{ "https://twitter.com/Rich_Harris/status/1526937421505609728" | canonicalTwitterUrl }}) and edge-casey. This offers a build-time alternative.

{% addedin "2.0.0-canary.15" %} This plugin is bundled with Eleventy 2.0 (no extra installation is required). It works with all template languages (via an Eleventy Transform) and some of the advanced usage filters require async-friendly template syntax (Nunjucks, Liquid, and JavaScript).

Open up your Eleventy config file (probably eleventy.config.js) and use addPlugin:

{% include "snippets/plugins/base-install.njk" %}

You’re only allowed one module.exports in your configuration file, so make sure you only copy the require and the addPlugin lines above!

For templates that output *.html files, you don’t need to do anything else. The HTML plugin will automatically apply the Path Prefix to URLs in any html file in your output directory.

This plugin also provides new filters for you to use these transformations manually. This is useful when you want to use the same functionality but the URL you want to transform is not in one of the HTML elements that get automatically transformed (like an HTML comment {% raw %}<!-- Current page: {{ page.url }} -->{% endraw %}).

Transform a single URL string using the base.

{% include "snippets/plugins/htmlbaseurl.njk" %}

You can override the baseHref option by passing another argument to the filter with your one-off base value. Note that when you use a full URL as your base href, relative paths are no longer ignored—they are modified using the current page’s URL:

{% include "snippets/plugins/htmlbaseurl-override.njk" %}

Transform a block of HTML with posthtml. Applies the above htmlBaseUrl filter to each applicable URL in an HTML block (so the URL transformation rules are the same). Requires an async-friendly template language.

We use this in the RSS plugin to change your content to be absolute URLs for broadest compatibility with various RSS feed readers.

{% include "snippets/plugins/base-transform.njk" %}

Note that passing a full external URL (e.g. http://example.com/) to htmlBaseUrl will return the URL unchanged. We don’t want to add pathPrefix to external links!

However, if you do want to force addition of pathPrefix to a URL, you can use the addPathPrefixToFullUrl filter.

{% include "snippets/plugins/base-add.njk" %}