gatsby-remark-relative-images

Convert image src(s) in markdown/html/frontmatter to be relative to their node's parent directory. This will help gatsby-remark-images match images outside the node folder. This was built for use with NetlifyCMS and should be considered a temporary solution until relative paths are supported. If it works for other use cases then great!

Features

• Converts markdown/mdx images
• Converts src in markdown/mdx html <img /> tags
• Converts frontmatter fields, supports nested fields
• Suports Unicode characters
• Frontmatter field filters (include/exclude)

v2 Breaking Changes:

The fmImagesToRelative() function has been removed, it is no longer needed.

NOTE: v2 greatly simplifies things and seems to work well for my use-case (NetlifyCMS), if you were previously using this plugin for something else that no longer works with v2, please open an issue and let me know and I will try to accomodate your use-case. Thanks.

Install

1# Install v2 (Recommended)
2yarn add gatsby-remark-relative-images
3
4# Install v1 (TS refactor, but quickly found more things to simplfy, skip)
5npm i gatsby-remark-relative-images@1.1.1
6
7# Install original (a bit hacky but have previously worked for most)
8npm i gatsby-remark-relative-images@0.3.0
9npm i gatsby-remark-relative-images@0.2.0

Usage Example

This usage example is for v2 of this plugin.

/gatsby-config.js

1module.exports = {
2  plugins: [
3    // Add static assets before markdown files
4    {
5      resolve: 'gatsby-source-filesystem',
6      options: {
7        path: `${__dirname}/static/uploads`,
8        name: 'uploads',
9      },
10    },
11    {
12      resolve: 'gatsby-source-filesystem',
13      options: {
14        path: `${__dirname}/src/pages`,
15        name: 'pages',
16      },
17    },
18    {
19      resolve: `gatsby-transformer-remark`,
20      options: {
21        plugins: [
22          // gatsby-remark-relative-images must go before gatsby-remark-images
23          {
24            resolve: `gatsby-remark-relative-images`,
25            options: {
26              // [Optional] The root of "media_folder" in your config.yml
27              // Defaults to "static"
28              staticFolderName: 'static',
29              // [Optional] Include the following fields, use dot notation for nested fields
30              // All fields are included by default
31              include: ['featured'],
32              // [Optional] Exclude the following fields, use dot notation for nested fields
33              // No fields are excluded by default
34              exclude: ['featured.skip'],
35            },
36          },
37          {
38            resolve: `gatsby-remark-images`,
39            options: { maxWidth: 1024 },
40          },
41        ],
42      },
43    },
44  ],
45};

/static/admin/config.yml

1# ...
2media_folder: static/img
3public_folder: /img
4# ...

/src/pages/blog-post.md

1---
2templateKey: blog-post
3title: A beginners’ guide to brewing with Chemex
4date: 2017-01-04T15:04:10.000Z
5featured: { image: /img/chémex.jpg, skip: /img/chémex.jpg }
6<!-- featured: { image: ../../static/img/chémex.jpg, skip: /img/chémex.jpg } -->
7description: Brewing with a Chemex probably seems like a complicated, time-consuming ordeal, but once you get used to the process, it becomes a soothing ritual that's worth the effort every time.
8---
9
10![chemex](/img/chémex.jpg)
11
12<!-- ![chemex](../../static/img/chémex.jpg) -->
13
14This week we’ll **take** a look at all the steps required to make astonishing coffee with a Chemex at home. The Chemex Coffeemaker is a manual, pour-over style glass-container coffeemaker that Peter Schlumbohm invented in 1941, and which continues to be manufactured by the Chemex Corporation in Chicopee, Massachusetts.
15
16In 1958, designers at the [Illinois Institute of Technology](https://www.spacefarm.digital) said that the Chemex Coffeemaker is _"one of the best-designed products of modern times"_, and so is included in the collection of the Museum of Modern Art in New York City.
17
18## The little secrets of Chemex brewing
19
20<img src="/img/chémex.jpg" alt="" style="width: 250px" />
21<!-- <img src="../../static/img/chémex.jpg" alt="" style="width: 250px" /> -->
22
23The Chemex Coffeemaker consists of an hourglass-shaped glass flask with a conical funnel-like neck (rather than the cylindrical neck of an Erlenmeyer flask) and uses proprietary filters, made of bonded paper (thicker-gauge paper than the standard paper filters for a drip-method coffeemaker) that removes most of the coffee oils, brewing coffee with a taste that is different than coffee brewed in other coffee-making systems; also, the thicker paper of the Chemex coffee filters may assist in removing cafestol, a cholesterol-containing compound found in coffee oils.

FAQs

I'm getting the error: Field "image" must not have a selection since type "String" has no subfields

This is a common error when working with Netlify CMS (see issue gatsby/gatsby#5990).

The application must include the media with gatsby-source-filesystem to include all the uploaded media and to make it available on build time. Note: The media folder must be included before the other content.

For example, an application that is using NetlifyCMS and this plugin, and has a content folder with markdown that comes from Netlify. Here's how the gatsby-config.js should look like:

1module.exports = {
2  plugins: [
3    {
4      resolve: `gatsby-source-filesystem`,
5      options: {
6        path: `${__dirname}/static/assets`,
7        name: 'assets',
8      },
9    },
10    {
11      resolve: `gatsby-source-filesystem`,
12      options: {
13        path: `${__dirname}/src/content`,
14        name: 'content',
15      },
16    },
17    `gatsby-transformer-sharp`,
18    `gatsby-plugin-sharp`,
19    {
20      resolve: `gatsby-transformer-remark`,
21      options: {
22        plugins: [
23          `gatsby-remark-relative-images`,
24          {
25            resolve: `gatsby-remark-images`,
26            options: {},
27          },
28        ],
29      },
30    },
31    `gatsby-plugin-netlify-cms`,
32  ],
33};