Skip to main content

Proofread Your Documentation

Catch spelling and grammar issues with the built-in proofreader.

Great Docs includes a proofread command that checks your documentation for spelling mistakes, grammar issues, and common writing problems. It uses Harper, a fast, privacy-focused grammar checker that runs entirely on your machine—no data leaves your computer.

Install Harper

The proofreader requires Harper to be installed separately. It’s a single binary with no dependencies:

Terminal
brew install harper

If you have Rust’s package manager installed:

Terminal
cargo install harper-cli

Download pre-built binaries from the Harper releases page.

Verify the installation:

Terminal
harper-cli --version

Basic Usage

Run the proofreader on your documentation site:

Terminal
great-docs proofread

This checks your site’s authored .qmd and .md pages and the package’s README.md, then reports any issues found. By default, rules that often produce false positives in technical documentation, such as those that flag code terms or formatting conventions, are disabled.

Filtering by File

Check specific files or patterns:

Terminal
# Check one file
great-docs proofread user-guide/getting-started.qmd

# Check .qmd and .md pages recursively in a directory
great-docs proofread recipes/

Adding Custom Dictionary Words

Technical documentation often includes domain-specific terms that aren’t in standard dictionaries. Add them with the -d or --dictionary option:

Terminal
great-docs proofread -d myterm -d anotherterm

To reuse custom words, save one word per line in a file and pass it with --dictionary-file:

Terminal
# words.txt contains one word per line
great-docs proofread --dictionary-file words.txt

Great Docs includes a built-in dictionary of common technical terms (like “API”, “CLI”, “PyPI”, “navbar”, etc.) that are automatically accepted.

Strict Mode

The default settings skip rules that often produce false positives in technical writing. To enable all Harper rules:

Terminal
great-docs proofread --strict

This 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:

Terminal
# Only spelling errors
great-docs proofread --spelling-only

# Only grammar issues
great-docs proofread --grammar-only

Machine-Readable Output

For CI integration or scripting, use JSON output:

Terminal
great-docs proofread --json-output

Or a compact one-line-per-issue format:

Terminal
great-docs proofread --compact

CI Integration

Add proofreading to your CI pipeline to catch issues before they reach production:

.github/workflows/docs.yml
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Harper
        run: cargo install harper-cli

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: pip install great-docs

      - name: Proofread documentation
        run: great-docs proofread

The command exits with a non-zero status if any issues are found, so CI will fail on spelling or grammar problems.

What Gets Checked

The proofreader examines:

  • The authored .qmd and .md pages: the homepage source and pages in the user guide, section and custom page directories. Generated pages, such as the API reference, are excluded.
  • The package’s README.md
  • Prose content only—fenced code blocks and YAML frontmatter are automatically skipped
  • Inline code (backticked text) is checked for typos

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 (e.g., “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 if you want maximum coverage.

Dialect Support

Harper supports different English dialects. The default is American English. To use British English:

Terminal
great-docs proofread --dialect uk

Available values are us (American, the default), uk (British), au (Australian), in (Indian) and ca (Canadian).