Introduction

This PostHTML plugin can prepend a string to various HTML attribute values and CSS property values.

Input:

<img src="test.jpg">

Output:

<img src="https://example.com/test.jpg">

Works on the following attributes:

• src=""
• href=""
• srcset=""
• poster=""
• background=""

... and 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 are supported as well.

Install

npm i posthtml posthtml-base-url

Usage

import posthtml from 'posthtml'
import baseUrl from 'posthtml-base-url'

posthtml([
  baseUrl({
    url: 'https://example.com', 
    tags: ['img']
  })
])
  .process('<img src="test.jpg">')
  .then(result => console.log(result.html))

Result:

<img src="https://example.com/test.jpg">

Absolute URLs

If the target attribute value is an URL, the plugin will not modify it.

If the prefix string to prepend to the target attribute value is an URL, the two strings will be concatenated.

Relative paths

If both the prefix and the attribute value are relative paths, the plugin will intelligently join the paths instead of simply concatenating them.

Options

You can configure what to prepend to which attribute values.

url

Type: string
Default: ''

The string to prepend to the attribute value.

allTags

Type: boolean
Default: false

The plugin is opt-in, meaning that by default it doesn't affect any tag.

When you set allTags to true, the plugin will prepend your url to all attribute values in all the tags that it supports.

styleTag

Type: boolean
Default: false

When set to true, the plugin will prepend your url to all url() sources in <style> tags.

inlineCss

Type: boolean
Default: false

When set to true, the plugin will prepend your url to all url() sources in style="" attributes.

tags

Type: array|object
Default: defaultTags (object)

Define a list of tags and their attributes to handle.

When using the tags option, the plugin will only handle those tags.

Array tags

To replace all known attributes for a list of tags, use the array format:

posthtml([
  baseUrl({
    url: 'https://example.com',
    tags: ['img', 'script'],
  })
])
  .process(
    `<a href="foo/bar.html">
      <img src="img.jpg" srcset="img-HD.jpg 2x,img-xs.jpg 100w">
    </a>
    
    <script src="javascript.js"></script>`
  )
  .then(result => console.log(result.html))

Result:

<a href="foo/bar.html">
  <img src="https://example.com/img.jpg" srcset="https://example.com/img-HD.jpg 2x, https://example.com/img-xs.jpg 100w">
</a>

<script src="https://example.com/javascript.js"></script>

Object tags

You may use an object for granular control over how specific attributes should be handled:

posthtml([
  baseUrl({
    url: 'https://foo.com/',
    tags: {
      img: {
        src: true,
        srcset: 'https://bar.com/',
      },
    },
  })
])
  .process(
    `<a href="foo/bar.html">
      <img src="img.jpg" srcset="img-HD.jpg 2x, img-xs.jpg 100w">
    </a>`
  )
  .then(result => console.log(result.html))

Result:

<a href="foo/bar.html">
  <img src="https://foo.com/img.jpg" srcset="https://bar.com/img-HD.jpg 2x, https://bar.com/img-xs.jpg 100w">
</a>

You may set the value of an attribute to true and the plugin will use the url option value - we did that above for the src attribute.

attributes

Type: object
Default: {}

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

Example:

posthtml([
  baseUrl({
    attributes: {
      'data-url': 'https://example.com/',
    }
  })
])
  .process('<div data-url="foo/bar.html"></div>')
  .then(result => console.log(result.html))

Result:

<div data-url="https://example.com/foo/bar.html"></div>