Update FAQ, etc.

svg-utils · Oct 16, 2024 · 4734fd1 · 4734fd1
1 parent ba9a745
commit 4734fd1
Show file tree

Hide file tree

Showing 6 changed files with 77 additions and 179 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,33 +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.
+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.
 
@@ -53,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,11 +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
+- [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
@@ -19,14 +30,14 @@ 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>

diff --git a/docs/preset-default.md b/docs/preset-default.md
@@ -1,4 +1,4 @@
-**svgo-ll** runs with a default preset that has the plugin ID `preset-default`. This is the default set of plugins that are used when not explicitly specified or overridden elsewhere.
+**svgo-ll** runs with a default preset that has the plugin ID `preset-default`. This is the default set of plugins that are used when not explicitly specified or overridden elsewhere. In addition to the default plugins, there are some [builtin plugins](./builtin-plugins.md) that must be enabled explicitly.
 
 ## Plugins List
 
@@ -16,7 +16,7 @@ The following plugins are included in `preset-default`, in the order that they a
 - [inlineStyles](./plugins/inlineStyles.md)
 - minifyStyles
 - [cleanupIds](./plugins/cleanupIds.md)
-- convertColors
+- [minifyColors](./plugins/minifyColors.md)
 - [removeUnknownsAndDefaults](./plugins/removeUnknownsAndDefaults.md)
 - removeNonInheritableGroupAttrs
 - removeUselessStrokeAndFill
@@ -31,38 +31,3 @@ The following plugins are included in `preset-default`, in the order that they a
 - removeEmptyContainers
 - removeUnusedNS
 - [createGroups](./plugins/createGroups.md)
-
-## Disable a Plugin
-
-Sometimes a specific plugin might not be appropriate for your workflow. You can continue using `preset-default` while disabling any plugin by using the `overrides` parameter.
-
-In `overrides`, reference the plugin ID and set it to `false` to disable it:
-
-```js
-module.exports = {
-  plugins: [
-    {
-      name: 'preset-default',
-      params: {
-        overrides: {
-          cleanupIds: false,
-        },
-      },
-    },
-  ],
-};
-```
-
-Alternatively, you can drop `preset-default` entirely, and configure your own plugin pipeline from scratch, with only the desirable plugins:
-
-```js
-module.exports = {
-  plugins: [
-    'removeDoctype',
-    'removeXMLProcInst',
-    'minifyStyles',
-    'sortAttrs',
-    'sortDefsChildren',
-  ],
-};
-```