Nelio Content analyzes the quality of my posts. Can I tune its settings?

Nelio Content analyzes the quality of your posts according to different criteria:

This analysis is implemented in JavaScript and can be easily customized by adding a few lines of code in your site.

Post Quality Summary

Depending on the evaluation of the included quality criteria, Nelio Content will report one of the following four states:

• Poor. There are several criteria that are either bad (in red) or improvable (in orange).
• Improvable. Most of your criteria are good (green), but there’s still one bad criterion or several improvable criteria that need addressing.
• Good. Most criteria are good, but there’s still some work to do (i.e. some criteria are improvable).
• Perfect. All criteria are good.

A post will only be perfect if all criteria are good. But if they aren’t, the post quality (poor, improvable, or good) will be computed counting how many criterion have specific statuses. For example, 3 bad criteria will result in a poor post, whereas 3 improvable criteria with no bad ones will result in a good post.

You can tweak what the overall quality should be depending on the number of bad and improvable criteria. To do so, use the updatePostQualitySettings function:

NelioContent.editPost.updatePostQualitySettings( options );

which takes an object with three properties:

• allowedBads: This setting lets you define the number of bad criteria that is “acceptable.” By default, this is set to 1, meaning that two or more bad criteria will result in a poor evaluation.
• unacceptableImprovables: If the combination of bad and improvable criteria is greater than or equal to this number, the overall quality evaluation should also be set to poor. Default value is 2.
• allowedImprovables: Assuming all criteria are either improvable or good, this setting determines how many improvable criteria one can have so that the overall evaluation is still good. If it’s greater than that, the post quality will be improvable. Default value is 4.

You can tweak each value as follows:

NelioContent.editPost.updatePostQualitySettings( {
  allowedBads: 1,
  allowedImprovables: 2,
  unnacceptableImprovables: 4,
} );

The following section describes how to customize each individual criterion.

What Quality Criteria Look Like

A quality criterion in Nelio Content is a JavaScript object with the following attributes:

• icon: a string with the name of a Dashicon.
• interval: the minimum number of milliseconds between two consecutive checks.
• settings: an optional object that one can use to offer customization options for the given criterion.
• attributes: a JavaScript function that takes a select object to read data from the WordPress store and returns an object with all the attributes required to check the status of the criterion.
• validate: a JavaScript function with two arguments (the attributes retrieved in the previous function and the criterion settings) and returns an object with exactly two attributes:
  • status: a string that can either be good, improvable, or bad. It defines the color with which the criterion will be rendered in the UI.
  • text: the label that will be shown next to the icon as part of the criterion.

To add a new criterion, use the registerQualityCheck function, indicating a unique name for said criterion and an object like the one we have just described. To remove a criterion, use the deregisterQualityCheck function with its name:

NelioContent.editPost.registerQualityCheck( name, definition );
NelioContent.editPost.deregisterQualityCheck( name );

Example

One of the default criteria that Nelio Content includes is the content length: depending on how many words you have written, Nelio Content will tell you if it’s enough or not. By default, less than 700 words is an error, between 700 and 1000 is something that’s not bad but should be improved, and over 1000 is okay.

Well, this is how this criterion is defined in Nelio Content:

registerQualityCheck( 'nelio-content/content-length', {
  icon: 'edit',
  interval: 2000,
  settings: {
    improvableThreshold: 700,
    goodThreshold: 1000,
  },
  attributes: ( select ) => {
    const { getContent } = select( 'nelio-content/edit-post' );
    return {
      content: getContent(),
    };
  },
  validate: ( { content }, { improvableThreshold, goodThreshold } ) => {
    const wordCount = countWords( content );
    if ( wordCount < improvableThreshold ) {
      return {
        status: 'bad',
        text: _x( 'Write a longer copy', 'user', 'nelio-content' ),
      };
    }
    if ( wordCount < goodThreshold ) {
      return {
        status: 'improvable',
        text: _x( 'Write a longer copy', 'user', 'nelio-content' ),
      };
    }
    return {
      status: 'good',
      text: _x( 'Copy length looks good', 'text', 'nelio-content' ),
    };
  },
} )

As you can see, it’s pretty straightforward:

• The criterion is named nelio-content/content-length.
• Its icon is edit.
• It can only run every 2 seconds.
• The criterion offers two customization settings:
  • improvableThreshold: minimum number of required words so that the criterion goes from bad to improvable.
  • goodThreshold: minimum number of required words so that the text looks good.
• The attributes function retrieves the post content from the store.
• The validate function counts the number of words included in content and, depending on the criterion settings, it returns an evaluation. For instance, if the content has less than improvableThreshold words, the evaluation is bad and we’re told that we have to “write a longer copy.”

Nelio Content Default Criteria

These are the main default criteria that Nelio Content includes along with its customization attributes:

• nelio-content/author: a post author shouldn’t be a site administrator.
  Setup: a boolean attribute named useBadStatus which indicates the status when things aren’t okay. If it’s set to true, the criterion will evaluate to bad if the author is an administrator. If it’s set to false, it will evaluate to improvable.
• nelio-content/content-images: a post should contain some images.
  Setup: improvableThreshold and goodThreshold.
• nelio-content/content-length: a post should not be too short.
  Setup: improvableThreshold and goodThreshold.
• nelio-content/editorial-tasks: all editorial tasks should be completed.
  Setup: useBadStatus.
• nelio-content/excerpt: a post should have an excerpt.
  Setup: useBadStatus.
• nelio-content/external-links: a post should have some links to external sources.
  Setup: improvableThreshold and goodThreshold.
• nelio-content/internal-links: a post should have some internal links to the site itself.
  Setup: improvableThreshold and goodThreshold.
• nelio-content/featured-image: a post should have a featured image.
  Setup: useBadStatus.
• nelio-content/tags: a post should be properly tagged.
  Setup: useBadStatus.

How To Customize Nelio Content’s Post Quality Evaluation

To customize the quality analysis of Nelio Content you have four options:

• Customize the overall post quality based on the statuses of your criteria using updatePostQualitySettings.
• Add new criteria using registerQualityCheck.
• Remove existing criteria with deregisterQualityCheck.
• Customize existing criteria with updateQualityCheckSettings.

Simply add the following code snippet to your website (as we explain here) with the specific customizations you want:

function nc_customize_criteria() {
  $script = <<<JS
    // Add customizations here.
JS;
  wp_add_inline_script( 'nelio-content-edit-post', $script );
}
add_filter( 'admin_enqueue_scripts', 'nc_customize_criteria' );

For example, imagine we want to lower the required word count thresholds of a post’s copy, as well as remove the images-in-copy check. We can achieve as follows:

function nc_customize_criteria() {
  $script = <<<JS
    NelioContent.editPost.updateQualityCheckSettings(
      'nelio-content/content-length',
      { improvableThreshold: 250, goodThreshold: 500 }
    );
    NelioContent.editPost.deregisterQualityCheck(
      'nelio-content/content-images'
    );
JS;
  wp_add_inline_script( 'nelio-content-edit-post', $script );
}
add_filter( 'admin_enqueue_scripts', 'nc_customize_criteria' );