Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub


Support Node of LTS npm version Actions Status: test code style: prettier

Copies local files relative linked to/from markdown to your public folder, preserving your directory structure.

This will copy the files linked relative to all Markdown files like gatsby-remark-copy-linked-files into a public directory structure like gatsby-remark-copy-images as it is. It can also copy additional files requested by the document.


$ npm install gatsby-remark-copy-relative-linked-files

How to use

// In your gatsby-config.js
plugins: [
    resolve: 'gatsby-transformer-remark',
    options: {
      plugins: ['gatsby-remark-copy-relative-linked-files'],

Note: When using the copyfiles code fence (see below), gatsby-remark-copy-relative-linked-files must appear before general purpose code fence processors like gatsby-remark-prismjs.

Then in your Markdown files, simply reference the files.


title: My awesome blog post

Hey everyone, here are some sweet files with lots of interesting stuff in them:

- ![](image.gif)
- [archive.zip](archive.zip)
- [sample.pdf](sample.pdf)
- [report.html](report.html)
- [not-copy.rar](https://example.com/not-copy.rar)


<img src="sales-growth.png" alt="Diagram of the sales growth" />

<audio src="sample.mp3" controls></audio>
<video src="sample.mp4" poster="thumbnail.jpg" controls></video>

<video controls>
  <source src="sample2.mp4" type="video/mp4">

<a href="sample.svg">SVG Image</a>

image.gif, archive.zip, sample.pdf and report.html should be in the same directory as the Markdown file. When you build your site, the files will be copied to the public folder and the markdown HTML will be modified to point to it.

Similarly, report.css and diagram.png should be in the same directory as the Markdown file. In this example, report.html has its own internal relative links to these files. report.html is not changed in any way. The relative links to the copied files work from the copied location.

The copy target is a relative link. Therefore, links starting with XXXX:// or // are ignored. In this example not-copy.rar is not copied.


Pull request by karlhorky also copied the href attribute of <a> tag, and poster attribute of <video> tag.


Pull request by karlhorky also copied the src attribute of <audio>/<video>/<source> tag.


// In your `gatsby-config.js`
plugins: [
    resolve: 'gatsby-transformer-remark',
    options: {
      plugins: [
          resolve: 'gatsby-remark-copy-relative-linked-files',
          options: {
            // By default, `.md` is specified
            // ignoreFileExtensions: ['.md']
            // These files will not be copied
            ignoreFileExtensions: ['.md', '.pdf', '.d.ts'],

            // Would generate file-1abcb33beeb811dca15f0ac3e47b88d9.pdf
            filename: ({ hash, name, extension }) =>
  • ignoreFileExtensions string[] - Specify the file extension to be ignored from copying. This plugin is for remark (Markdown), so it specifies .md by default.
  • filename (hash: string, name: string, extension: string) => string - Can control the file name as you like. See #15 for details.



© 2023 Gatsby, Inc.