diff --git a/README.md b/README.md
index 6d91d23..3c556e6 100644
--- a/README.md
+++ b/README.md
@@ -2,17 +2,21 @@
Lints SVG files. Can be run as a commandline utility, or as a NodeJS library.
+
+
+
+
## Usage
The tool can be used as a commandline tool by executing the CLI.
If installed as a dependency by NPM this will be found at `./node_modules/.bin/svglint`.
If installed globally by NPM it can be executed directly as `svglint`.
-```
+```shell
$ svglint --help
Linter for SVGs
@@ -36,8 +40,9 @@ The tool can also be used through the JS API.
import SVGLint from "svglint";
const linting = await SVGLint.lintSource("", {
- // ... config goes here
+ // ... config object goes here
});
+
linting.on("done", () => {
if (!linting.valid) {
console.log("You've been a naughty boy!");
@@ -47,34 +52,201 @@ linting.on("done", () => {
## Config
+SVGLint can run without a configuration file. In that case, it uses an empty object as the default configuration, which means that no rules are enabled. This default configuration may be changed such that previously valid SVGs become invalid in minor releases and patches.
+
In order to specify what should be linted SVGLint must be given a configuration object.
-If you are using the CLI, this configuration object is read from the file specified by `--config`. This defaults to `.svglintrc.js`, which will be searched for up through the directory tree, or in the user's home directory (e.g. `~/.svglintrc.js` on Unix-like systems) - this is similar to tools such as ESLint.
+
+If you are using the CLI, this configuration object is read from the file specified by `--config`. This defaults to:
+
+- *.svglintrc.js*
+- If the *package.json* `type` field is set to `"module"`, then *.svglintrc.cjs* is also checked, else *.svglintrc.mjs* is checked.
+
+These files will be searched for up through the directory tree, or in the user's home directory (e.g. `~/` on Unix-like systems).
This configuration file should export a single object, of the format:
```javascript
export default {
- // additional configuration may go here in the future
- // for now, "rules" is the only useful key
rules: {
- elm: [{
- // config 1 for the "elm" rule
+ // Built-in rules
+ elm: {
+ // config for the `elm` rule
+ },
+ attr: [{
+ // config 1 for the `attr` rule
}, {
- // config 2 for the "elm" rule
+ // config 2 for the `attr` rule
}],
- attr: {
- // config 1 for the "attr" rule
- },
+ valid: true,
+
+ // Custom rules
+ custom: [
+ (reporter, $, ast) => {
+ // config for a custom rule named `my-first-rule`
+ reporter.name = 'my-first-rule';
+
+ // ... additional code for the rule
+ },
+ (reporter, $, ast) => {
+ // config for a custom rule named `my-second-rule`
+ reporter.name = 'my-second-rule';
+
+ // ... additional code for the rule
+ }
+ ],
+
+ // External rules
+ 'simple-icons-svglint-rules/icon-precision': {
+ // config for the rule `icon-precision` of the external
+ // hypotetical npm package `simple-icons-svglint-rules`
+ }
+ }
+}
+```
+
+Additional configuration may be added in the future. For now, `rules` is the only useful key.
+
+### Rules (`rules`)
+
+All rules are optional.
+
+#### `elm`
+
+Rules at `elm` specify what elements are allowed in the SVG. It should be an object or an array of objects where:
+
+- The keys are the element CSS selectors. See [_Selecting elements_ on cheerio's documentation][selecting-elements-cheerio].
+- The values are either:
+ - `true` if at least one of the element is present.
+ - `false` if the element must not be present.
+ - A number to specify the number of times the element must be present.
+ - An array of two numbers to specify the minimum and maximum number of times the element must be present.
+
+##### Example
+
+Only one `