WIP - add extractor, generate snippet_data
This commit is contained in:
Stefan Fejes
350
node_modules/gatsby-plugin-sharp/README.md
generated
vendored
Normal file
350
node_modules/gatsby-plugin-sharp/README.md
generated
vendored
Normal file
@ -0,0 +1,350 @@
|
||||
# gatsby-plugin-sharp
|
||||
|
||||
Exposes several image processing functions built on the
|
||||
[Sharp image processing library](https://github.com/lovell/sharp). This is a
|
||||
low-level helper plugin generally used by other Gatsby plugins. You generally
|
||||
shouldn't be using this directly but might find it helpful if doing very custom
|
||||
image processing.
|
||||
|
||||
It aims to provide excellent out-of-the box settings for processing common web
|
||||
image formats.
|
||||
|
||||
For JPEGs it generates progressive images with a default quality level of 50.
|
||||
|
||||
For PNGs it uses [pngquant](https://github.com/pornel/pngquant) to compress
|
||||
images. By default it uses a quality setting of [50-75]. The `pngCompressionSpeed`
|
||||
value is a speed/quality trade-off from 1 (brute-force) to 10 (fastest). Speed
|
||||
10 has 5% lower quality, but is 8 times faster than the default (4). In most
|
||||
cases you should stick with the default, but if you have very large numbers
|
||||
of PNGs then it can significantly reduce build times.
|
||||
|
||||
## Install
|
||||
|
||||
`npm install --save gatsby-plugin-sharp`
|
||||
|
||||
## How to use
|
||||
|
||||
```javascript
|
||||
// In your gatsby-config.js
|
||||
plugins: [
|
||||
{
|
||||
resolve: `gatsby-plugin-sharp`,
|
||||
options: {
|
||||
useMozJpeg: false,
|
||||
stripMetadata: true,
|
||||
defaultQuality: 75,
|
||||
},
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
## Methods
|
||||
|
||||
### resize
|
||||
|
||||
#### Parameters
|
||||
|
||||
- `width` (int, default: 400)
|
||||
- `height` (int)
|
||||
- `quality` (int, default: 50)
|
||||
- `jpegProgressive` (bool, default: true)
|
||||
- `pngCompressionLevel` (int, default: 9)
|
||||
- `base64`(bool, default: false)
|
||||
|
||||
#### Returns
|
||||
|
||||
- `src` (string)
|
||||
- `width` (int)
|
||||
- `height` (int)
|
||||
- `aspectRatio` (float)
|
||||
|
||||
### fixed
|
||||
|
||||
Automatically create sizes for different resolutions — we do 1x, 1.5x, and 2x.
|
||||
|
||||
#### Parameters
|
||||
|
||||
- `width` (int, default: 400)
|
||||
- `height` (int)
|
||||
- `quality` (int, default: 50)
|
||||
|
||||
#### Returns
|
||||
|
||||
- `base64` (string)
|
||||
- `aspectRatio` (float)
|
||||
- `width` (float)
|
||||
- `height` (float)
|
||||
- `src` (string)
|
||||
- `srcSet` (string)
|
||||
|
||||
### fluid
|
||||
|
||||
Create fluid sizes (in width) for the image. If the max width of the container for the
|
||||
rendered markdown file is 800px, the sizes would then be: 200px, 400px, 800px, 1200px,
|
||||
1600px – enough to provide close to the optimal image size for every device
|
||||
size / screen resolution.
|
||||
|
||||
If you want more control over which sizes are output you can use the `srcSetBreakpoints`
|
||||
parameter. For example, if you want images that are 200, 340, 520, and 890 wide you
|
||||
can add `srcSetBreakpoints: [ 200, 340, 520, 890 ]` as a parameter. You will also get
|
||||
`maxWidth` as a breakpoint (which is 800 by default), so you will actually get
|
||||
`[ 200, 340, 520, 800, 890 ]` as breakpoints.
|
||||
|
||||
On top of that, `fluid` returns everything else (namely aspectRatio and
|
||||
a base64 image to use as a placeholder) you need to implement the "blur up"
|
||||
technique popularized by Medium and Facebook (and also available as a Gatsby
|
||||
plugin for Markdown content as gatsby-remark-images).
|
||||
|
||||
When both a `maxWidth` and `maxHeight` are provided, sharp will use `COVER` as a fit strategy by default. This might not be ideal so you can now choose between `COVER`, `CONTAIN` and `FILL` as a fit strategy. To see them in action the [CSS property object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) comes close to its implementation.
|
||||
|
||||
#### Note
|
||||
|
||||
fit strategies `CONTAIN` and `FILL` will not work when `cropFocus` is assigned to [sharp.strategy][6]. The `cropFocus` option cannot be `ENTROPY` or `ATTENTION`
|
||||
|
||||
#### Parameters
|
||||
|
||||
- `maxWidth` (int, default: 800)
|
||||
- `maxHeight` (int)
|
||||
- `quality` (int, default: 50)
|
||||
- `srcSetBreakpoints` (array of int, default: [])
|
||||
- `fit` (string, default: '[sharp.fit.cover][6]')
|
||||
- `background` (string, default: 'rgba(0,0,0,1)')
|
||||
- [deprecated] `sizeByPixelDensity` (bool, default: false)
|
||||
- Pixel density is only used in vector images, which Gatsby’s implementation of Sharp doesn’t support. This option is currently a no-op and will be removed in the next major version of Gatsby.
|
||||
|
||||
#### Returns
|
||||
|
||||
- `base64` (string)
|
||||
- `aspectRatio` (float)
|
||||
- `src` (string)
|
||||
- `srcSet` (string)
|
||||
- `srcSetType` (string)
|
||||
- `sizes` (string)
|
||||
- `originalImg` (string)
|
||||
|
||||
### Shared Options
|
||||
|
||||
In addition to their individual parameters, all methods above share the
|
||||
following:
|
||||
|
||||
- `grayscale` (bool, default: false)
|
||||
- `duotone` (bool|obj, default: false)
|
||||
- `toFormat` (string, default: '')
|
||||
- `cropFocus` (string, default: '[sharp.strategy.attention][6]')
|
||||
- `pngCompressionSpeed` (int, default: 4)
|
||||
|
||||
#### toFormat
|
||||
|
||||
Convert the source image to one of the following available options: `NO_CHANGE`,
|
||||
`JPG`, `PNG`, `WEBP`.
|
||||
|
||||
#### cropFocus
|
||||
|
||||
Change the cropping focus. Available options: `CENTER`, `NORTH`, `NORTHEAST`,
|
||||
`EAST`, `SOUTHEAST`, `SOUTH`, `SOUTHWEST`, `WEST`, `NORTHWEST`, `ENTROPY`,
|
||||
`ATTENTION`. See Sharp's [crop][6].
|
||||
|
||||
#### rotate
|
||||
|
||||
Rotate the image (after cropping). See Sharp's [rotate][7].
|
||||
|
||||
#### grayscale
|
||||
|
||||
Uses Sharp's [greyscale][8] to convert the source image to 8-bit greyscale, 256
|
||||
shades of grey, e.g.
|
||||
|
||||
```javascript
|
||||
allImageSharp {
|
||||
edges {
|
||||
node {
|
||||
... on ImageSharp {
|
||||
resize(width: 150, height: 150, grayscale: true) {
|
||||
src
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### duotone
|
||||
|
||||
Applys a "duotone" effect (see [I][1], [II][2], [III][3]) to the source image if
|
||||
given two hex colors `shadow` and `highlight` defining start and end color of
|
||||
the duotone gradient, e.g.
|
||||
|
||||
```javascript
|
||||
fixed(
|
||||
width: 800,
|
||||
duotone: {
|
||||
highlight: "#f00e2e",
|
||||
shadow: "#192550"
|
||||
}
|
||||
) {
|
||||
src
|
||||
srcSet
|
||||
base64
|
||||
}
|
||||
```
|
||||
|
||||
the source image colors will be converted to match a gradient color chosen based
|
||||
on each pixel's [relative luminance][4].\
|
||||
Logic is borrowed from [react-duotone][5].
|
||||
|
||||
You can pass a third optional parameter, `opacity`:
|
||||
|
||||
```javascript
|
||||
fluid(
|
||||
width: 800,
|
||||
duotone: {
|
||||
highlight: "#f00e2e",
|
||||
shadow: "#192550",
|
||||
opacity: 50
|
||||
}
|
||||
) {
|
||||
src
|
||||
srcSet
|
||||
base64
|
||||
}
|
||||
```
|
||||
|
||||
If set, a semi-transparent version of duotone'd image will be composited over
|
||||
the original image, allowing the original image and its colors to partially
|
||||
"shine through". _Heads up_: If the original image contains an alpha channel it
|
||||
will be [flattened][15] before creating the composite.
|
||||
|
||||
This works by adding an alpha channel to the duotone'd image - then we let Sharp
|
||||
do its magic via
|
||||
[`overlayWith`](http://sharp.pixelplumbing.com/en/stable/api-composite/#overlaywith);
|
||||
quoting the Sharp documentation:
|
||||
|
||||
> If the overlay image contains an alpha channel then composition with
|
||||
> <a href="https://en.wikipedia.org/wiki/Alpha_compositing">premultiplication</a>
|
||||
> will occur.
|
||||
|
||||
#### tracedSVG
|
||||
|
||||
Generates a traced SVG of the image (see [the original GitHub issue][9]) and
|
||||
returns the SVG as "[optimized URL-encoded][10]" `data:` URI. It it used in
|
||||
[gatsby-image](/packages/gatsby-image/) to provide an
|
||||
alternative to the default inline base64 placeholder image.
|
||||
|
||||
Uses [node-potrace][11] and [SVGO][12] under the hood. Default settings for
|
||||
node-potrace:
|
||||
|
||||
```javascript
|
||||
{
|
||||
color: `lightgray`,
|
||||
optTolerance: 0.4,
|
||||
turdSize: 100,
|
||||
turnPolicy: TURNPOLICY_MAJORITY,
|
||||
}
|
||||
```
|
||||
|
||||
All [node-potrace `Potrace` parameters][13] are exposed and can be set via the
|
||||
`traceSVG` argument:
|
||||
|
||||
```javascript
|
||||
fixed(
|
||||
traceSVG: {
|
||||
color: "#f00e2e"
|
||||
turnPolicy: TURNPOLICY_MINORITY
|
||||
blackOnWhite: false
|
||||
}
|
||||
) {
|
||||
src
|
||||
srcSet
|
||||
tracedSVG
|
||||
}
|
||||
```
|
||||
|
||||
### Setting a default quality
|
||||
|
||||
You can pass a default image quality to `sharp` by setting the `defaultQuality` option.
|
||||
|
||||
### Using MozJPEG
|
||||
|
||||
You can opt-in to use [MozJPEG][16] for jpeg-encoding. MozJPEG provides even
|
||||
better image compression than the default encoder used in `gatsby-plugin-sharp`.
|
||||
However, when using MozJPEG the build time of your Gatsby project will increase
|
||||
significantly.
|
||||
|
||||
To enable MozJPEG, you can set the `useMozJpeg` plugin option to `true` in
|
||||
`gatsby-config.js`.
|
||||
|
||||
For backwards compatible reasons, if `useMozJpeg` is not defined in the plugin
|
||||
options, the [environment variable](/docs/environment-variables/#environment-variables)
|
||||
`GATSBY_JPEG_ENCODER` acts as a fallback if set to `MOZJPEG`:
|
||||
|
||||
```shell
|
||||
GATSBY_JPEG_ENCODER=MOZJPEG
|
||||
```
|
||||
|
||||
### EXIF and ICC metadata
|
||||
|
||||
By default, `gatsby-plugin-sharp` strips all EXIF, ICC and other metadata
|
||||
present in your source file. This is the recommended default as it leads to
|
||||
smaller file sizes.
|
||||
|
||||
However, in situations where you wish to preserve EXIF metadata or ICC profiles
|
||||
(example: you are building a photography portfolio and wish to conserve
|
||||
the color profile or the copyright information of the photos you've exported
|
||||
from Adobe Lightroom or Phase One's Capture One), you can set the `stripMetadata`
|
||||
plugin option to `false` in `gatsby-config.js`.
|
||||
|
||||
It is important to note that if `stripMetadata` is set to `false`, **all**
|
||||
metadata information will be preserved from the source image, including but not
|
||||
limited to the latitude/longitude information of where the picture was taken
|
||||
(if present). If you wish to strip this information from the source file, you
|
||||
can either leave `stripMetadata` to its default of `true`, or manually
|
||||
pre-process your images with a tool such as [ExifTool][17].
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Incompatible library version: sharp.node requires version X or later, but Z provides version Y
|
||||
|
||||
This means that there are multiple incompatible versions of the `sharp` package installed in `node_modules`. The complete error typically looks like this:
|
||||
|
||||
```
|
||||
Something went wrong installing the "sharp" module
|
||||
|
||||
dlopen(/Users/misiek/dev/gatsby-starter-blog/node_modules/sharp/build/Release/sharp.node, 1): Library not loaded: @rpath/libglib-2.0.dylib
|
||||
Referenced from: /Users/misiek/dev/gatsby-starter-blog/node_modules/sharp/build/Release/sharp.node
|
||||
Reason: Incompatible library version: sharp.node requires version 6001.0.0 or later, but libglib-2.0.dylib provides version 5801.0.0
|
||||
```
|
||||
|
||||
To fix this, you'll need to update all Gatsby plugins in the current project that depend on the `sharp` package. Here's a list of official plugins that you might need to update in case your projects uses them:
|
||||
|
||||
- `gatsby-plugin-sharp`
|
||||
- `gatsby-plugin-manifest`
|
||||
- `gatsby-remark-images-contentful`
|
||||
- `gatsby-source-contentful`
|
||||
- `gatsby-transformer-sharp`
|
||||
- `gatsby-transformer-sqip`
|
||||
|
||||
To update these packages, run:
|
||||
|
||||
```sh
|
||||
npm install gatsby-plugin-sharp gatsby-plugin-manifest gatsby-remark-images-contentful gatsby-source-contentful gatsby-transformer-sharp gatsby-transformer-sqip
|
||||
```
|
||||
|
||||
If updating these doesn't fix the issue, your project probably uses other plugins from the community that depend on a different version of `sharp`. Try running `npm list sharp` or `yarn why sharp` to see all packages in the current project that use `sharp` and try updating them as well.
|
||||
|
||||
[1]: https://alistapart.com/article/finessing-fecolormatrix
|
||||
[2]: http://blog.72lions.com/blog/2015/7/7/duotone-in-js
|
||||
[3]: https://ines.io/blog/dynamic-duotone-svg-jade
|
||||
[4]: https://en.wikipedia.org/wiki/Relative_luminance
|
||||
[5]: https://github.com/nagelflorian/react-duotone
|
||||
[6]: http://sharp.pixelplumbing.com/en/stable/api-resize/#crop
|
||||
[7]: http://sharp.pixelplumbing.com/en/stable/api-operation/#rotate
|
||||
[8]: http://sharp.pixelplumbing.com/en/stable/api-colour/#greyscale
|
||||
[9]: https://github.com/gatsbyjs/gatsby/issues/2435
|
||||
[10]: https://codepen.io/tigt/post/optimizing-svgs-in-data-uris
|
||||
[11]: https://github.com/tooolbox/node-potrace
|
||||
[12]: https://github.com/svg/svgo
|
||||
[13]: https://github.com/tooolbox/node-potrace#parameters
|
||||
[14]: https://github.com/oliver-moran/jimp
|
||||
[15]: http://sharp.pixelplumbing.com/en/stable/api-operation/#flatten
|
||||
[16]: https://github.com/mozilla/mozjpeg
|
||||
[17]: https://www.sno.phy.queensu.ca/~phil/exiftool/
|
||||
[18]: https://www.npmjs.com/package/color
|
||||
Reference in New Issue
Block a user