Skip to content
 

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:

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.

Nextโ†’

Comments
๐Ÿ”—