Introduction

This plugin helps prevent widow words by replacing the space between the last two words in a string with a non-breaking space. By default, the string must contain at least 4 words to be processed.

Input:

<div prevent-widows>
  <p>The quick brown fox</p>
</div>

Output:

<div>
  <p>The quick brown&nbsp;fox</p>
</div>

• [x] configurable attribute names
• [x] set the minimum number of words
• [x] ignore templating logic or expressions
• [x] reverse it: create widow words

Install

npm i posthtml posthtml-widows

Usage

import posthtml from 'posthtml'
import preventWidows from 'posthtml-widows'

posthtml([
  preventWidows()
])
  .process('<p prevent-widows>The quick brown fox</p>')
  .then(result => console.log(result.html))

Result:

<p>The quick brown&nbsp;fox</p>

Attributes

The plugin will only handle strings inside elements that have one of the following attributes:

• prevent-widows
• no-widows

You may also specify custom attributes to use:

posthtml([
  preventWidows({
    attributes: ['fix-widows']
  })
])
  .process('<p fix-widows>The quick brown fox</p>')

Options

minWords

Type: number
Default: 4

The minimum number of words a string must contain to be processed.

posthtml([
  preventWidows({
    minWords: 3,
  })
])
  .process('<p prevent-widows>Prevent widow words</p>')

ignore

Type: Array
Default: (array of objects)

An array of objects that specify the start and end delimiters of strings to ignore. Used to avoid processing templating logic or expressions.

By default, the following templating delimiters are ignored:

• {{ }} - Handlebars, Liquid, Nunjucks, Twig, Jinja2, Mustache
• {% %} - Liquid, Nunjucks, Twig, Jinja2
• <%= %> - EJS, ERB
• <% %> - EJS, ERB
• {$ } - Smarty
• <?php ?> - PHP
• <?= ?> - PHP
• #{ } - Pug

You may add custom delimiters to ignore:

posthtml([
  preventWidows({
    ignore: [
      { start: '[[', end: ']]' },
      // Inside MSO comments
      { start: '<!--[', end: ']>' },
      { start: '<![', end: ']--><' }, // <![endif]-->
    ]
  })
])
  .process(
    `<p prevent-widows>Using the option to <!--[if mso]> ignore this MSO comment <![endif]--> is being tested here.</p>`
  )

Result:

<p>Using the option to <!--[if mso]> ignore this MSO comment <![endif]--> is being tested&nbsp;here.</p>

createWidows

Type: boolean
Default: false

You may also use the plugin to do the opposite of preventing widow words by replacing the   between the last two words with a regular space.

posthtml([
  preventWidows({
    attributes: ['create-widows'],
    createWidows: true,
  })
])
  .process('<p create-widows>The quick brown&nbsp;fox</p>')

Result:

<p>The quick brown fox</p>

License

MIT