Working with Images in Markdown Posts and Pages
When building Gatsby sites composed primarily of Markdown pages or posts, insertion of images can enhance the content. You can add images in multiple ways.
In sites like a blog, you may want to include a featured image that appears at the top of a page. One way to do this is to grab the image filename from a frontmatter field and then transform it with
gatsby-plugin-sharp in a GraphQL query.
This solution assumes you already have programmatically generated pages from Markdown with renderers like
gatsby-plugin-mdx. If not, take a read through up to Part 7 of the Gatsby Tutorial. This will build upon the tutorial and as such,
gatsby-transformer-remark will be used for this example.
Note: This can be done similarly using MDX as well. Instead of the
markdownRemarknodes in GraphQL,
Mdxcan be swapped in and should work.
To start out, download the plugins for Gatsby-image as mentioned in Using gatsby-image.
You will also want to have
gatsby-source-filesystem installed. Then, configure the various plugins in the
If your images are in the same directory as the Markdown files, sourcing and resolving the images can be done in one configuration. For example, if your Markdown pages and images are located together in a
/pages directory, both content types will be automatically picked up by GraphQL as part of Gatsby’s data layer.
Then, in an example Markdown file, add a field called
The next step will be to incorporate the data into a template with a GraphQL query, which can be found later in this guide.
There are also occasions when you may want to source images from a different directory than where your Markdown posts or pages are located, such as in an external
/images folder. You can set this up by specifying two distinct sources, one for the pages and the other for images:
Then, in a Markdown file, the path to a
featuredImage would be relative to the page file (in this case, in an
/images directory up a level):
Now that you’ve sourced Markdown and image data, you can query for featured images in GraphQL. If a filepath points to an actual image, it will be transformed into a
File node in GraphQL and then you can get the image data out of it by using the
This can be added to the GraphQL query in a Markdown template file. In this example, a Fluid query is used to make a responsive image.
Also in the Markdown post template, import the
gatsby-image package and pass the results of the GraphQL query into an
<Img /> component.
Your featured image should now appear on the generated page right below the main header. Tada!
You may also include images in the Markdown body itself. The plugin gatsby-remark-images comes in handy for this.
Start out by installing
Also make sure that
gatsby-source-filesystem is installed and points at the directory where your images are located.
Configure the plugins in your
gatsby-config file. As with the previous example, either
MDX can be used.
The below example uses the
gatsby-remark-images needs to be both a sub-plugin of
gatsby-plugin-mdx, included in the
options field, and a string entry in the plugins array.
gatsby-plugin-sharp can be included on its own.
gatsby-source-filesystem needs to be pointed at wherever you have your images on disk.
Note: This example configuration assumes your images and Markdown pages are sourced from the same directory. Check out the section on configuring for different directories for additional help.
Here is a similar example using the
gatsby-transformer-remark plugin instead of
gatsby-plugin-mdx. Put the
gatsby-remark-images plugin within the
plugins option field of
With the configurations above, you can use the default Markdown syntax for images. They will be processed by Sharp and appear as if you placed them in a