Base URL

Define a string that will be prepended to all sources and hrefs in your HTML and CSS.

Useful if you already host your images somewhere like a CDN, so you don't have to write the full URL every time when developing.

Works with the following HTML attributes:

• src
• href
• srcset
• poster
• background

... and with the following CSS properties:

• background: url()
• background-image: url()
• @font-face { src: url() }

Both <style> tags and style="" attributes are supported. CSS property values with multiple url() sources (like @font-face declarations) are supported as well.

Usage

Make it globally available by setting it in your environment config:

module.exports = {
  baseURL: 'https://cdn.example.com/'
}

Customization

You'll most likely want to customize the transformer so that it applies only to certain elements, or even only to certain attributes of certain elements.

tags

Apply the base URL only to <img> tags:

module.exports = {
  baseURL: {
    url: 'https://cdn.example.com/',
    tags: ['img'],
  },
}

That will apply the url to all known source attributes on all <img> elements in your HTML, like src="" or srcset=".

If you need greater control, you may specify which attributes of which tags should be prepended what URL, by passing in an object instead:

module.exports = {
  baseURL: {
    url: 'https://cdn.example.com/',
    tags: {
      img: {
        src: true, // use the value of `url` above
        srcset: 'https://bar.com/',
      },
    },
  },
}

attributes

Key-value pairs of attributes and what to prepend to them.

module.exports = {
  baseURL: {
    attributes: {
      'data-url': 'https://example.com/',
    },
  },
}

styleTag

By default, the transformer will prepend your url to all url() sources in <style> tags. Set this option to false to prevent it from doing so:

module.exports = {
  baseURL: {
    url: 'https://cdn.example.com/',
    tags: ['img'],
    styleTag: false,
  },
}

inlineCss

Similarly, the transformer will prepend your url to all url() sources in style="" attributes. You may disable this if you need to:

module.exports = {
  baseURL: {
    url: 'https://cdn.example.com/',
    tags: ['img'],
    inlineCss: false,
  },
}

Front Matter

You may override it for a single Template, through Front Matter:

---
baseURL: 'https://res.cloudinary.com/user/image/upload/v.../'
---

<extends src="src/layouts/base.html">
  <block name="template">
    <img src="example.jpg">
  </block>
</extends>

Trailing slash

Mind the trailing slash on your URL, this influences how you reference images:

<!-- baseURL: 'https://cdn.example.com/img' -->
<img src="/folder/product-1.png">

<!-- baseURL: 'https://cdn.example.com/img/' -->
<img src="folder/product-1.png">

Disabling

If you have baseURL set globally (in your config), you may disable it for a Template by setting its value to an empty string or a falsy value in Front Matter:

---
baseURL: ''
---

or

---
baseURL: false
---

API

const {applyBaseUrl} = require('@maizzle/framework')
const config = {
  url: 'https://cdn.example.com/img/',
}

const html = await applyBaseUrl('<img src="image.jpg">', config)