Comprehensive word counting and tracking system for authors - track word counts across documents, monitor writing progress, and generate detailed analytics for markdown-based writing projects.
A comprehensive word counting and tracking system for managing writing projects, particularly designed for authors working with markdown files. This skill provides tools for tracking word counts across multiple documents, monitoring writing progress over time, and generating detailed analytics.
#!/usr/bin/env python3
import re
from pathlib import Path
from datetime import datetime
def quick_count(directory="drafts"):
"""Quick word count for all markdown files."""
total = 0
for md_file in Path(directory).glob("*.md"):
text = md_file.read_text(errors='ignore')
words = len(re.findall(r"\b\w+\b", text))
print(f"{md_file.name}: {words:,} words")
total += words
print(f"\nTotal: {total:,} words")
print(f"Date: {datetime.now().strftime('%Y-%m-%d')}")
if __name__ == "__main__":
quick_count()
# Standalone script (simplest)
python scripts/word_tracker_standalone.py --drafts drafts
# Full package version (most features)
python -m scripts.wordcount_tracker.cli --drafts drafts --csv tracker.csv
# With options
python scripts/word_tracker_standalone.py --recursive --report --goal 70000
word-tracker/
├── SKILL.md # Main instructions (this file)
├── REFERENCE.md # Detailed API reference
├── README.md # Quick start guide
└── scripts/
├── word_tracker_standalone.py # Single-file solution
└── wordcount_tracker/ # Full package
├── __init__.py
├── cli.py # Command-line interface
├── scanner.py # File discovery
├── counter.py # Word counting
├── dates.py # Date handling
├── tracker.py # CSV management
└── analytics.py # Reports & statistics
For detailed API documentation and advanced usage, see REFERENCE.md.
# Basic usage
python scripts/word_tracker_standalone.py
# With options
python scripts/word_tracker_standalone.py --drafts manuscripts --recursive --report
Advantages:
# From the skill directory
python -m scripts.wordcount_tracker.cli --drafts drafts --csv tracker.csv
# With advanced features
python -m scripts.wordcount_tracker.cli --recursive --advanced --report --backup
Advantages:
def find_markdown_files(root: Path, recursive: bool = False) -> Iterable[Path]:
"""Find all markdown files in specified directory."""
pattern = "**/*.md" if recursive else "*.md"
return (p for p in root.glob(pattern) if p.is_file())
def count_words(text: str) -> int:
"""Count words using configurable regex patterns."""
# Simple word boundary approach
return len(re.findall(r"\b\w+\b", text))
def count_words_advanced(text: str, exclude_frontmatter: bool = True) -> int:
"""Advanced counting with frontmatter exclusion."""
if exclude_frontmatter and text.startswith("---"):
# Skip YAML frontmatter
_, _, text = text.split("---", 2)
return count_words(text)
@dataclass
class WordCountEntry:
filename: str
word_count: int
date_created: str
date_updated: str = ""
def update_tracker(csv_path: Path, entries: List[WordCountEntry]) -> None:
"""Update CSV tracker with new word counts."""
# Load existing data
# Merge with new entries
# Save back to CSV
The tracker uses this CSV format:
| Column | Type | Description |
|---|---|---|
| Filename | String | Relative path to file |
| Word Count | Integer | Current word count |
| Date Created | Date | YYYY-MM-DD format |
| Date Updated | Date | YYYY-MM-DD or blank for new |
# Count words in drafts folder
python -m wordcount_tracker.cli --drafts drafts --csv word_count_tracker.csv
# Include subfolders
python -m wordcount_tracker.cli --drafts drafts --csv word_count_tracker.csv --recursive
# Specify custom paths
python -m wordcount_tracker.cli --drafts /path/to/manuscripts --csv /path/to/tracking.csv
# Generate weekly report
python -m wordcount_tracker.cli --report weekly
# Set word count goal
python -m wordcount_tracker.cli --goal 50000 --deadline 2024-12-31
# Track multiple projects
python -m wordcount_tracker.cli --project novel --drafts novel/drafts
python -m wordcount_tracker.cli --project stories --drafts short_stories
# For screenplay format
def count_screenplay_words(text: str) -> int:
# Custom logic for dialogue, action, etc.
# For academic papers
def count_academic_words(text: str) -> int:
# Exclude citations, footnotes, etc.
def extract_frontmatter_date(text: str) -> Optional[str]:
"""Extract creation date from YAML frontmatter."""
if text.startswith("---"):
frontmatter = yaml.safe_load(text.split("---")[1])
return frontmatter.get("created", None)
SUPPORTED_FORMATS = {
".md": count_markdown,
".txt": count_plaintext,
".docx": count_docx, # Requires python-docx
".html": count_html, # Strip tags first
}
project/
drafts/ # Active writing
chapter_01.md
chapter_02.md
archive/ # Completed/old versions
reports/ # Generated analytics
word_count_tracker.csv
config.yaml # Project settings
Create a wordtracker.yaml for project-specific settings:
# wordtracker.yaml
drafts_dir: drafts
csv_path: word_count_tracker.csv
recursive: true
exclude_patterns:
- "*.backup.md"
- "notes/*"
word_count:
method: standard # or 'academic', 'screenplay'
exclude_frontmatter: true
exclude_code_blocks: false
reporting:
weekly_goal: 5000
project_goal: 70000
deadline: 2024-12-31
Encoding Errors
errors='ignore' or 'replace' when reading filesDate Detection Issues
Large File Performance
=== Writing Progress Report ===
Period: 2024-10-14 to 2024-10-21
Total Words Written: 12,450
Daily Average: 1,779 words
Best Day: Monday (2,341 words)
Projects:
- Novel: 8,200 words (5 chapters updated)
- Short Stories: 4,250 words (2 new stories)
Progress to Goal: 45,230 / 80,000 (56.5%)
Projected Completion: December 5, 2024
def safe_word_count(path: Path) -> Optional[int]:
"""Safely count words with comprehensive error handling."""
try:
text = path.read_text(encoding='utf-8', errors='replace')
return count_words(text)
except PermissionError:
print(f"Permission denied: {path}")
except IsADirectoryError:
print(f"Is a directory: {path}")
except Exception as e:
print(f"Unexpected error with {path}: {e}")
return None
Real-time Monitoring
Cloud Sync
AI Integration
Visualization
Here's a minimal working example to get started immediately:
#!/usr/bin/env python3
import re
from pathlib import Path
from datetime import datetime
def quick_count(directory="drafts"):
\"\"\"Quick word count for all markdown files.\"\"\"
total = 0
for md_file in Path(directory).glob("*.md"):
text = md_file.read_text(errors='ignore')
words = len(re.findall(r"\b\w+\b", text))
print(f"{md_file.name}: {words:,} words")
total += words
print(f"\nTotal: {total:,} words")
print(f"Date: {datetime.now().strftime('%Y-%m-%d')}")
if __name__ == "__main__":
quick_count()
This skill is specifically designed with fiction authors in mind:
This skill provides a professional-grade word tracking solution that scales from simple single-file counts to complex multi-project manuscript management systems.