Textlint

To increase the quality of Frontity's documentation the repository includes textlint, a tool that will generate a report over the texts added or modified to the repo

You will have to install the dependencies of the repo by doing npm i so this tool can work properly

Most of the rules used by textlink will generate just a warning (⚠️) but a few of them will generate an error (⛔️). No errors are allowed in the commits so they should be fixed to be able to complete the commit

Most of these errors detected can be fixed by doing npx textlink --fix <pattern-files>

Rules

The rules used to generate the reports are the ones specified under the textlint property in the package.json. For now they are:

• ⚠️ textlint-rule-alex: Alex helps you find gender favouring, polarising, race related, religion inconsiderate, or other unequal phrasing.
• ⚠️ textlint-rule-common-misspellings: Check common misspellings from Wikipedia: Lists of common misspellings.
• ⚠️ textlint-rule-en-capitalization: Check and fix capitalization.
• ⚠️ textlint-rule-no-empty-section: Check for empty sections.
• ⚠️ textlint-rule-no-exclamation-question-mark: Disallow exclamation and question marks.
• ⚠️ textlint-rule-one-sentence-per-line: A fixable textlint rule adding a line break after each sentence, also known as Semantic Line Breaks (SemBr).
• ⚠️ textlint-rule-period-in-list-item: Check with or without period in list item.
• ⚠️ textlint-rule-rousseau: Check English sentence using rousseau.
• ⚠️ textlint-rule-spelling: Check spellings with much more language dictionaries.
• ⛔️ textlint-rule-terminology: Check and fix correct terms spelling. Check the default terminology.
• ⚠️ textlint-rule-write-good: Proofreading with btford/write-good. "write good" is a "naive linter for English prose for developers who can't write good and wanna learn to do other stuff good too."

We can also manually launch the report over some the files we want by doing npx textlint [file]

Example

This commit generates several warnings that we can take into account (or not) to improve the quality of the text we add, but these warnings doesn't block the commit (the commit is completed)

At the end of the report the tool informs us that some of the warnings detected can be automatically fixed by using npx textlint --fix [file]

> git commit -m "files cli"
husky > pre-commit (node v10.15.3)
✔ Preparing...
✔ Hiding unstaged changes to partially staged files...
✔ Running tasks...
✔ Applying modifications...
✔ Restoring unstaged changes to partially staged files...
✔ Cleaning up...

ℹ textlint:

.../gitbook-docs/docs/frontity-cli/create-package.md
   4:1   warning  suggestion(readibility) sentence is hard to read                   rousseau
   4:8   warning  warning(passive) "be executed" may be passive voice                rousseau
   4:8   warning  "be executed" may be passive voice                                 write-good
   4:11  warning  [executed] Be careful with “executed”, it’s profane in some cases  alex
  15:1   warning  suggestion(readibility) sentence is hard to read                   rousseau

.../gitbook-docs/docs/frontity-cli/create.md
   4:1  ✓ warning  Paragraph: Follow the standard capitalization rules for American English.
See https://owl.english.purdue.edu/owl/resource/592/01/  en-capitalization
   4:1  warning    error(sentence:uppercase) sentence should start with an uppercase letter
Suggestions:
=> Git   rousseau
  23:1  warning    suggestion(readibility) sentence is hard to read                           rousseau

.../gitbook-docs/docs/frontity-cli/serve.md
  21:3  warning  suggestion(readibility) sentence is hard to read  rousseau

.../gitbook-docs/docs/frontity-cli/subscribe.md
  18:48  warning  warning(passive) "be sent" may be passive voice
Suggestions:
=> sent  rousseau
  18:48  warning  "be sent" may be passive voice                   write-good

✖ 11 problems (0 errors, 11 warnings)
✓ 1 fixable problem.
Try to run: $ textlint --fix [file]

[frontity-cli 78ea438] files cli
 7 files changed, 8 insertions(+), 8 deletions(-)

Disabling Rules

Textlint can be disabled in a file by using the comments <!-- textlint-disable --> and <!-- textlint-disable -->. With these comments you can disable rules (all of them or specific ones) in a file or in a piece of text

...
* [⚙ Frontity Packages](api-reference-1/README.md)
  <!-- textlint-disable terminology -->
  * [frontity](api-reference-1/frontity.md)
  <!-- textlint-enable terminology -->
  * [@frontity/tiny-router](api-reference-1/router.md)
  ...