gatsby-remark-extract-image-attributes
Extract data attributes from the images in your Markdown (.md) files and add them to the remark AST for later processing.
Align And Size Markdown Images
This plugin can be used by itself, or in conjunction with the gatsby-remark-images-insert-wrapper-attributes plugin to extract image attributes and then apply them to the wrapper generated by gatsby-remark-images after image processing.
Using the two plugins together makes it simple to align and size images in your Markdown files while still taking advantage of Gatsby's excellent image optimization plugin, gatsby-remark-images.
Use With Gatsby Remark Copy Linked Files Plugin
The "stripMdAttributes" option can be used to remove url params prior to being processed by the gatsby-remark-copy-linked-files plugin. This setup can be very useful when using a git-backed CMS such as Forestry.io or NetlifyCMS where images must be stored in and referenced from the "static" directory.
To use this plugin with gatsby-remark-copy-linked-files (and Gatsby Remark Images), place it thusly in the gatsby-config.js plugins array:
{
resolve: `gatsby-transformer-remark`,
options: {
plugins: [
{
resolve: `gatsby-remark-extract-image-attributes`,
options: {
stripMdAttributes: true,
}
},
`gatsby-remark-copy-linked-files`,
`gatsby-remark-images`,
]
}
}
Getting Started
Compatibility
This plugin has been tested, and is compatible, with the following (related) dependencies:
- gatsby: ^3.3.1
- gatsby-transformer-remark: ^3.0.0
- gatsby-transformer-sharp: ^3.0.0
- gatsby-remark-images: ^4.0.0
Prerequisites
- gatsby-transformer-remark
- Node.js v10 or newer
Installation
npm install gatsby-remark-extract-image-attributes
Solo Usage
This plugin can be used by itself to extract image attributes. In your gatsby-config.js file, simply add it to the plugins array of the 'gatsby-transformer-remark' plugin.
// gatsby-config.js
plugins: [
{
resolve: `gatsby-transformer-remark`,
options: {
plugins: [
`gatsby-remark-extract-image-attributes`,
]
}
}
]
With gatsby-remark-images-insert-wrapper-attributes
In this configuration, the gatsby-remark-images plugin should be sandwiched in the middle, like so:
{
resolve: `gatsby-transformer-remark`,
options: {
plugins: [
`gatsby-remark-extract-image-attributes`,
`gatsby-remark-images`,
`gatsby-remark-images-insert-wrapper-attributes`
]
}
}
Options
properties
By default, the plugin extracts the "align", "width", and "height" attributes. Any number of additional custom data attributes can be captured by specifying the attribute name(s) in the "properties" array:
{
resolve: `gatsby-transformer-remark`,
options: {
plugins: [
{
resolve: `gatsby-remark-extract-image-attributes`,
options: {
properties: ["caption", "filesize", "format"]
}
},
]
}
}
stripMdAttributes (boolean)
When using Markdown syntax, setting this value to "true" will remove url params from the image source. For example, image.jpg?align=left&width=300 will become image.jpg.
{
resolve: `gatsby-transformer-remark`,
options: {
plugins: [
{
resolve: `gatsby-remark-extract-image-attributes`,
options: {
stripMdAttributes: true,
}
},
]
}
}
Image Attribute Examples
The plugin accepts both Markdown and HTML syntax.
Markdown
Attributes using Markdown syntax are accomplished by appending the desired data to the image source as URL params. This example shows align, height, width, and caption params. Make sure to URL-encode any data parameters that include spaces or characters outside the ASCII set :
HTML
With HTML syntax, the plugin first looks for data-* attributes:
<img src="my-image.jpg" alt="Alt text here" title="Title text here" data-align="left" data-height="1280" data-width="720" data-caption="My awesome picture caption">
If no data-* attribute is found, it will look for the attribute name alone:
<img src="my-image.jpg" alt="Alt text here" title="Title text here" align="left" height="1280" width="720" data-caption="My awesome picture">
Testing
To run Jest tests:
npm test