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

Type: Array|Object
Default: see default 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

Type: Object
Default: {}

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

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

styleTag

Type: Boolean
Default: true

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

Type: Boolean
Default: true

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/'
---

<x-main>
  <img src="example.jpg">
</x-main>

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)