Linting and Formatting

🔗

Text linting is much less common than code linting, but if you have to maintain a lot of text it may save you a lot of time, and improve quality of your documentation.

Linting Markdown With Textlint and Proselint

🔗

Text linting is less common than code linting but in large projects with many contributors it could improve documentation quality. You can:

• Validate links.
• Ensure consistent terminology, like JavaScript vs. Java​script or npm vs. N​PM.
• Improve language, like disallowing ju​st, easi​ly and si​mply.

Textlint↗ is an extendable text linter written in JavaScript, it’s a fork of ESLint so setup is similar. And like ESLint it can fix certain rules for you. It has many plugins:

• eslint↗ — checks code examples in Markdown using ESLint (autofixing is also possible).
• common-misspellings↗ — fixes common English misspellings, like simi​liarity → similarity.
• no-dead-link↗ — finds dead links, automatically fixes redirects.
• stop-words↗ — filler words, buzzwords and chiches.
• terminology↗ — checks and fixes terms spelling in your tech writing.
• write-good↗ — tries to improve your English styles.

Proselint↗ is prose linter following the advice of world’s greatest writers and editors, it checks your texts for things like redundancy, jargon, illogic, clichés, sexism, misspelling, inconsistency and misuse of symbols. It has several dozens of rules↗ by default.

It’s written in Python but we recommend using it via a JavaScript wrapper↗ for better UI.

To check Markdown syntax and consistency, try remark-lint↗.

Setting up Textlint

🔗

Let’s install Textlint with several rules:

npm install --save-dev textlint textlint-rule-terminology textlint-rule-common-misspellings textlint-rule-write-good textlint-rule-no-dead-link

Add a script to your package.json like this:

{
  "scripts": {
    "lint:text": "textlint '**/*.md'"
  }
}

Create a config file, .textlintrc:

{
  "rules": {
    "terminology": true,
    "common-misspellings": true,
    "write-good": {
      "adverb": false,
      "passive": false,
      "tooWordy": false,
      "weasel": false
    },
    "no-dead-link": true
  }
}

And finally run:

npm run lint:text

You can run Textlint with autofixing like this: npm run lint:text -- --fix. Don’t forget to commit your texts first because autofixing may introduce changes you don’t want to keep.

Setting up Proselint

🔗

Let’s install Proselint:

pip install proselint
npm install --save-dev proselint

Add a script to your package.json like this:

{
  "scripts": {
    "lint:prose": "proselintjs '**/*.md'"
  }
}

And finally run:

npm run lint:prose

Formatting Markdown With Prettier

🔗

We’re discussed Prettier in great detail in the Code Formatting chapter but it can do more. It can format your Markdown files, and not only text but also code example for languages it supports: JavaScript, TypeScript, CSS, Less, SCSS, JSON, GraphQL, and Markdown.

Setting up Prettier

🔗

Let’s install Prettier:

npm install --save-dev prettier

Add a script to your package.json like this:

{
  "scripts": {
    "prettier": "prettier --write '**/*.md'"
  }
}

Create a config file, .prettierrc:

{
  "printWidth": 68,
  "singleQuote": true,
  "trailingComma": "es5",
  "proseWrap": "never"
}

If you’re using Prettier to format your code, you may want to define different rules for code inside Markdown files:

{
  "printWidth": 100,
  "singleQuote": true,
  "trailingComma": "es5",
  "useTabs": true,
  "proseWrap": "never",
  "overrides": [
    {
      "files": "*.md",
      "options": {
        "printWidth": 68,
        "useTabs": false,
        "trailingComma": "none"
      }
    }
  ]
}

And finally run:

npm run prettier

Conclusion

🔗

Documentation linting is as important as code linting: it helps you to improve quality, find mistakes and keep formatting consistent.