Skip to content

Latest commit

 

History

History
169 lines (118 loc) · 7.15 KB

README.md

File metadata and controls

169 lines (118 loc) · 7.15 KB
Raw

Inline SVG plugin for rehype

A rehype plugin that inlines and optimizes SVG images

Cross-Platform Compatibility Build Status

Coverage Status Dependencies

npm License Buy us a tree

Features

  • Replaces SVG <img> tags with inlined <svg> tags
  • Optimizes SVGs using svgo
    • Minimizes download size
    • Removes extra metadata that is added by image editors
  • Caches file reads
    • Each .svg file is only read from disk once and optimized once
    • Improves processing speed when images occur multiple times on a page
    • Improves processing speed when processing multiple HTML pages

Example

This example uses to-vfile to read an HTML file and process it using unified, rehype-parse, and rehype-stringify.

index.html

<html>
  <body>
    <img src="img/icon.svg" alt="some icon">
  </body>
</html>

example.js

const unified = require("unified");
const parse = require("rehype-parse");
const inlineSVG = require("@jsdevtools/rehype-inline-svg");
const stringify = require("rehype-stringify");
const vfile = require("to-vfile");

async function example() {
  // Create a Rehype processor with the Inline SVG plugin
  const processor = unified()
    .use(parse)
    .use(inlineSVG)
    .use(stringify);

  // Read an HTML file that contains SVG images
  let originalFile = await vfile.read("index.html");

  // Process the file, inlining and optimizing SVG images
  let modifiedFile = await processor.process(originalFile);

  // The result is HTML with inlined <svg> elements
  console.log(modifiedFile.contents);

  // <html>
  //   <body>
  //     <svg alt="some icon" viewBox="0 0 48 48"><path d="M5 24c0...
  //   </body>
  // </html>
}

Installation

You can install Rehype Inline SVG via npm.

npm install @jsdevtools/rehype-inline-svg

You'll probably want to install unified, rehype-parse, rehype-stringify, and to-vfile as well.

npm install unified rehype-parse rehype-stringify to-vfile

Usage

Using the Inline SVG plugin requires an understanding of how to use Unified and Rehype. Here is an excelleng guide to learn the basics.

The Inline SVG plugin works just like any other Rehype plugin. Pass it to the .use() method, optionally with an options object.

const unified = require("unified");
const inlineSVG = require("@jsdevtools/rehype-inline-svg");

// Use the Inline SVG plugin with its default options
unified().use(inlineSVG);

// Use the Inline SVG plugin with custom options
unified().use(inlineSVG, {
  maxImageSize: 5000,          // Don't inline SVGs larger than 5 kb
  maxTotalSize: 25000,    // 25 kb limit for all occurrences of each SVG
  optimize: false,            // Don't optimize SVGs
});

Options

Rehype Inline SVG supports the following options:

Option Type Default Description
maxImageSize number 3000 The maximum image size (in bytes) to inline. Images that are larger than this (after optimization) will not be inlined.

Defaults to ~3 kilobytes.
maxOccurrences number Infinity The maximum number of times that the same image can appear on a page and still be inlined. Images that occur more than this number of times will not be inlined.
maxTotalSize number 10000 The maximum total size (in bytes) of all occurrences of a single image. If maxTotalSize is 10kb and a 2kb image occurs 5 times on a page, then all five occurrences will be inlined. But if the image accurs 6 or more times, then none of them will be inlined.

Defaults to ~10 kilobytes.
optimize boolean or object true SVG optimization options. If false, then SVGs will not be optimized. If true, then the default optimization options will be used.

Contributing

Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.

Building

To build the project locally on your computer:

  1. Clone this repo
    git clone https://github.com/JS-DevTools/rehype-inline-svg.git

  2. Install dependencies
    npm install

  3. Build the code
    npm run build

  4. Run the tests
    npm test

License

Rehype Inline SVG is 100% free and open-source, under the MIT license. Use it however you want.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❤

GitHub NPM Coveralls Travis CI SauceLabs