[{"data":1,"prerenderedAt":69},["Reactive",2],{"blog-post-markdown-word-count-reading-time-how-it-actually-works":3},{"slug":4,"title":5,"description":6,"excerpt":7,"date":8,"category":9,"author":10,"keywords":11,"readingMinutes":12,"html":13,"headings":14,"tools":37,"related":42},"markdown-word-count-reading-time-how-it-actually-works","Markdown Word Count and Reading Time: How the Numbers Actually Get Calculated","\"3 min read\" badges and word counts disagree between tools more often than you'd expect. Here's why: different words-per-minute assumptions, different handling of images, and — the part that matters most for Markdown specifically — whether the tool strips markup before counting at all.","Paste the same Markdown document into two different word-count tools and you'll often get two different numbers — sometimes by a wide margin. Paste it into two different \"reading time\" estimators…","2026-09-11","workflows","Matt Rathbone","markdown word count, reading time calculator, words per minute reading, how reading time is calculated, markdown word count tool, estimated reading time algorithm",7,"\u003Cp>Paste the same Markdown document into two different word-count tools and you'll often get two different numbers — sometimes by a wide margin. Paste it into two different "reading time" estimators and the gap gets even bigger, because now two separate sources of disagreement stack on top of each other: how many words the tool thinks you wrote, and how fast the tool assumes a person reads.\u003C/p>\n\u003Cp>Neither number is "wrong," exactly. They're built on different assumptions, and for Markdown specifically, one of those assumptions — whether the tool strips the markup before counting — matters a lot more than most people expect. This post covers how our own \u003Ca href=\"/tools/markdown-word-count\">Markdown Word Count & Reading Time tool\u003C/a> calculates its numbers, how that compares to what a handful of other well-known platforms do, and the practical implications for anyone publishing Markdown-authored content.\u003C/p>\n\u003Ch2 id=\"the-part-everyone-skips-what-counts-as-a-word-in-markdown-source\">The Part Everyone Skips: What Counts as a "Word" in Markdown Source\u003C/h2>\n\u003Cp>A naive word counter just splits the raw text on whitespace and counts the pieces. Applied directly to Markdown source, this produces a number that's subtly wrong in both directions at once:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>Markup tokens get counted as words.\u003C/strong> A heading marker (\u003Ccode>##\u003C/code>), emphasis delimiters (\u003Ccode>**\u003C/code>/\u003Ccode>_\u003C/code>), a link's URL, and the punctuation around an image reference all split into whitespace-separated tokens. A link like \u003Ccode>[check the docs](https://example.com/very/long/path)\u003C/code> naively counts as two "words" — \u003Ccode>[check\u003C/code> and \u003Ccode>the...\u003C/code> — when a reader only sees "check the docs" as three words of prose, and the URL isn't read as words at all.\u003C/li>\n\u003Cli>\u003Cstrong>Some real prose gets undercounted.\u003C/strong> A sentence broken across multiple soft-wrapped lines inside a blockquote, or text sitting inside a table cell, can get miscounted depending on how the splitter handles the surrounding \u003Ccode>>\u003C/code> or \u003Ccode>|\u003C/code> characters.\u003C/li>\n\u003C/ul>\n\u003Cp>The practical effect is that a heavily-linked reference document or a page full of tables and images can show a meaningfully inflated or deflated word count compared to a plain-prose post of the same actual reading length — purely as an artifact of how much Markdown syntax surrounds the words, not because the tool is "buggy." It's just measuring markup density, not prose length.\u003C/p>\n\u003Cp>Our tool strips Markdown syntax first — heading markers, bold/italic delimiters, link brackets and target URLs, image syntax — before it counts anything, so the word count reflects the words a reader would actually see rendered, not the raw character soup of the source file. If you're comparing a word count from our tool against a plain \u003Ccode>wc -w\u003C/code> on the raw \u003Ccode>.md\u003C/code> file, expect them to disagree, and expect the difference to grow with how markup-heavy the document is.\u003C/p>\n\u003Ch2 id=\"how-our-tool-calculates-reading-time\">How Our Tool Calculates Reading Time\u003C/h2>\n\u003Cp>Once the stripped word count is in hand, reading time is estimated at \u003Cstrong>238 words per minute\u003C/strong> — the average adult silent-reading speed for meaningful, non-skimmed text, from a 2019 meta-analysis by Brysbaert et al. that reviewed reading-speed studies going back decades. It's a plain word-count-divided-by-rate calculation with no adjustments for images, code blocks, or content type, rounded up to the next whole minute (a document estimated at 0.4 minutes still shows "1 min read" — nobody wants to see "0 min read").\u003C/p>\n\u003Cp>The full stat panel reports ten numbers total: words, minutes to read, characters (with and without spaces), sentences (approximated from sentence-ending punctuation), paragraphs (blank-line-separated blocks, excluding headings and code blocks), headings, links, images, and fenced code blocks. All ten are computed from a single pass over the stripped and structural-element-tagged text, so they stay consistent with each other — the word count you see is the same one the reading-time estimate is based on.\u003C/p>\n\u003Ch2 id=\"why-other-tools-give-you-a-different-number\">Why Other Tools Give You a Different Number\u003C/h2>\n\u003Cp>If you've ever seen a "3 min read" badge on a blog post and thought it felt off, here's why estimates vary so much between platforms — it's not just a different WPM constant, though that's part of it:\u003C/p>\n\u003Cp>\u003Cstrong>The words-per-minute assumption itself varies widely.\u003C/strong> Published estimates for silent reading of average material range from roughly 200 to 275+ WPM depending on the study and the type of content being read (technical or unfamiliar material is read slower than casual prose). Plenty of blogging tools and CMS plugins default to a round number like 200 WPM rather than a research-cited figure, simply because it's an easy default to ship and adjust later.\u003C/p>\n\u003Cp>\u003Cstrong>Some platforms add fixed time for images on top of the word count\u003C/strong>, rather than relying on WPM alone. The best-known example is Medium's publicly documented reading-time algorithm: it adds 12 seconds for the first image in a post, decreasing by one second for each subsequent image down to a floor of 3 seconds per image, on top of a roughly 265-WPM word-based estimate. The reasoning is that a reader's eye pauses on an image for a real, measurable amount of time that a pure word count doesn't capture at all — the more images a post has, the more this pushes the total above what word count alone would suggest. Several open-source reading-time libraries (used by a number of blogging platforms and static-site plugins) borrow this same image-time-plus-word-time approach rather than inventing their own.\u003C/p>\n\u003Cp>\u003Cstrong>Some don't strip markup, or strip it differently.\u003C/strong> A platform's reading-time calculator that runs on already-rendered HTML text (stripping HTML tags rather than Markdown syntax) will produce a different word count than one that runs on raw Markdown source and strips Markdown syntax — the two aren't measuring quite the same input, even when both claim to be counting "the words in the post."\u003C/p>\n\u003Cp>\u003Cstrong>A few platforms don't estimate reading time at all\u003C/strong>, and it's added manually by the author, via a separate plugin, or not shown at all — so "no reading time badge" doesn't necessarily mean "short post," just that the platform doesn't calculate one.\u003C/p>\n\u003Cp>None of this makes any single number more "correct" than another — they're all reasonable estimates built on different, defensible assumptions. But it explains why you shouldn't expect two tools to agree, and why a reading-time badge is a rough signal, not a precise measurement.\u003C/p>\n\u003Ch2 id=\"quick-reference-what-varies-between-reading-time-approaches\">Quick Reference: What Varies Between Reading-Time Approaches\u003C/h2>\n\u003Cdiv class=\"table-responsive\">\u003Ctable class=\"table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth align=\"left\">Factor\u003C/th>\n\u003Cth align=\"left\">What it affects\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd align=\"left\">WPM assumption (commonly 200–275)\u003C/td>\n\u003Ctd align=\"left\">The baseline word-count-to-minutes conversion; higher WPM = shorter estimated time for the same word count\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">Markup-stripping before counting\u003C/td>\n\u003Ctd align=\"left\">Whether Markdown/HTML syntax inflates or deflates the "word" count itself, before WPM is even applied\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">Fixed per-image time (Medium-style algorithms and the libraries that copy the approach)\u003C/td>\n\u003Ctd align=\"left\">Adds extra seconds per image on top of the word-based estimate, so image-heavy posts read as longer than their word count alone suggests\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">Content-type adjustment\u003C/td>\n\u003Ctd align=\"left\">Some estimators don't adjust for this at all (ours doesn't); others informally assume technical/code-heavy content is read slower, though this is far less standardized across tools than the WPM constant itself\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd align=\"left\">Whether reading time is shown at all\u003C/td>\n\u003Ctd align=\"left\">Some platforms simply don't calculate or display it, which isn't itself a signal about post length\u003C/td>\n\u003C/tr>\n\u003C/tbody>\u003C/table>\u003C/div>\n\u003Ch2 id=\"practical-implications-for-writers\">Practical Implications for Writers\u003C/h2>\n\u003Cp>None of this is purely academic if you're publishing regularly:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>Reading-time badges are directional, not precise.\u003C/strong> Treat "5 min read" as "this will take you a few minutes," not a literal stopwatch prediction — actual reading speed for any individual reader varies enormously based on familiarity with the topic, whether they're skimming or reading closely, and whether the content is prose or dense technical material.\u003C/li>\n\u003Cli>\u003Cstrong>Word count is still useful as a length gauge\u003C/strong>, independent of the reading-time conversion — the raw number tells you whether a post is thin (worth expanding) or sprawling (worth tightening), which is a more actionable signal than the derived minutes figure.\u003C/li>\n\u003Cli>\u003Cstrong>If you're comparing counts across tools, check whether markup is stripped.\u003C/strong> A count taken directly off the raw \u003Ccode>.md\u003C/code> file (e.g., a quick \u003Ccode>wc -w\u003C/code>) will run higher than a count taken after Markdown syntax is stripped, and the gap grows with how link- and formatting-heavy the document is — this is the single most common source of "why don't these two numbers match" confusion.\u003C/li>\n\u003Cli>\u003Cstrong>Structural stats (headings, code blocks, links, images) are often more useful than the word count alone\u003C/strong> when you're doing an editorial pass — a post with far more headings than paragraphs might be under-developed per section; one with a high image count but few words of surrounding prose might need more explanatory text around each image.\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"use-cases\">Use Cases\u003C/h2>\n\u003Cul>\n\u003Cli>\u003Cstrong>Pre-publish checks\u003C/strong>: confirm a draft hits a target length before it goes out, without needing to open a separate word processor\u003C/li>\n\u003Cli>\u003Cstrong>README and documentation length audits\u003C/strong>: spot check whether a README has grown unwieldy, or whether a section is too thin to be useful\u003C/li>\n\u003Cli>\u003Cstrong>Editorial workflows\u003C/strong>: use the structural stats (headings, paragraphs, code blocks) alongside the word count to catch under-developed sections, not just short posts\u003C/li>\n\u003Cli>\u003Cstrong>Cross-tool sanity checks\u003C/strong>: if a CMS's built-in word count disagrees with ours, the tables above cover the most likely reasons why, rather than assuming either number is broken\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"related-tools\">Related Tools\u003C/h2>\n\u003Cp>If you're checking a document's length and structure, our \u003Ca href=\"/tools/markdown-linter\">Markdown Linter\u003C/a> catches heading-hierarchy and formatting issues the word-count stats won't surface on their own, and the \u003Ca href=\"/tools/markdown-editor\">Markdown Live Preview Editor\u003C/a> lets you see exactly how the stripped, rendered version of your document looks before you publish. If your document is long enough that navigation matters, our \u003Ca href=\"/tools/markdown-toc\">Table of Contents Generator\u003C/a> builds one automatically from your headings.\u003C/p>\n",[15,19,22,25,28,31,34],{"id":16,"text":17,"level":18},"the-part-everyone-skips-what-counts-as-a-word-in-markdown-source","The Part Everyone Skips: What Counts as a \"Word\" in Markdown Source",2,{"id":20,"text":21,"level":18},"how-our-tool-calculates-reading-time","How Our Tool Calculates Reading Time",{"id":23,"text":24,"level":18},"why-other-tools-give-you-a-different-number","Why Other Tools Give You a Different Number",{"id":26,"text":27,"level":18},"quick-reference-what-varies-between-reading-time-approaches","Quick Reference: What Varies Between Reading-Time Approaches",{"id":29,"text":30,"level":18},"practical-implications-for-writers","Practical Implications for Writers",{"id":32,"text":33,"level":18},"use-cases","Use Cases",{"id":35,"text":36,"level":18},"related-tools","Related Tools",[38,39,40,41],"markdown-word-count","markdown-linter","markdown-editor","markdown-toc",[43,53,61],{"slug":44,"title":45,"description":46,"excerpt":47,"date":48,"category":49,"author":50,"keywords":51,"readingMinutes":52},"how-to-convert-word-documents-to-markdown","How to Convert Word Documents to Markdown: Complete Guide","Learn multiple methods to convert Microsoft Word documents to Markdown format. Includes Pandoc, online tools, and manual conversion techniques with examples.","Converting Microsoft Word documents to Markdown format is a common need for developers, technical writers, and content creators moving to Markdown-based workflows. Whether you're migrating…","2025-08-05","Tutorial","Matthew Rathbone","word to markdown, convert word document to markdown, docx to markdown converter, pandoc word markdown",5,{"slug":54,"title":55,"description":56,"excerpt":57,"date":58,"category":9,"author":10,"keywords":59,"readingMinutes":60},"markdown-to-word-docx-what-converts-cleanly","Markdown to Word (DOCX): What Converts Cleanly and What Doesn't","Converting Markdown to a Word document for stakeholders, legal review, or print? Here's what survives the trip cleanly, what gets mangled, and which conversion method to use.","Markdown is great until someone who doesn't use Markdown needs to read your document. A legal team wants track changes. A client wants a Word file they can comment on. A stakeholder wants…","2026-07-03","markdown to word, markdown to docx, convert markdown to word document, pandoc markdown to docx, markdown to word converter, docx from markdown, markdown word document",9,{"slug":62,"title":63,"description":64,"excerpt":65,"date":66,"category":49,"author":50,"keywords":67,"readingMinutes":68},"how-to-add-line-numbers-to-code-blocks-in-markdown","How to Add Line Numbers to Code Blocks in Markdown: Complete Guide","Learn how to display line numbers in Markdown code blocks using GitHub, Jekyll, Hugo, and other platforms. Includes syntax highlighting and customization options.","Line numbers in code blocks significantly improve code readability and make it easier to reference specific lines in documentation, tutorials, and code reviews. While standard Markdown doesn't…","2025-08-13","markdown line numbers, code block line numbers, markdown syntax highlighting, numbered code blocks, markdown programming examples",6,1792184947057]