# gatsby-remark-copy-linked-files > Find files which are linked to from markdown and copy them to the public directory Latest version **6.16.0** (published 2026-01-26) · MIT license · 0 weekly downloads ## Install ```sh npm install gatsby-remark-copy-linked-files pnpm add gatsby-remark-copy-linked-files yarn add gatsby-remark-copy-linked-files bun add gatsby-remark-copy-linked-files ``` ## Health **Score 60/100 (C)** — status: stable. Positive: no vulnerabilities; high maintenance score; popular repo; extremely popular. Warnings: low downloads; no types; no esm support. ## Facts | | | |---|---| | Version | 6.16.0 | | Published | 2026-01-26 | | First published | 2017-05-05 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Node | >=18.0.0 <26 | | Dependencies | 8 | | Unpacked size | 64.3 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 55940 | | Author | Kyle Mathews | | Maintainers | pieh, kathmbeck, serhalp-netlify, mlgualtieri-gatsby, fk, tylerbarnes, daniellewgatsby | | Keywords | gatsby, gatsby-plugin, prismjs, remark | ## Links - npm: https://www.npmjs.com/package/gatsby-remark-copy-linked-files - Repository: https://github.com/gatsbyjs/gatsby - Homepage: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-copy-linked-files#readme - Issues: https://github.com/gatsbyjs/gatsby/issues - npm.io page: https://npm.io/package/gatsby-remark-copy-linked-files ## Dependencies (8) - [lodash](https://npm.io/package/lodash.md) ^4.17.21 - [cheerio](https://npm.io/package/cheerio.md) 1.0.0-rc.12 - [fs-extra](https://npm.io/package/fs-extra.md) ^11.2.0 - [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.20.13 - [path-is-inside](https://npm.io/package/path-is-inside.md) ^1.0.2 - [is-relative-url](https://npm.io/package/is-relative-url.md) ^3.0.0 - [probe-image-size](https://npm.io/package/probe-image-size.md) ^7.2.3 - [unist-util-visit](https://npm.io/package/unist-util-visit.md) ^2.0.3 ## Alternatives - [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads - [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads - [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads - [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads - [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads ## Recent versions - 6.16.0 (latest) — 2026-01-26 - 6.17.0-next.0 (next) — 2025-11-27 - 6.17.0-react19.1 (react19) — 2025-11-26 - 6.11.1-canary-less-lmdb.0 (less-lmdb) — 2024-12-20 - 4.12.0 (latest-v3) — 2022-12-07 - 5.25.0 (latest-v4) — 2022-12-07 - 6.0.0-alpha-drupal-proxyurl.14 (drupal-proxyurl) — 2022-11-22 - 5.14.0-alpha-transformer-json.26 (alpha-transformer-json) — 2022-10-12 - 6.0.0-alpha-v5.d20221012t101120.57 (alpha-v5) — 2022-10-12 - 5.23.0-alpha-a5-peer.70 (alpha-a5-peer) — 2022-09-14 - 5.23.0-alpha-preview-gh-api.26 (preview-gh-api) — 2022-09-08 - 5.23.0-alpha-9689ff.25 (alpha-9689ff) — 2022-08-31 - 5.18.0-alpha-drupal-self-reference.18 (drupal-self-reference) — 2022-07-19 - 5.15.0-alpha-wp-image-cdn-auth.48 (wp-image-cdn-auth) — 2022-05-20 - 5.8.0-alpha-image-service.24 (image-service) — 2022-02-10 - … 459 more at https://npm.io/package/gatsby-remark-copy-linked-files/versions ## README # gatsby-remark-copy-linked-files Copies local files linked to/from Markdown (`.md|.markdown`) files to the `public` folder. **A sample markdown file:** ```markdown --- title: My awesome blog post --- Hey everyone, I just made a sweet PDF with lots of interesting stuff in it. [Download it now](my-awesome-pdf.pdf) ``` **When you build your site:** The `my-awesome-pdf.pdf` file will be copied to the `public` folder (i.e., `public/some-really-long-contenthash/my-awesome-pdf.pdf`) and the generated HTML page will be modified to point to it. > **Note**: The `my-awesome-pdf.pdf` file should be in the same directory as the markdown file. ## Installation ```shell npm install gatsby-remark-copy-linked-files ``` ## Configuration ### Default settings Add `gatsby-remark-copy-linked-files` plugin as a plugin to [`gatsby-transformer-remark`](https://www.gatsbyjs.com/plugins/gatsby-transformer-remark/): ```js:title=gatsby-config.js module.exports = { plugins: [ { resolve: `gatsby-transformer-remark`, options: { plugins: [`gatsby-remark-copy-linked-files`], }, }, ], } ``` ### Custom settings ```js:title=gatsby-config.js module.exports = { plugins: [ { resolve: `gatsby-transformer-remark`, options: { plugins: [ { resolve: `gatsby-remark-copy-linked-files`, options: { destinationDir: `path/to/dir`, ignoreFileExtensions: [`png`, `jpg`, `jpeg`, `bmp`, `tiff`], }, }, ], }, }, ], } ``` ## Option: `destinationDir` By default, all files will be copied to the root of the `public` folder in the following format: `contentHash/fileName.ext`. For example, `[Download it now](my-awesome-pdf.pdf)` will copy the file `my-awesome-pdf.pdf` to something like `public/2a0039f3a61f4510f41678438e4c863a/my-awesome-pdf.pdf` ### Simple usage To change this, set `destinationDir` to a path of your own choosing (i.e., `path/to/dir`). ```js:title=gatsby-config.js { resolve: `gatsby-transformer-remark`, options: { plugins: [ { resolve: "gatsby-remark-copy-linked-files", options: { destinationDir: "path/to/dir", }, }, ], }, } ``` So now, `[Download it now](my-awesome-pdf.pdf)` will copy the file `my-awesome-pdf.pdf` to `public/path/to/dir/2a0039f3a61f4510f41678438e4c863a/my-awesome-pdf.pdf` ### Advanced usage For more control, set `destinationDir` to a function expression using properties `name`, `hash`, and `absolutePath` to specify the path. - `name`: The name of the file without the file extension - `hash`: The `internal.contentDigest` on the `File` node (guarantees a unique identifier) - `absolutePath`: The absolute path to the file, e.g. `/Users/your-name/example/project/src/pages/folder/my-awesome-pdf.pdf` **Examples:** ```js # save `my-awesome-pdf.pdf` to `public/my-awesome-pdf.pdf` destinationDir: f => `${f.name}` # save `my-awesome-pdf.pdf` to `public/2a0039f3a61f4510f41678438e4c863a.pdf` destinationDir: f => `${f.hash}` # save `my-awesome-pdf.pdf` to `public/downloads/2a0039f3a61f4510f41678438e4c863a/my-awesome-pdf.pdf` destinationDir: f => `downloads/${f.hash}/${f.name}` # save `my-awesome-pdf.pdf` to `public/downloads/2a0039f3a61f4510f41678438e4c863a-my-awesome-pdf.pdf` destinationDir: f => `downloads/${f.hash}-${f.name}` # save `my-awesome-pdf.pdf` to `public/my-awesome-pdf/2a0039f3a61f4510f41678438e4c863a.pdf` destinationDir: f => `${f.name}/${f.hash}` # save `my-awesome-pdf.pdf` to `public/path/to/dir/hello-my-awesome-pdf+2a0039f3a61f4510f41678438e4c863a_world.pdf` destinationDir: f => `path/to/dir/hello-${f.name}+${f.hash}_world` # save `src/pages/custom-folder/my-awesome-pdf.pdf` to `public/custom-folder/my-awesome-pdf.pdf` # Note: Import `path` to use this example https://nodejs.org/api/path.html destinationDir: f => `${path.dirname(path.relative(path.join(__dirname, `src`, `pages`), f.absolutePath))}/${f.name}` ``` **Please note:** Make sure you use either `name` or `hash` property in your function expression! If you don't include both `name` and `hash` properties in your function expression, `gatsby-remark-copy-linked-files` plugin will resolve the function expression to a string value and use default settings as a fallback mechanism to prevent your local files from getting copied with the same name (causing files to get overwritten). ```js # Note: `my-awesome-pdf.pdf` is saved to `public/hello/2a0039f3a61f4510f41678438e4c863a/my-awesome-pdf.pdf` # because `name` and `hash` properties are not referenced in the function expression. # So these function expressions are treated the same way destinationDir: _ => `hello` destinationDir: `hello` ``` ### Caveat: Error thrown if `destinationDir` points outside the `public` folder **Please note:** An error will be thrown if the destination points outside the `public` folder. **Correct:** ```js # saves to `public/path/to/dir/` destinationDir: `path/to/dir` # saves to `public/path/to/dir/` destinationDir: _ => `path/to/dir` # saves to `public/path/to/dir/fileName.ext` destinationDir: f => `path/to/dir/${f.name}` # saves to `public/contentHash.ext` destinationDir: f => `${f.hash}` ``` **Error thrown:** ```js # cannot save outside `public` folder destinationDir: `../path/to/dir` destinationDir: _ => `../path/to/dir` destinationDir: f => `../path/to/dir/${f.name}` destinationDir: f => `../${f.hash}` ``` ### Custom set which file types to ignore using `ignoreFileExtensions` By default, the file types that this plugin ignores are: `png`, `jpg`, `jpeg`, `bmp`, `tiff`. For example, `[Download it now](image.png)` will be ignored and not copied to the root of the `public` folder. To change this, set `ignoreFileExtensions` to an array of extensions to ignore (i.e., an empty array `[]` to ignore nothing). ```js:title=gatsby-config.js { resolve: `gatsby-transformer-remark`, options: { plugins: [ { resolve: "gatsby-remark-copy-linked-files", options: { // `ignoreFileExtensions` defaults to [`png`, `jpg`, `jpeg`, `bmp`, `tiff`] // as we assume you'll use gatsby-remark-images to handle // images in markdown as it automatically creates responsive // versions of images. // // If you'd like to not use gatsby-remark-images and just copy your // original images to the public directory, set // `ignoreFileExtensions` to an empty array. ignoreFileExtensions: [], }, }, ], }, } ``` So now, `[Download it now](image.png)` will be copied to the root of the `public` folder. ### Supported Markdown tags - img - `![Image](my-img.png)` - link - `[Link](myFile.txt)` ### Supported HTML tags - `` - `