Update docs. (#62)

svg-utils · Oct 16, 2024 · 128ea35 · 128ea35
1 parent af547e5
commit 128ea35
Show file tree

Hide file tree

Showing 9 changed files with 168 additions and 178 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
-# svgo-ll
+# svgo-ll [![npm](https://img.shields.io/npm/v/svgo-ll)](https://npmjs.org/package/svgo-ll)
 
-**svgo-ll** is a Node.js library and command-line application for optimizing SVG files, based on the [SVGO](https://www.npmjs.com/package/svgo) package. **svgo-ll** is focused on lossless optimization and compression.
+**svgo-ll** is a Node.js library and command-line application for optimizing SVG files, evolved from the [SVGO](https://www.npmjs.com/package/svgo) package. **svgo-ll** is focused on lossless optimization and compression.
 
 ## Why?
 
@@ -31,124 +31,6 @@ svgo-ll --preset next -i one.svg -o one.min.svg
 
 For more detailed options, see the [command line option documentation](https://github.com/svg-utils/svgo-ll/blob/main/docs/command-line-options.md) or [FAQ](https://github.com/svg-utils/svgo-ll/blob/main/docs/faq.md).
 
-## Configuration
-
-**svgo-ll** has a plugin architecture. You can find a list of the default plugins in the order they run in the [default preset](https://github.com/svg-utils/svgo-ll/blob/main/docs/preset-default.md) documentation.
-
-**svgo-ll** reads the configuration from `svgo.config.mjs` or the `--config path/to/config.mjs` command-line option. Some other parameters can be configured though command-line options too.
-
-**`svgo.config.mjs`**
-
-```js
-export default {
-  datauri: 'base64', // 'base64'|'enc'|'unenc'
-  js2svg: {
-    indent: 4, // number
-    pretty: false, // boolean
-  },
-  plugins: [
-    'preset-default', // built-in plugins enabled by default
-    'prefixIds', // enable built-in plugins by name
-
-    // enable built-in plugins with an object to configure plugins
-    {
-      name: 'prefixIds',
-      params: {
-        prefix: 'uwu',
-      },
-    },
-  ],
-};
-```
-
-### Default preset
-
-Instead of configuring **svgo-ll** from scratch, you can modify the default preset to suit your needs by configuring or disabling individual plugins.
-
-**`svgo.config.mjs`**
-
-```js
-export default {
-  plugins: [
-    {
-      name: 'preset-default',
-      params: {
-        overrides: {
-          // disable a default plugin
-          cleanupIds: false,
-
-          // customize the params of a default plugin
-          inlineStyles: {
-            onlyMatchedOnce: false,
-          },
-        },
-      },
-    },
-  ],
-};
-```
-
-### Custom plugins
-
-You can also specify custom plugins:
-
-**`svgo.config.mjs`**
-
-```js
-import importedPlugin from './imported-plugin';
-
-export default {
-  plugins: [
-    // plugin imported from another JavaScript file
-    importedPlugin,
-
-    // plugin defined inline
-    {
-      name: 'customPlugin',
-      params: {
-        paramName: 'paramValue',
-      },
-      fn: (ast, params, info) => {},
-    },
-  ],
-};
-```
-
-## API usage
-
-**svgo-ll** provides a few low level utilities.
-
-### optimize
-
-The core of **svgo-ll** is the `optimize` function.
-
-```js
-import { optimize } from 'svgo-ll';
-
-const result = optimize(svgString, {
-  path: 'path-to.svg', // recommended
-  maxPasses: 3, // all other config fields are available here
-});
-
-const optimizedSvgString = result.data;
-```
-
-### loadConfig
-
-If you write a tool on top of **svgo-ll** you may want to resolve the `svgo.config.mjs` file.
-
-```js
-import { loadConfig } from 'svgo-ll';
-
-const config = await loadConfig();
-```
-
-You can also specify a path and customize the current working directory.
-
-```js
-const config = await loadConfig(configFile, cwd);
-```
-
 ## License and Copyright
 
 This software is released under the terms of the [MIT license](https://github.com/svg-utils/svgo-ll/blob/main/LICENSE).
diff --git a/docs/builtin-plugins.md b/docs/builtin-plugins.md
@@ -0,0 +1,6 @@
+# Builtin Plugins
+
+In addition to the [default plugins](./preset-default.md), the following plugins are available, but must be enabled with the [`--enable` command line option in order to be used:
+](./command-line-options.md#enable)
+
+- [round](./plugins/round.md)
diff --git a/docs/command-line-options.md b/docs/command-line-options.md
@@ -2,8 +2,7 @@
 
 For examples of how these options can be used, see the [FAQ](./faq.md).
 
-`-v, --version`  
-Output the version number.
+## Input Options
 
 `-i, --input <INPUT...>`  
 One or more input files to process. Use "-" to take input from STDIN.
@@ -14,28 +13,44 @@ Process an input file specified as a string.
 `-f, --folder <FOLDER>`  
 Process all \*.svg files in the specified folder.
 
-`-o, --output <OUTPUT...>`  
-File or folder to which output should be written. If no output option is specified, the input file will be overwritten by the processed result. Use "-" to write output to STDOUT.
+`-r, --recursive`  
+If `--folder` is specified, process files in all sub-folders recursively.
+
+`--exclude <PATTERN...>`  
+If `--folder` is specified, exclude files matching any of the specified regular expression patterns.
+
+## Plugin and Compression Options
 
 `--preset <default | next | none>`  
 Specify which set of predefined plugins to use. If this option is not used, and no plugins are define by the `--config` option,
 [preset-default](./preset-default.md) is used.
 
-`--config <CONFIG>`  
-Custom configuration file.
-
+<a id="enable"></a>
 `--enable <plugin...>`  
 Specify one or more builtin plugins to run in addition to those specified by `--preset` or `--config`.
 
+<a id="options"></a>
+` --options <FILENAME>`  
+Path to a [JSON file](https://www.json.org) containing configuration parameters for enabled plugins. The JSON file should contain an object whose keys are the names of plugins, and whose values are the parameters to pass to that plugin. This option cannot be used if the [`--config` option](#config) is specified.
+
 `--disable <plugin...>`  
 Specify one or more plugins specified by `--preset` or `--config` which should not be run.
 
-`--datauri <base64 | enc | unenc>`  
-Output as Data URI string (base64), URI encoded (enc) or unencoded (unenc) rather than .svg.
+<a id="config"></a>
+`--config <FILENAME>`  
+Specifies a [custom configuration file](./custom-config-file.md).
 
 `--max-passes <INTEGER>`  
 Maximum number of iterations over the plugins. Must be an integer between 1 and 10. Default is 10.
 
+## Output Options
+
+`-o, --output <OUTPUT...>`  
+File or folder to which output should be written. If no output option is specified, the input file will be overwritten by the processed result. Use "-" to write output to STDOUT.
+
+`--datauri <base64 | enc | unenc>`  
+Output as Data URI string (base64), URI encoded (enc) or unencoded (unenc) rather than .svg.
+
 `--pretty`  
 Add line breaks and indentation to output.
 
@@ -48,20 +63,19 @@ Line break to use when outputting SVG. If unspecified, the platform default is u
 `--final-newline`  
 Ensure output ends with a line break.
 
-`-r, --recursive`  
-If `--folder` is specified, process files in all sub-folders recursively.
-
-`--exclude <PATTERN...>`  
-If `--folder` is specified, exclude files matching any of the specified regular expression patterns.
+`--no-color`  
+Output messages in plain text without color.
 
 `-q, --quiet`  
 Only output error messages, not regular status messages.
 
+## Help Options
+
 `--show-plugins`
 Show available plugins and exit.
 
-`--no-color`  
-Output messages in plain text without color.
+`-v, --version`  
+Output the version number.
 
 `-h, --help`  
 Display help for command line options.

diff --git a/docs/custom-config-file.md b/docs/custom-config-file.md
@@ -0,0 +1,25 @@
+# Custom Configuration Files
+
+If you are using only the builtin plugins distributed with **svgo-ll**, you should be able to do all configuration from the [command line](./command-line-options.md), but if you are using custom plugins or have a complex configuration, you may want to use a custom configuration file.
+
+A custom configuration file is a JavaScript file that exports a [`Config` object](https://github.com/svg-utils/svgo-ll/blob/main/lib/svgo.d.ts), for example:
+
+```js
+import importedPlugin from './imported-plugin';
+
+export default {
+  plugins: [
+    // plugin imported from another JavaScript file
+    importedPlugin,
+
+    // plugin defined inline
+    {
+      name: 'customPlugin',
+      params: {
+        paramName: 'paramValue',
+      },
+      fn: (ast, params, info) => {},
+    },
+  ],
+};
+```
diff --git a/docs/faq.md b/docs/faq.md
@@ -4,9 +4,22 @@ Compression
 
 - [Just remove whitespace from a file](#comp-ws)
 - [Run a single plugin](#comp-1plugin)
+- [Disable one or more default plugins](#comp-disable)
+- [Round decimal values](#comp-round)
+- [Change the default options for a plugin](#comp-defaults)
 
 ## Compression
 
+<a id="comp-ws"></a>
+
+### Just remove whitespace from a file
+
+Use `preset-none`. For example:
+
+```
+npx svgo-ll --preset none -i test.svg
+```
+
 <a id="comp-1plugin"></a>
 
 ### Run a single plugin
@@ -17,12 +30,42 @@ Use `preset-none` and `--enable`. For example:
 npx svgo-ll --preset none --enable minifyPathData -i test.svg
 ```
 
-<a id="comp-ws"></a>
+<a id="comp-disable"></a>
 
-### Just remove whitespace from a file
+### Disable one or more default plugins
 
-Use `preset-none`. For example:
+Use the `--disable` command line option. For example:
 
 ```
-npx svgo-ll --preset none -i test.svg
+npx svgo-ll --disable minifyPathData cleanupIds -i test.svg
+```
+
+<a id="comp-round"></a>
+
+### Round decimal values
+
+Rounding is not enabled by default. To enable the rounding plugin, use the [`--enable` command line option](./command-line-options.md#enable). For example, to add rounding to the default plugins:
+
+```
+npx svgo-ll -i test.svg --enable round
+```
+
+<a id="comp-defaults"></a>
+
+### Change the default options for a plugin
+
+You can change the default options for a plugin by creating a JSON file and using the [`--options` command line option](./command-line-options.md#options). For example, to use the default plugins and specify an id that should not be changed by the `cleanupIds` plugin, create file named `options.json` with the content:
+
+```
+{
+  "cleanupIds": {
+    "preserve": "abc"
+  }
+}
+```
+
+and use the command:
+
+```
+npx svgo-ll -i test.svg --options options.json
 ```
diff --git a/docs/plugins/minifyColors.md b/docs/plugins/minifyColors.md
@@ -0,0 +1,18 @@
+# minifyColors
+
+Rewrites color attributes and properties to use shorter formats.
+
+## Details
+
+The plugin has no effect if:
+
+- The document has scripts.
+- The document has `<style>` elements with CSS which **svgo-ll** is not able to process.
+- The `<style>` has attribute selectors.
+
+Depending on the format of the color specification, the color may be shortened as follows:
+
+- RGB colors in hexadecimal notation and [extended color keywords](https://www.w3.org/TR/css-color-3/#svg-color) are shortened to the shortest possible string (which may be a 6 character or 3 character hex string, or an extended color keyword).
+- RGB colors in `rgb()` functional notation using integer values are converted to 6 digit hexadecimal format, then shortened as above.
+- RGB colors in `rgb()` functional notation with percentage values, all of which are either `0%` or `100%`, are changed to integer values of 0 or 255, then shortened as above.
+- Color values in formats other than those described above are not changed.
diff --git a/docs/plugins/round.md b/docs/plugins/round.md
@@ -0,0 +1,37 @@
+# round
+
+Rounds numbers to a shorter form.
+
+## Options
+
+- `coordDigits`: **number** - the number of digits after the decimal place to round x/y coordinates and width/height values (default: **4**)
+- `opacityDigits`: **number** - the number of digits after the decimal place to round opacity values (default: **3**)
+
+## Details
+
+The plugin has no effect if:
+
+- The document has scripts.
+- The document has `<style>` elements with CSS which **svgo-ll** is not able to process.
+- The document has `<style>` elements with attribute selectors.
+
+### x and y coordinates and width/height
+
+Coordinate values and lengths are rounded according to the context in which they are used. The number of digits to which a value is rounded is based on the `viewBox` context in which it is used (or if there is no `viewBox`, the `width` and `height`). The number of digits specified by the `coordDigits` parameter specifies the number of digits for a dimension >= 100 pixels and < 1000 pixels. Smaller dimensions will add one digit for each factor of 10, and larger dimensions will subtract one digit for each factor of 10.
+
+The following values are rounded using this value:
+
+- `M`, `m`, `L`, `l`, `H`, `h`, `V`, or `v` command values in the `d` attribute of a path element.
+- The coordinates in a `translate()` function in a `transform` attribute.
+- The `x`, `y`, `width` and `height` attributes of a `<rect>` element.
+- The `x1`, `y1`, `x2` and `y2` attributes of a `<line>` element.
+
+If the dimension of the element or its ancestors cannot be determined, or if the element or one of its ancestors is subject to a `transform` other than `translate()`, no rounding is done.
+
+### Opacities
+
+`opacity` and `fill-opacity` values are rounded to the number of digits specified by the `opacityDigits` parameter.
+
+### Colors
+
+Any colors specified using RGB percentages are converted to integer RGB values, and minified as they are in the [minifyColors](./minifyColors.md) plugin.