widont

In typesetting, single words on the last line of a paragraph are commonly known as widows, and are considered bad style. widont eliminates the issue of widows by using a non-breaking space to force the last two words of a string onto the same line. If the last word contains hyphens they will be converted to the non-breaking variant instead.

Usage

var widont = require('widont')

widont('I dream of a world without widows')
// => 'I dream of a world without\u00a0widows'

widont('I like words with hyphens that stick-together')
// => 'I like words with hyphens that stick\u2011together'

widont('I get HTML entities instead', 'html')
// => 'I get HTML entities instead'

widont('I get exclamation marks', { spaces: '!!', hyphens: '??' })
// => 'I get exclamation!!marks'

In TypeScript

import * as widont from 'widont'

widont('TypeScript says hello', 'html')
// => 'TypeScript says hello'

API

widont(string, [replacements='unicode'], [minWords=3])

Replaces any number of whitespace before the last word of string with a non-breaking space, unless the last word contains hyphens in which case they will be replaced (by non-breaking hyphens) instead. Trims trailing whitespace at the end of string if present. Returns non-string inputs as-is.

The optional replacements argument specifies what characters to use as replacements. It can either be a string that maps to a set of predefined characters (unicode, html or ascii), or an object with the keys space and hyphen (both must be provided):

{
  space: '_',
  hyphen: '~'
}

A TypeError will be thrown for unknown or incomplete replacements values.

The minWords argument specifies the minimum number of words requires to be present in the string for the replacement to be applied. It defaults to 3 to avoid forcing strings only consisting of two words to be kept together, as that could lead to them overflowing.

Origins

The original widont was created by Shaun Inman. This implementation is based on the version in Kirby CMS, which extends the original by using non-breaking hyphens if the last word contains hyphens.

License

MIT