Paragraph length

What this check does

Splits the body content into paragraphs (by <p> tags, by double newlines in Markdown), counts words in each, and reports the average and maximum length. Flags paragraphs over 80 words as too long.

Why it matters

People don’t read web pages — they scan them, as Nielsen Norman documented in eye-tracking studies going back to 1997 and replicated every few years since. Long paragraphs are visual cliffs: scanners hit them, decide it looks like work, and bounce.

The effect is amplified on mobile, where an 80-word paragraph fills the entire screen and looks even more daunting. Yoast SEO’s readability analysis (which a sizeable chunk of the WordPress world tunes against) flags any paragraph over 150 words as a hard fail — we use 80 as the warning threshold because mobile screens are smaller now than they were in 2010.

How to fix it

Break paragraphs over 80 words into 2–3 shorter ones. The natural split points:

• When the subject changes (“Now, on the technical side…”).
• When you reach a new step or beat in an argument.
• After a sentence that would work as a standalone takeaway.
• Before any list, code block, or quote.

Before (one 120-word block):

When you’re setting up HTTPS on nginx, there are a few things you need to think about. First, you need to make sure your certificate is valid and trusted by the major browsers, which usually means using Let’s Encrypt or another widely-trusted CA. Once that’s installed, you’ll want to configure the protocols and ciphers to disable anything weak — TLS 1.0 and 1.1 are deprecated, and a number of older cipher suites have known vulnerabilities. You’ll also want to set up HSTS to prevent downgrade attacks, but be careful about the max-age you set, because once a browser has seen the HSTS header, it will refuse to connect over plain HTTP for that duration, even if your certificate expires.

After (three paragraphs):

When you’re setting up HTTPS on nginx, three things matter most: a valid certificate, modern protocols, and HSTS.

Get a certificate from Let’s Encrypt or another trusted CA. Then disable old protocols — TLS 1.0 and 1.1 are deprecated — and remove known-weak cipher suites.

Finally, set up HSTS so browsers refuse downgrade attacks. Be careful with the max-age: once a browser has seen the header, it ignores plain-HTTP fallback until the timer expires.

Same information, three times more likely to be read.

Other readability levers (each is its own check):

• Long sentences — long sentences in short paragraphs still fail.
• Average sentence length — pace.
• Passive voice — long and passive is the worst combination.
• Flesch-Kincaid grade — overall complexity score.

Frequently asked questions

Should every paragraph be one sentence?

No. One-sentence paragraphs work for emphasis but lose rhythm at scale. Aim for 2–4 sentences per paragraph, with the occasional one-liner for emphasis. The point is variation, not extremes.

What about technical documentation with long explanations?

Break them up anyway. Long doesn’t mean dense — you can write a thorough technical paragraph in 80 words by leaning on lists, code blocks, and tables when the content gets dense. If a paragraph genuinely needs 200 words to make its point, ask whether it should be a list or a separate section.

Does this affect SEO directly?

Not as a documented ranking factor. But the helpful-content system explicitly looks for content “easily scanned” and “well-organized” — and bounce rate, time-on-page, and scroll depth all correlate with rankings. Walls of text hurt those, so they hurt rankings transitively.