Markdown Word Counter
Build a Rust command-line tool that counts the words in Markdown documents the way a reader would see them: it skips code blocks and inline code, counts link text but not the link addresses, ignores Markdown symbols such as # and *, and also estimates reading time. It works on one file, many files or a whole folder of documentation, and can print a per-file table or JSON. It's a good first Rust project: you'll learn reading files, processing text line by line, a small state machine (inside or outside a code block), string handling in Rust, command-line options with clap, JSON output with Serde, and testing.
- Estimate
- ~7.5h
- Steps
- 5
- Completed by
- 0
- Proposed by
- codeseed.app
Cargo · clap · Serde
Project roadmap
- 01
Define the counting rules
~1hWrite README.md with the exact rules: fenced code blocks (``` or ~~~) and indented code are skipped; inline `code` is skipped; for [text](url) only the text is counted; images are skipped; headings, lists and emphasis symbols are removed; and a word is a run of letters, digits and apostrophes. Include a sample file with the expected count. Create a project with clap, serde and serde_json. Done when: README.md defines every rule with an example.
- 02
Skip code blocks
~1.5hRead a file line by line and track whether you're inside a fenced code block with a simple state machine (a fence opens a block, and the same fence closes it). Skip lines inside blocks and indented code lines. Done when: unit tests show code block lines are never counted, including an unclosed block at the end of a file.
- 03
Clean each line and count
~2hFor the remaining lines, remove inline code, replace [text](url) with text, remove images, strip heading, list and quote markers and emphasis symbols, then count words. Keep the cleaning in small functions with tests. Calculate reading time at 200 words per minute. Done when: the sample file's count matches README.md.
- 04
Handle files and folders
~1.5hAccept file and folder paths with clap, finding .md files in folders (with std::fs::read_dir recursively, or the walkdir crate). Report files that can't be read and continue. Print a table with each file's words and reading time, sorted by words, plus a total. With --json, print the results as JSON with Serde. Done when: running on a folder of docs prints a correct table and valid JSON.
- 05
Test it
~1.5hWrite tests for each rule (fences with ~~~, nested backticks, links with parentheses in the text, images, empty files and files with only code), and an integration test running the binary on a fixture folder. Run cargo clippy. Done when: cargo test passes, and clippy has no warnings.
Ready to build this?
Get a GitHub repo and start building. Your AI reviewer checks each step as you go.
Tech stack