Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add usage section #2038

Merged
merged 1 commit into from
Jun 15, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 0 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,26 +166,6 @@ You can also specify a path and customize the current working directory.
const config = await loadConfig(configFile, cwd);
```

## Other ways to use SVGO

| Method | Reference |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Web app | [SVGOMG](https://jakearchibald.github.io/svgomg/) |
| Grunt task | [grunt-svgmin](https://github.com/sindresorhus/grunt-svgmin) |
| Gulp task | [gulp-svgmin](https://github.com/ben-eb/gulp-svgmin) |
| Webpack loader | [image-minimizer-webpack-plugin](https://github.com/webpack-contrib/image-minimizer-webpack-plugin/#optimize-with-svgo) |
| PostCSS plugin | [postcss-svgo](https://github.com/cssnano/cssnano/tree/master/packages/postcss-svgo) |
| Inkscape plugin | [inkscape-svgo](https://github.com/konsumer/inkscape-svgo) |
| Sketch plugin | [svgo-compressor](https://github.com/BohemianCoding/svgo-compressor) |
| Rollup plugin | [rollup-plugin-svgo](https://github.com/porsager/rollup-plugin-svgo) |
| Visual Studio Code plugin | [vscode-svgo](https://github.com/1000ch/vscode-svgo) |
| Atom plugin | [atom-svgo](https://github.com/1000ch/atom-svgo) |
| Sublime plugin | [Sublime-svgo](https://github.com/1000ch/Sublime-svgo) |
| Figma plugin | [Advanced SVG Export](https://www.figma.com/c/plugin/782713260363070260/Advanced-SVG-Export) |
| Linux app | [Oh My SVG](https://github.com/sonnyp/OhMySVG) |
| Browser extension | [SVG Gobbler](https://github.com/rossmoody/svg-gobbler) |
| API | [Vector Express](https://github.com/smidyo/vectorexpress-api#convertor-svgo) |

## Donors

| [<img src="https://sheetjs.com/sketch128.png" width="80">](https://sheetjs.com/) | [<img src="https://raw.githubusercontent.com/fontello/fontello/8.0.0/fontello-image.svg" width="80">](https://fontello.com/) |
Expand Down
51 changes: 51 additions & 0 deletions docs/02-usage/01-node.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
---
title: Node.js
slug: 'node'
---

To minimally use SVGO in Node.js, ensure you've installed the dependency by following the instructions in [Getting Started](../01-index.mdx#installation), then import the `optimize` function.

Here's a minimal example:

```js
import { optimize } from 'svgo';

const svg = `
<svg xmlns="http://www.w3.org/2000/svg"
xmlns:xlink="http://www.w3.org/1999/xlink"
viewBox="0 0 100 100">
<text x="50" y="50" text-anchor="middle">•ᴗ•</text>
</svg>
`;

const { data } = optimize(svg);
console.log(data);
// <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text x="50" y="50" text-anchor="middle">•ᴗ•</text></svg>
```

## Exports

<dl>
<dt>
<code>VERSION</code>
</dt>
<dd>Version of SVGO during runtime.</dd>
<dt>
<code>builtinPlugins</code>
</dt>
<dd>
Array of built-in plugins, including plugins that are disabled by default
and any presets.
</dd>
<dt>
<code>optimize(svgCode, svgoConfig)</code>
</dt>
<dd>Invokes the optimization and returns the optimized/minified SVG code.</dd>
<dt>
<code>loadConfig(configFile, directory)</code>
</dt>
<dd>
Utility to find the nearest <code>svgo.config.js</code> file by searching up
the parent directories.
</dd>
</dl>
84 changes: 84 additions & 0 deletions docs/02-usage/02-browser.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
---
title: Browser
slug: 'browser'
---

SVGO can run in the browser, but how to use it depends on the structure of your project.

## With Build Tools

These instructions are for when you're writing your website in a Node.js environment, probably with tools like [webpack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/) to build it.

Ensure you've installed the dependency by following the instructions in [Getting Started](../01-index.mdx#installation), then you can import `svgo/browser` to use SVGO on client-side.

Here's a minimal example using [React](https://react.dev/):

```js
import React from 'react';
import { optimize } from 'svgo/browser';

export default function SvgoDemo(props) {
const { svg, svgoConfig } = props;
const { data } = optimize(svg, svgoConfig);

return (
<>
<span id="before">{svg}</span>
<span id="after">{data}</span>
</>
);
}
```

## Without Build Tools

These instructions are for when you want to fetch the SVGO browser bundle from client-side. For example, when you're building a static website with a templating engine like Handlebars, SSG like Jekyll, or just plain old HTML.

You'll have to somehow serve a copy of `svgo.browser.js`, you could either:

- Download the latest version of `svgo.browser.js` from our [GitHub Releases](https://github.com/svg/svgo/releases), and place it in your project directory to self-serve it.
- Use a public CDN like [unpkg](https://unpkg.com/svgo/dist/svgo.browser.js) or [jsDelivr](https://cdn.jsdelivr.net/npm/svgo/dist/svgo.browser.js).

Here's a minimal example:

```html
<!doctype html>
<html lang="en">
<head>
<title>SVGO Browser Example</title>
<script type="module">
import { VERSION } from '/svgo.browser.js';
// You could also do:
// import { VERSION } from 'https://unpkg.com/svgo/dist/svgo.browser.js';

document.addEventListener('DOMContentLoaded', () => {
document.getElementById('version').innerHTML = VERSION;
});
</script>
</head>

<body>
<span id="version"></span>
</body>
</html>
```

## Exports

<dl>
<dt>
<code>VERSION</code>
</dt>
<dd>Version of SVGO during runtime.</dd>
<dt>
<code>builtinPlugins</code>
</dt>
<dd>
Array of built-in plugins, including plugins that are disabled by default
and any presets.
</dd>
<dt>
<code>optimize(svgCode, svgoConfig)</code>
</dt>
<dd>Invokes the optimization and returns the optimized/minified SVG code.</dd>
</dl>
34 changes: 34 additions & 0 deletions docs/02-usage/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
title: Usage
slug: 'usage'
---

We officially support four interfaces for SVGO:

- Command-line application - Get help with `svgo --help`, or read a [tl;dr](https://github.com/tldr-pages/tldr/blob/main/pages/common/svgo.md)!
- [Node.js library](./01-node.mdx) - For general use in Node.js.
- [Browser bundle](./02-browser.mdx) - For using SVGO on client-side in the browser.
- [Webpack loader](https://www.npmjs.com/package/svgo-loader) - Optimizes SVG imports with SVGO and returns a [Data URL](https://developer.mozilla.org/docs/web/http/basics_of_http/data_urls).

## Community

Thanks to the community who have integrated, wrapped, or otherwise adapated SVGO to play well with other tools, and ultimately made SVGO more accessible for everyone.

This section showcases reputable projects that are stable and well maintained. Please check the project's website for more information on how to use it.

### Integrations

Depending on your project stack, you may want to try one of these integrations to seemlessly incorporate SVGO into your workflow:

- [SVGR](https://react-svgr.com/) - Webpack loader that optimizes and transforms SVGs into React components.
- [grunt-svgmin](https://www.npmjs.com/package/grunt-svgmin) - Grunt task to optimize SVGs.
- [postcss-svgo](https://www.npmjs.com/package/postcss-svgo) - PostCSS plugin that optimizes inline SVGs in CSS.
- [@figma-export](https://figma-export.marcomontalbano.com/) - Node.js library to transforms Figma components into optimized SVGs.

### Frontends

The community have developed many frontends for SVGO, and some even have additional features on top:

- [SVGOMG](https://jakearchibald.github.io/svgomg/) - Web application that wraps SVGO.
- [Oh My SVG](https://flathub.org/apps/re.sonny.OhMySVG) - Linux desktop application that wraps SVGO.
- [SVG Gobbler](https://svggobbler.com/) - Browser extension for finding, optimizing, and exporting SVGs.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.