npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

quality-docs

v3.3.0

Published

A CLI tool to evaluate the quality of writing in your project's markdown files.

Downloads

15

Readme

quality-docs

Screenshot

A CLI tool to check the quality of writing in your project's markdown or plain text documentation.

This tool uses retext to check the quality of writing in your project's documentation using these plugins;

Table of Contents

Installation

Install the tool globally with npm to use the CLI.

npm install -g quality-docs

Usage

CLI

The CLI accepts one argument which is a glob of the documentation files you want to check. For example, to recursively check every .md file in your project;

quality-docs {,**/}*.md

Silent Mode

The -s, --silent flag enables silent mode which mutes warnings. Fatal errors are displayed in silent mode.

Config

The -c, --config flag passes in a JSON file with a custom config. The config is combined with default-config.json and the custom config overrides the defaults.

quality-docs {,**/}*.md --config custom-config.json

The override uses this format (without comments):


{
  "dictionaries": "sparkart.dic", // Path to custom dictionary file, relative to config file
  "rules": { // Turn rules on/off or change their severity
    "filler": {"severity": "warn"},
    "hedge": {"severity": "suggest"},
    "list-item-content-indent": false,
    "no-auto-link-without-protocol": false,
    "retext-readability": {
      "age": 18,
      "minWords": 7,
      "severity": "fatal"
    },
    "weasel": {"severity": "suggest"}
  },
  "ignore": [ // Words or phrases to ignore
    "can",
    "forward",
    "found",
    "start",
    "started",
    "up"
  ],
  "noIgnore": [ // Words or phrases ignored by default to not ignore
    "require",
    "transmit"
  ]
}

Ignore

When used along with the config flag, the -i, --ignore flag adds a word to the config file's ignore list. Example;

$ quality-docs {,**/}*.md --config custom-config.json --ignore irregardless
Added 'irregardless' to ignore list. Don't forget to commit the changes to custom-config.json.

Reports

The tool uses vfile-reporter to print a report of writing quality issues with their location and description. For example, a spelling error in README.md from line 76 column 119 to line 76 column 124 prints;

README.md
  76:119-76:124  error    thier is misspelled         spelling

Custom Dictionary

By default, quality-docs spell checks documents against a US English dictionary. To extend the built in dictionary with custom English terms related to your project(s), add a hunspell format .dic file to your project, and reference it with the customDictionary key in a custom config JSON file. See en_US-tech-industry.dic for an example. (Note: quality-docs uses the US English affix file to check for valid variants of dictionary words. Non-English characters or prefix/suffix rules are not supported.)

Changing Default Config

The quality-docs CLI ships with an opinionated configuration to improve your writing. If you want to override the defaults of the retext plugins used by this tool, we recommend one of these three options;

  1. Exclude documentation files from the glob argument.
  2. Use the --config flag to pass in a JSON file with default configuration overrides.
  3. Use remark-message-control marks to turn on/off specific rules for individual documents or text nodes.

Troubleshooting

Here is a list of common confusing issues quality-docs flags, and how to resolve them;

Names are flagged as misspelled

If it's a common name, add it to a custom dictionary. If it isn't common or you don't want to add it to the dictionary, add it to the ignore array in a config override file.

Other non-dictionary terms are flagged as misspelled

Any non-dictionary terms in quotes are ignored. If the word is a literal value such as a variable name or package name, put it in backticks; `quality-docs`. If it's a made-up word or other literal representation of a non-dictionary term, use "buttonator" or 'buttonator'.

Table cells are flagged as being incorrectly padded

First, check the rules for formatting table cells in markdown. If everything is correct, check for empty table cells, which throw off the linter. Try adding content to blank cells; n/a or (none).

Another issue is being incorrectly flagged

Try using the methods provided to change the default config to suit your preferences. If custom config doesn't resolve the problem, file an issue including the text of the markdown file you're checking and the error you're seeing in the output.

Contribute

Open an issue to report bugs or ask questions. Open a PR to contribute. Run npm run test to make sure contributions pass the included tests.

License

MIT © 2016 Sparkart Group Inc.