Skip to content

Latest commit

 

History

History
173 lines (121 loc) · 7.33 KB

README.md

File metadata and controls

173 lines (121 loc) · 7.33 KB

grunt-raggedast

Adjust the text rag of your documents for better readability.

Overview

This task was inspired by an article by Mark Boulton and based on plugin by Nathan Ford. In case you want to process your documents dynamically, you should take a look at that plugin. Raggedast is for those who care about typography and readability but are concerned about layout reflows and JavaScript regex performance during the critical phase of loading a document. Raggedast will process static files generated by Jekyll or any similar solution.

Document size

Processing documents with Raggedast will increase the size of your documents since it replaces the regular whitespaces with hard spaces in the form of Unicode character references. If this bothers you, serve your files compressed. The difference between processed and unprocessed document size will then become negligible.

Why the stupid name?

Meet Raggedast, the god of beer and finely ragged chunks of text.

Getting Started

This plugin requires Grunt ~0.4.2

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-raggedast --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-raggedast');

Raggedast

Run this task with the grunt raggedast command.

Options

options.type

Type: String Default value: 'html'

Type of files to be processed. Valid values are either html or json.

options.selector

Type: String Default value: 'p'

Select elements to be processed via selector. Applies only for a type of html.

options.space

Type: String Default value: ' '

The string that is put in place of simple spaces, if for some reason you need to change it to something else.

options.thinSpace

Type: String Default value: ' '

Some words, for example group of numbers, are connected by thin non-breaking space instead of the regular sized. You can change it using this option.

options.words

Type: Boolean Default value: true

Sets whether or not Raggedast tries to find and adjust words that shouldn't end up last on a line, i.e. prepositions, articles and conjunctions. Note that the words are predefined (see the code) and only English is supported as of the moment. The option to serve your own list of words to Raggedast is on the way.

options.symbols

Type: Boolean Default value: true

Targets basic mathematical symbols and spaced en or em dashes (if spaced is the way you like ’em).

options.units

Type: Boolean Default value: true

Looks for a combination of number and some unit of measurement. As before, the units are predefined (see the code) and the list is by no means exhaustive.

options.numbers

Type: Boolean Default value: true

Tries to find numbers separated into groups of thousands for better readability, like 2 435 713, and glue them together by hard spaces.

options.emphasis

Type: Boolean Default value: true

Searches for short emphasized phrases. Short means two to three words long, emphasized suggests the use of either strong, em, b or i.

options.quotes

Type: Boolean Default value: true

Looks for short quotations or phrases enclosed in quotation marks. Short means the same thing as before.

options.months

Type: Boolean Default value: true

If set to true, tries to catch dates with month names written in full. The name can be either long, e.g. ‘December’, or short like in ‘Dec’. The date also has to follow one of the following formats: ‘24 December 2013’ or ‘December 24, 2013’.

options.orphans

Type: Integer Default value: 2

Searches for “orphans” – a word or very short line that appears by itself at the end of a paragraph or any other block of text like headlines. The number stands for the lowest number of words the last line of text can contain. The default setting of 2 is thus the lowest number that still makes sense if you want to use this method. To disable it, set it to 1 or 0.

options.shortWords

Type: Integer Default value: 2

Tries to find the rest of the words that you do not want to appear at the end of a line. The words are targeted by their length, the default 2 matching words such as ‘I’ or ‘he’. By setting the number too high, this method can quickly become very greedy. On the other hand, setting this options to zero turns it off entirely.

options.limit

Type: Integer Default value: 0

This option should come in handy in case you want to tame the hard spaces a little after all the processing. The number implies the longest allowed row of words glued together by hard spaces. For example, with shortWords set to 3, the sentence “It showed a lady fitted out with a fur hat and fur boa who sat upright.” would end up with eleven words transformed into a non-breakable string, starting with the word ‘out’. But if you set limit to 6, it would split that string into two by removing the hard space after the word ‘and’. Obviously, it is always better to do these alterations by hand but in case you process a lot of text, it is not always viable. The default 0 suggests leaving the strings as they are.

options.ignore

Type: String | RegExp Default value: null

Either a selector for a type of html, or a string (for exact matches) or a regular expression for a type of json. In the first case, any element that matches options.selector but also matches the supplied selector is skipped. In the second case, any property of a JSON object that matches the specified pattern is skipped in the same way.

Usage Examples

Default Options

In this example, the default options are used to process the files generated by Jekyll.

grunt.initConfig({
   raggedast: {
      options: {
         type: 'html',
         selector: 'p',
         space: ' ',
         thinSpace: ' ',
         words: true,
         symbols: true,
         units: true,
         numbers: true,
         emphasis: true,
         quotes: true,
         months: true,
         orphans: 2,
         shortWords: 2,
         limit: 0,
         ignore: null
      },
      files: [{
         expand: true,
         cwd: '_site',
         src: ['*.html']
      }],
   },
});

Release History

  • 2015-06-24   v0.3.0   Added option to parse JSON files and ignore patterns.
  • 2014-09-15   v0.2.3   Minor fixes.
  • 2014-01-24   v0.2.2   Prevented whitespace processing inside attributes.
  • 2014-01-23   v0.2.1   Prevented whitespace processing inside tags.
  • 2014-01-22   v0.2.0   Added support for processing dates and orphans.
  • 2014-01-19   v0.1.0   Raggedast released.

Release History

MIT © Adam Havel