prevent-widows

Prevent widows from appearing in a string.

This module replaces the spaces and hyphens at the end of a paragraph with non-breaking spaces and non-breaking hyphens to prevent widows.

It comes with support for strings and posthtml.

Installation

npm install prevent-widows
# - or -
yarn add prevent-widows

Usage

Prevent widows from appearing in a string.

const preventWidows = require('prevent-widows');
preventWidows('lorem ipsum dolar sit a met');
// lorem ipsum dolar sit a met

import preventWidows from 'prevent-widows';
preventWidows('lorem ipsum dolar sit a met');
// lorem ipsum dolar sit a met

Options

encoding

Defines the type of output to transform the spaces and hyphens.

• Since: 1.0.0
• Property is Optional
• Default value is: Encodings.HTML
• Validation rules:
  • Must be a type of Encoding

This table describes how values will be transformed depending on what type of pre-defined encoding you specify.

| Encoding | Space character | Hyphen character | | -------- | --------------- | ---------------- | | html |   | ‑ | | unicode | \u00a0 | \u2011 |

For example:

preventWidows('lorem ipsum dolar sit a met', { encoding: Encodings.UNICODE });

Alternatively, a custom encoding can be defined using an object:

preventWidows('lorem ipsum dolar sit a met', {
  encoding: { space: '_', hyphen: '~' },
});

// lorem ipsum dolar sit a_met

posthtml

This module comes with out-of-the-box support for posthtml.

Usage

The posthtml function exposes an additional parameter: posthtmlOptions.

import posthtml from 'posthtml';
import preventWidows from 'prevent-widows';

posthtml().use(preventWidows.posthtml(posthtmlOptions, preventWidowsOptions));

Example

import posthtml from 'posthtml';
import preventWidows from 'prevent-widows';

(async () => {
  const input = '<div prevent-widows>lorem ipsum dolar sit a met</div>';

  const { html } = await posthtml().use(preventWidows.posthtml()).process(input);

  console.log(html);
})();

// <div>lorem ipsum dolar sit a&nbsp;met</div>

posthtml Options

The posthtml method also comes with the following options:

attrName

The name of the attribute which identifies where widows should be prevented on its children.

• Since: 1.0.0
• Property is Optional
• Default value is: prevent-widows
• Validation rules:
  • Must be a valid HTML attribute name

<div prevent-widows>Prevent widows</div>

attrRemove

Whether or not to remove the attribute (see: attrName) from the element after the transform has been applied.

• Since: 1.0.0
• Property is Optional
• Default value is: true
• Validation rules:
  • Must be a boolean value: true or false

When true and by default, this will output:

<div>Prevent widows</div>

When false, this will output:

<div prevent-widows>Prevent widows</div>