Markdown Stats — Word count, reading time, headings, TODOs

What Markdown documents get analysed

Reading-time and structure checks are most useful before publishing — which means the input is almost always an unpublished draft. Pre-publication blog posts, README reviews before a repo push, internal documentation audits, and OSS project changelogs under review are all typical inputs. The content is at a stage where the author has not yet chosen to share it.

TODO progress tracking (- [ ] / - [x]) is designed for PROJECT.md and TODO.md files, which typically contain task assignments, project status, and team context — internal information by nature.

Online word counters and the drafts they receive

Online word-count and reading-time tools process submissions server-side. A draft blog post, a design document under review, or a project status file submitted for a word count lands in the server’s request log. The statistics requested are trivial to compute locally; the draft content is not trivial to expose.

MDX files add another dimension: they may contain React component names, prop values, and import statements alongside the prose. An analysis tool that receives a full MDX file receives application code structure as well as document content.

A zero-dependency scanner running in the browser

This tool’s ~430-line custom scanner — no marked, no remark, no external parser — runs entirely in browser JavaScript. ATX headings (# foo) and Setext headings are detected. Fenced code blocks (```) and 4-space indented blocks are excluded from word and link counts. Frontmatter (--- … ---) is separated from body content. TODO checkboxes are counted. GitHub-style anchor slugs are generated for the heading outline. All of this is local.

Input Markdown lives only in page memory. Drafts, internal project files, and MDX source code can all be analysed without leaving the browser.

Content quality workflow before publishing

Typical checks before hitting publish: Is the reading time appropriate? Is the heading hierarchy correct (no H3 without H2)? Are the external links correctly listed? Is TODO progress at the expected level? The heading outline can be fed directly to markdown-toc to generate a table of contents, and case-counter covers the case when you only need plain character / line counts. All of these checks run on the draft before it goes anywhere.

Word-count semantics: Latin tokens vs. CJK, and the 235 wpm convention

Word counting is fundamentally different across writing systems. English and other Latin-script languages have explicit inter-word whitespace, so tokenising “It is a test.” into 'It', 'is', 'a', 'test' gives a defensible count of 4. Japanese, Chinese, and Korean (CJK) have no word boundaries — there is no native concept of “word” without running a morphological analyser like kuromoji or MeCab. This tool’s compromise is to count each CJK character as one word; in practice the resulting numbers track close to MeCab token counts for typical Japanese prose, which feels more intuitive to writers than a character-only count.

Reading time uses 235 words per minute, the figure popularised by Medium. Academic literature varies — Carver, Coon, & Davis (1990) report 250-300 wpm for oral reading; Brysbaert (2019) places silent reading at 175-300 wpm with substantial individual variation; 235 sits near the centre. Japanese reading speed depends on the kanji / kana mix and cannot be mapped cleanly to Western wpm, but 235 functions as a widely accepted convention for “approximate reading time” on blog posts. Highly technical material reads more slowly; short-form social copy reads faster. Treat the figure as a rough guide and adjust mentally for the genre.

The traps in naive Markdown statistics: code blocks, frontmatter, and tables

The biggest pitfall in word counting is treating code inside fenced blocks as prose. Lines like for (let i = 0; i < arr.length; i++) mix symbols and identifiers in a way that wildly inflates a naïve word count. This tool excludes content inside ``` fences and 4-space indented code blocks from the word total. Many online word counters do not — which is why technical articles tend to show absurd word counts in those tools.

Frontmatter blocks (----delimited YAML metadata at the top of a file) cause similar errors when treated as body: title: My Article would be counted as a heading or two words rather than metadata. This tool detects and separates frontmatter before counting. GFM tables (| col1 | col2 |) present an ambiguity — should the cell separators count? — and this tool counts cell text as words while excluding the | characters themselves. If you want consistent numbers between this tool and a build-time count in Hugo / Astro / Next.js, run a custom script that applies the same exclusions; wc -w from the Unix toolchain does not distinguish frontmatter or fences and produces overestimates for Markdown.