Markdown Word Count: Source Text or Rendered Prose?
Blog / TEXT FORMATS
A Markdown word count depends on whether you measure raw source or the text readers see after rendering. CommonMark defines formatting syntax, not a universal word-count rule. Before choosing a counter, decide whether headings, code examples, link destinations, and other source material belong in your total.
Why the source count can be misleading
A Markdown file mixes prose with formatting characters and sometimes metadata or raw HTML. A whitespace-based source counter may count a standalone heading marker as a token. Another counter might ignore that marker but still count words inside an image description or a URL.
For the source line ## Notes on **word counts**, the visible heading is Notes on word counts: four words. A simple whitespace split of the source produces five pieces because ## is separate. This is a concrete difference between source tokens and reader-facing words, not proof that every Markdown extension behaves the same way.
## Notes on **word counts**
Visible heading: Notes on word counts
Prose words: 4
Whitespace-separated source pieces: 5Use the rendered preview for an article-length check
Render the file with the same Markdown implementation your publishing system uses. Copy the relevant visible article into a temporary plain-text document, then count that passage. Inspect the beginning and end of the copy so navigation labels or unrelated page text do not become part of the article.
Keep meaningful headings and list items if the requirement includes them. Decide separately whether code blocks count. A tutorial's code is useful content, but counting every variable and symbol as prose may misrepresent an editorial word limit. Your publisher's brief should settle that decision.
Treat links and images deliberately
In [Read the guide](https://example.org/guide), readers normally see Read the guide: three words. The URL is a link destination, not another sentence. For a prose-only count, measure the displayed label rather than counting the destination as additional writing.
Image descriptions are more subtle. Alternative text supports accessibility and may appear when an image is unavailable, while captions can be visible prose. Do not blindly discard all image-related text. Define whether captions and alternative descriptions belong in the specific total you are reporting.
Avoid stripping markup with one broad replacement
Deleting every character between angle brackets or removing all punctuation can damage examples, links, and legitimate text. Markdown has nested structures and implementation-specific extensions; a broad search-and-replace is not a reliable parser.
Preserve the original source and make a separate counting copy. If you automate a repeated workflow, use a maintained parser compatible with your publishing format and document which node types you include. Test headings, nested lists, code fences, links, and raw HTML before trusting a batch total.
Keep the method consistent across revisions
A prose-only draft count should be compared with another prose-only count. Switching to a raw-file count after adding link references can suggest that the article grew when its visible paragraphs did not. Save the source, check the rendered preview, and measure the agreed scope again before publication.
Frequently asked questions
Does Markdown have a standard word-count rule?
No. CommonMark defines syntax; counters still choose how to handle source material and prose.
Should code blocks count?
Only if the relevant brief includes them. Keep that choice explicit and consistent.
Will a plain word counter remove Markdown automatically?
Do not assume that. For reader-facing prose, inspect and copy the rendered text first.