From f41f358ca5334a70de7823a61dc246a8bd44005b Mon Sep 17 00:00:00 2001 From: Seth Falco Date: Mon, 2 Oct 2023 21:03:57 +0100 Subject: [PATCH] docs: add documentation for all commands --- docs/01-index.mdx | 38 +++ docs/02-preset-default.mdx | 86 ++++++ .../add-attributes-to-svg-elements.mdx | 34 +++ .../03-plugins/add-classes-to-svg-element.mdx | 39 +++ docs/03-plugins/cleanup-attrs.mdx | 39 +++ docs/03-plugins/cleanup-enable-background.mdx | 26 ++ docs/03-plugins/cleanup-ids.mdx | 58 ++++ docs/03-plugins/cleanup-list-of-values.mdx | 38 +++ docs/03-plugins/cleanup-numeric-values.mdx | 37 +++ docs/03-plugins/collapse-groups.mdx | 28 ++ docs/03-plugins/convert-colors.mdx | 53 ++++ docs/03-plugins/convert-ellipse-to-circle.mdx | 20 ++ .../03-plugins/convert-one-stop-gradients.mdx | 23 ++ docs/03-plugins/convert-path-data.mdx | 77 ++++++ docs/03-plugins/convert-shape-to-path.mdx | 31 +++ docs/03-plugins/convert-style-to-attrs.mdx | 44 ++++ docs/03-plugins/convert-transform.mdx | 54 ++++ docs/03-plugins/index.mdx | 17 ++ docs/03-plugins/inline-styles.mdx | 35 +++ docs/03-plugins/merge-paths.mdx | 33 +++ docs/03-plugins/merge-styles.mdx | 20 ++ docs/03-plugins/minify-styles.mdx | 28 ++ docs/03-plugins/move-elems-attrs-to-group.mdx | 20 ++ docs/03-plugins/move-group-attrs-to-elem.mdx | 20 ++ docs/03-plugins/prefix-ids.mdx | 35 +++ .../remove-attributes-by-selector.mdx | 27 ++ docs/03-plugins/remove-attrs.mdx | 41 +++ docs/03-plugins/remove-comments.mdx | 51 ++++ docs/03-plugins/remove-desc.mdx | 34 +++ docs/03-plugins/remove-dimensions.mdx | 25 ++ docs/03-plugins/remove-doctype.mdx | 20 ++ docs/03-plugins/remove-editors-ns-data.mdx | 34 +++ docs/03-plugins/remove-elements-by-attr.mdx | 30 +++ docs/03-plugins/remove-empty-attrs.mdx | 26 ++ docs/03-plugins/remove-empty-containers.mdx | 36 +++ docs/03-plugins/remove-empty-text.mdx | 40 +++ docs/03-plugins/remove-hidden-elems.mdx | 74 ++++++ docs/03-plugins/remove-metadata.mdx | 30 +++ .../remove-non-inheritable-group-attrs.mdx | 20 ++ docs/03-plugins/remove-off-canvas-paths.mdx | 22 ++ docs/03-plugins/remove-raster-images.mdx | 19 ++ docs/03-plugins/remove-script-elements.mdx | 27 ++ docs/03-plugins/remove-style-element.mdx | 19 ++ docs/03-plugins/remove-title.mdx | 29 ++ .../remove-unknowns-and-defaults.mdx | 46 ++++ docs/03-plugins/remove-unused-namespaces.mdx | 26 ++ docs/03-plugins/remove-useless-defs.mdx | 20 ++ .../remove-useless-stroke-and-fill.mdx | 36 +++ docs/03-plugins/remove-viewbox.mdx | 30 +++ docs/03-plugins/remove-xml-proc-inst.mdx | 32 +++ docs/03-plugins/remove-xmlns.mdx | 27 ++ docs/03-plugins/reuse-paths.mdx | 23 ++ docs/03-plugins/sort-attrs.mdx | 61 +++++ docs/03-plugins/sort-defs-children.mdx | 39 +++ docs/04-plugins-api.mdx | 122 +++++++++ plugins-api.md | 248 ------------------ 56 files changed, 1999 insertions(+), 248 deletions(-) create mode 100644 docs/01-index.mdx create mode 100644 docs/02-preset-default.mdx create mode 100644 docs/03-plugins/add-attributes-to-svg-elements.mdx create mode 100644 docs/03-plugins/add-classes-to-svg-element.mdx create mode 100644 docs/03-plugins/cleanup-attrs.mdx create mode 100644 docs/03-plugins/cleanup-enable-background.mdx create mode 100644 docs/03-plugins/cleanup-ids.mdx create mode 100644 docs/03-plugins/cleanup-list-of-values.mdx create mode 100644 docs/03-plugins/cleanup-numeric-values.mdx create mode 100644 docs/03-plugins/collapse-groups.mdx create mode 100644 docs/03-plugins/convert-colors.mdx create mode 100644 docs/03-plugins/convert-ellipse-to-circle.mdx create mode 100644 docs/03-plugins/convert-one-stop-gradients.mdx create mode 100644 docs/03-plugins/convert-path-data.mdx create mode 100644 docs/03-plugins/convert-shape-to-path.mdx create mode 100644 docs/03-plugins/convert-style-to-attrs.mdx create mode 100644 docs/03-plugins/convert-transform.mdx create mode 100644 docs/03-plugins/index.mdx create mode 100644 docs/03-plugins/inline-styles.mdx create mode 100644 docs/03-plugins/merge-paths.mdx create mode 100644 docs/03-plugins/merge-styles.mdx create mode 100644 docs/03-plugins/minify-styles.mdx create mode 100644 docs/03-plugins/move-elems-attrs-to-group.mdx create mode 100644 docs/03-plugins/move-group-attrs-to-elem.mdx create mode 100644 docs/03-plugins/prefix-ids.mdx create mode 100644 docs/03-plugins/remove-attributes-by-selector.mdx create mode 100644 docs/03-plugins/remove-attrs.mdx create mode 100644 docs/03-plugins/remove-comments.mdx create mode 100644 docs/03-plugins/remove-desc.mdx create mode 100644 docs/03-plugins/remove-dimensions.mdx create mode 100644 docs/03-plugins/remove-doctype.mdx create mode 100644 docs/03-plugins/remove-editors-ns-data.mdx create mode 100644 docs/03-plugins/remove-elements-by-attr.mdx create mode 100644 docs/03-plugins/remove-empty-attrs.mdx create mode 100644 docs/03-plugins/remove-empty-containers.mdx create mode 100644 docs/03-plugins/remove-empty-text.mdx create mode 100644 docs/03-plugins/remove-hidden-elems.mdx create mode 100644 docs/03-plugins/remove-metadata.mdx create mode 100644 docs/03-plugins/remove-non-inheritable-group-attrs.mdx create mode 100644 docs/03-plugins/remove-off-canvas-paths.mdx create mode 100644 docs/03-plugins/remove-raster-images.mdx create mode 100644 docs/03-plugins/remove-script-elements.mdx create mode 100644 docs/03-plugins/remove-style-element.mdx create mode 100644 docs/03-plugins/remove-title.mdx create mode 100644 docs/03-plugins/remove-unknowns-and-defaults.mdx create mode 100644 docs/03-plugins/remove-unused-namespaces.mdx create mode 100644 docs/03-plugins/remove-useless-defs.mdx create mode 100644 docs/03-plugins/remove-useless-stroke-and-fill.mdx create mode 100644 docs/03-plugins/remove-viewbox.mdx create mode 100644 docs/03-plugins/remove-xml-proc-inst.mdx create mode 100644 docs/03-plugins/remove-xmlns.mdx create mode 100644 docs/03-plugins/reuse-paths.mdx create mode 100644 docs/03-plugins/sort-attrs.mdx create mode 100644 docs/03-plugins/sort-defs-children.mdx create mode 100644 docs/04-plugins-api.mdx delete mode 100644 plugins-api.md diff --git a/docs/01-index.mdx b/docs/01-index.mdx new file mode 100644 index 000000000..29151ed01 --- /dev/null +++ b/docs/01-index.mdx @@ -0,0 +1,38 @@ +--- +title: Introduction +slug: "introduction" +--- + +SVGO (short for SVG Optimizer) is a Node.js library and command-line application for optimizing SVG files. + +SVG files, especially those exported from vector editors, usually contain a lot of redundant information. This includes editor metadata, comments, hidden elements, default or suboptimal values, and other stuff that can be safely removed or converted without affecting the rendering result. + +## Installation + +### System Requirements + +* [Node.js 14](https://nodejs.org/) or later + + + + +```sh +npm install -g svgo +``` + + + + +```sh +yarn global add svgo +``` + + + + +```sh +pnpm add -g svgo +``` + + + diff --git a/docs/02-preset-default.mdx b/docs/02-preset-default.mdx new file mode 100644 index 000000000..03583194f --- /dev/null +++ b/docs/02-preset-default.mdx @@ -0,0 +1,86 @@ +--- +title: Preset Default +--- + +SVGO 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. + +:::info + +If you aren't using SVGO directly, like through [SVGR](https://github.com/gregberge/svgr), the default plugins may be different from the default preset. + +::: + +## Plugins List + +The following plugins are included in `preset-default`, in the order that they're executed: + +* [Remove Doctype](/docs/plugins/remove-doctype/) +* [Remove XML Declaration](/docs/plugins/remove-xml-proc-inst/) +* [Remove Comments](/docs/plugins/remove-comments/) +* [Remove Metadata](/docs/plugins/remove-metadata/) +* [Remove Editor Namespace Data](/docs/plugins/remove-editors-ns-data/) +* [Cleanup Attributes](/docs/plugins/cleanup-attrs/) +* [Merge Styles](/docs/plugins/merge-styles/) +* [Inline Styles](/docs/plugins/inline-styles/) +* [Minify Styles](/docs/plugins/minify-styles/) +* [Cleanup IDs](/docs/plugins/cleanup-ids/) +* [Remove Useless Defs](/docs/plugins/remove-useless-defs/) +* [Cleanup Numeric Values](/docs/plugins/cleanup-numeric-values/) +* [Convert Colors](/docs/plugins/convert-colors/) +* [Remove Unknowns and Defaults](/docs/plugins/remove-unknowns-and-defaults/) +* [Remove Non-inheritable Group Attributes](/docs/plugins/remove-non-inheritable-group-attrs/) +* [Remove Useless Stroke and Fill](/docs/plugins/remove-useless-stroke-and-fill/) +* [Remove ViewBox](/docs/plugins/remove-viewbox/) +* [Cleanup Enable Background](/docs/plugins/cleanup-enable-background/) +* [Remove Hidden Elements](/docs/plugins/remove-hidden-elems/) +* [Remove Empty Text](/docs/plugins/remove-empty-text/) +* [Convert Shape to Path](/docs/plugins/convert-shape-to-path/) +* [Convert Ellipse to Circle](/docs/plugins/convert-ellipse-to-circle/) +* [Move Element Attributes to Group](/docs/plugins/move-elems-attrs-to-group/) +* [Move Group Attributes to Element](/docs/plugins/move-group-attrs-to-elem/) +* [Collapse Groups](/docs/plugins/collapse-groups/) +* [Convert Path Data](/docs/plugins/convert-path-data/) +* [Convert Transform](/docs/plugins/convert-transform/) +* [Remove Empty Attributes](/docs/plugins/remove-empty-attrs/) +* [Remove Empty Containers](/docs/plugins/remove-empty-containers/) +* [Remove Unused Namespaces](/docs/plugins/remove-unused-namespaces/) +* [Merge Paths](/docs/plugins/merge-paths/) +* [Sort Attributes](/docs/plugins/sort-attrs/) +* [Sort Defs Children](/docs/plugins/sort-defs-children/) +* [Remove Title](/docs/plugins/remove-title/) +* [Remove Description](/docs/plugins/remove-desc/) + +## 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: { + removeViewBox: false + }, + }, + }, + ], +}; +``` + +Alternatively, you can also drop `default-preset` entirely, and configure your own plugin pipeline from scratch, with only the desireable plugins: + +```js +module.exports = { + plugins: [ + 'removeDoctype', + 'removeXMLProcInst', + 'minifyStyles', + 'sortAttrs', + 'sortDefsChildren' + ], +}; +``` diff --git a/docs/03-plugins/add-attributes-to-svg-elements.mdx b/docs/03-plugins/add-attributes-to-svg-elements.mdx new file mode 100644 index 000000000..6fdf0fa05 --- /dev/null +++ b/docs/03-plugins/add-attributes-to-svg-elements.mdx @@ -0,0 +1,34 @@ +--- +title: Add Attributes to Elements +svgo: + pluginId: addAttributesToSVGElement + parameters: + attributes: + description: Attributes to add to the <svg> element. If key/value pairs are passed, the attributes and added with the paired value. If an array is passed, attributes are added with no key associated with them. + default: null + attribute: +--- + +Adds attributes to the outer most [``](https://developer.mozilla.org/docs/Web/SVG/Element/svg) element in the document. This is not an optimization and will increase the size of SVG documents. + +:::danger + +This plugin is only safe to use when a map of key/value pairs is passed. If you pass an array of keys to declare empty attributes, this will produce an malformed SVG that's only usable inline an HTML5 document. + +::: + +## Usage + + + +### Parameters + + + +## Demo + + + +## Implementation + +* https://github.com/svg/svgo/blob/main/plugins/addAttributesToSVGElement.js diff --git a/docs/03-plugins/add-classes-to-svg-element.mdx b/docs/03-plugins/add-classes-to-svg-element.mdx new file mode 100644 index 000000000..121c58ea6 --- /dev/null +++ b/docs/03-plugins/add-classes-to-svg-element.mdx @@ -0,0 +1,39 @@ +--- +title: Add Classes to SVG +svgo: + pluginId: addClassesToSVGElement + parameters: + classNames: + description: Adds the specified class names to the outer most <svg> element. + default: null + className: + description: Adds the specified class name to the outer most <svg> element. If classNames is specified, this is ignored. +--- + +Overrides the `class` attribute in the outer most `` element, omitting duplicates or null classes if found in your configuration. + +:::caution + +If there is no `class` attribute to begin with, it will be added. However, if the there were already classes assigned, these are removed and replaced with the classes configured in this plugin. + +::: + +If you have a standalone SVG, this is not an optimization and will increase the size of the SVG document. This plugin is only relavent when considering multiple SVGs that may be inlined a parent document. + +By adding classes, if the parent document is aware, you can share styles across all inlined SVG elements. + +## Usage + + + +### Parameters + + + +## Demo + + + +## Implementation + +* https://github.com/svg/svgo/blob/main/plugins/addClassesToSVGElement.js diff --git a/docs/03-plugins/cleanup-attrs.mdx b/docs/03-plugins/cleanup-attrs.mdx new file mode 100644 index 000000000..722f6b974 --- /dev/null +++ b/docs/03-plugins/cleanup-attrs.mdx @@ -0,0 +1,39 @@ +--- +title: Cleanup Attributes +svgo: + pluginId: cleanupAttrs + defaultPlugin: true + parameters: + newlines: + description: Replace instances of a newline with a single whitespace. + type: boolean + default: true + trim: + description: Trim whitespace characters from the start and end of attribute values. + type: boolean + default: true + spaces: + description: Replace all instances of 2 or more whitespace characters with a single whitespace. + type: boolean + default: true +--- + +Removes redundant whitespaces from attribute values. + +This will not modify the attribute keys, nor remove them if the value becomes empty after optimization. + +## Usage + + + +### Parameters + + + +## Demo + + + +## Implementation + +* https://github.com/svg/svgo/blob/main/plugins/cleanupAttrs.js diff --git a/docs/03-plugins/cleanup-enable-background.mdx b/docs/03-plugins/cleanup-enable-background.mdx new file mode 100644 index 000000000..3ec405433 --- /dev/null +++ b/docs/03-plugins/cleanup-enable-background.mdx @@ -0,0 +1,26 @@ +--- +title: Cleanup Enable Background +svgo: + pluginId: cleanupEnableBackground + defaultPlugin: true +--- + +Removes the [`enable-background`](https://developer.mozilla.org/docs/Web/SVG/Attribute/enable-background) attribute, unless it's used in a [``](https://developer.mozilla.org/docs/Web/SVG/Element/filter). + +:::info + +Some browsers don't support `enable-background`, so it's best to avoid that attribute regardless. + +::: + +## Usage + + + +## Demo + + + +## Implementation + +* https://github.com/svg/svgo/blob/main/plugins/cleanupEnableBackground.js diff --git a/docs/03-plugins/cleanup-ids.mdx b/docs/03-plugins/cleanup-ids.mdx new file mode 100644 index 000000000..a135be76d --- /dev/null +++ b/docs/03-plugins/cleanup-ids.mdx @@ -0,0 +1,58 @@ +--- +title: Cleanup IDs +svgo: + pluginId: cleanupIds + parameters: + remove: + description: If to remove all unreferenced IDs. + default: true + minify: + description: If to minify referenced IDs. + default: true + preserve: + description: Elements with one of these IDs will be ignored. + default: [] + preservePrefixes: + description: Elements with an ID that starts with one of these prefixes will be ignored. + default: [] + force: + description: This plugin normally does nothing if a <script> or <style> element is found. Setting this to true will bypass that behaviour, which may result in destructive changes. + default: false + defaultPlugin: true +--- + +Removes unused IDs, and minifys IDs that are referenced by other elements. + +By default, we back off from removing and minifying IDs if a `