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-devOnce the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;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;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