Proofreading
Good documentation requires accurate spelling and grammar. Great Docs includes a proofreading command that checks your documentation for spelling mistakes, grammar issues, and common writing problems using Harper, a fast, privacy-focused grammar checker that runs entirely on your machine.
Installing Harper
The proofreader requires Harper to be installed separately. It’s a single binary with no dependencies:
brew install harpercargo install harper-cliDownload pre-built binaries from the Harper releases page.
Verify the installation:
harper-cli --versionWhat Gets Checked
The proofreader reads the same .qmd and .md pages as the link checker:
- The homepage source
- The pages in the user guide directory
- The pages in each section directory
- The pages in each custom page directory
- The
README.mdfile at the package root
Within page directories, paths with any part starting with _ or . are skipped. Generated pages, such as the API reference, are not checked. A recipes/ directory is read only when a section lists it.
With --include-docstrings, the proofreader also checks docstrings in the documented package’s Python files.
Within .qmd pages, the proofreader skips:
- Fenced code blocks - Content between
```markers - YAML frontmatter - Content between
---markers at the start of files
Inline code (backticked text) is checked for typos.
Basic Usage
Run the proofreader from your project directory:
great-docs proofreadThis checks all documentation files and reports any issues found. By default, rules that tend to produce false positives in technical documentation are disabled.
Filtering by File
Check specific files or patterns:
# Check one file
great-docs proofread user-guide/getting-started.qmd
# Check pages recursively in a directory
great-docs proofread recipes/
# Check .qmd pages directly in a directory
great-docs proofread recipes/*.qmdA directory argument expands into its .qmd and .md pages, including pages in subdirectories. As with the default page search, paths with a component starting with _ or . below the specified directory are skipped.
Custom Dictionary
Adding Words on the Command Line
For project-specific terminology, add custom words using -d:
great-docs proofread -d "griffe" -d "pkgdown" -d "navbar"Built-in Technical Dictionary
Great Docs includes a built-in dictionary of common technical terms (API, CLI, PyPI, navbar, docstring, etc.) that are automatically accepted. To disable this:
great-docs proofread --no-builtin-dictionaryStrict Mode
The default settings skip rules that often produce false positives in technical writing. To enable all Harper rules:
great-docs proofread --strictThis is useful for final polishing or when writing prose-heavy content like blog posts.
Spelling-Only or Grammar-Only
Focus on just one type of check:
# Only spelling errors
great-docs proofread --spelling-only
# Only grammar issues
great-docs proofread --grammar-onlyEnglish Dialect
Harper supports different English dialects. The default is American English. To use British English:
great-docs proofread --dialect ukAvailable values are us (American, the default), uk (British), au (Australian), in (Indian) and ca (Canadian).
Output Formats
Default Output
The default output groups issues by file with context:
user-guide/getting-started.qmd:
Line 12: "recieve" - Did you mean "receive"?
Line 45: Consider using "use" instead of "utilize"
Compact Output
For a condensed one-line-per-issue format:
great-docs proofread --compactJSON Output
For programmatic processing or CI integration:
great-docs proofread --json-outputCI/CD Integration
GitHub Actions
Add proofreading to your CI workflow:
.github/workflows/docs.yml
name: Documentation
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
proofread:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Install Harper
run: cargo install harper-cli
- name: Set up Python
uses: actions/setup-python@v6
with:
python-version: '3.12'
- name: Install dependencies
run: pip install great-docs
- name: Proofread documentation
run: great-docs proofreadPre-commit Hook
Add proofreading as a pre-commit hook:
.pre-commit-config.yaml
repos:
- repo: local
hooks:
- id: proofread
name: Proofread Documentation
entry: great-docs proofread
language: system
types: [markdown]
pass_filenames: falseExit Codes
| Code | Meaning |
|---|---|
| 0 | No issues found |
| 1 | Issues found or error occurred |
Default Ignored Rules
By default, these Harper rules are disabled because they frequently trigger on valid technical documentation patterns:
- Spacing rules - Technical docs often have unconventional spacing around operators and in code
- Capitalization rules - Many technical terms have specific capitalization (macOS, iOS)
- Compound word rules - Technical terms like navbar, frontend, codebase are flagged as compounds
- Punctuation rules - Quote marks and dashes in code examples differ from prose conventions
Use --strict to enable all rules.
Best Practices
- Install Harper in CI - Use
cargo install harper-cliin your workflow - Run proofread in CI to catch issues before they reach production
- Use
--strictsparingly - Default settings are tuned for technical docs - Add project-specific terms with
-dfor domain-specific vocabulary - Combine with link checking for comprehensive documentation QA:
great-docs check-links && great-docs proofreadProgrammatic Usage
Call GreatDocs.proofread() from Python to use the same dictionary and rule defaults as great-docs proofread. It returns a list of checked files, each with a file path, issues and an error message if checking failed:
from great_docs import GreatDocs
docs = GreatDocs()
# Basic proofread
results = docs.proofread()
for file_result in results:
if file_result.issues:
print(f"{file_result.file}: {len(file_result.issues)} issues")
# With custom dictionary
results = docs.proofread(
custom_words=["griffe", "pkgdown"],
)
# Strict mode (all rules enabled)
results = docs.proofread(strict=True)
# Check docstrings in the package's Python files
results = docs.proofread(include_docstrings=True)
# Process results
for file_result in results:
if file_result.error:
print(f"{file_result.file}: not checked ({file_result.error})")
for issue in file_result.issues:
print(f"Line {issue.line}: {issue.message}")
if issue.suggestions:
print(f" Suggestions: {issue.suggestions[:3]}")Use dialect, only_rules and ignore_rules as you would the CLI options --dialect, --only and --ignore. A missing harper-cli raises RuntimeError for the whole run, including runs that check only .qmd pages.
Next Steps
Proofreading catches the small errors that accumulate over time: misspellings, repeated words, and style inconsistencies. Run it alongside the link checker and linter to keep your documentation polished.
- Link Checker validates that all links in your documentation resolve correctly
- Docs Linting checks docstring directives, cross-references, and structural issues
- Configuration describes the project settings available in
great-docs.yml