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. Javascript or npm vs. NPM.
- Improve language, like disallowing just, easily and simply.
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 similiarity โ 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.
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
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.