Nanometer Process Machine

    grunt-raggedast

    0.3.0 • Public • Published

    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

    Install

    npm i grunt-raggedast

    DownloadsWeekly Downloads

    2

    Version

    0.3.0

    License

    none

    Last publish

    Collaborators

    • rizzenvrinn