remark plugin to add a simpler image syntax

Downloads in past


4.0.09 months ago6 years agoMinified + gzip package size for remark-images in KB


!Buildbuild-badgebuild !Coveragecoverage-badgecoverage !Downloadsdownloads-badgedownloads !Sizesize-badgesize !Sponsorssponsors-badgecollective !Backersbackers-badgecollective !Chatchat-badgechat
remark plugin to add a simpler image syntax.


*   [`defaultImageExtensions`](#defaultimageextensions)
*   [`unified().use(remarkImages[, options])`](#unifieduseremarkimages-options)
*   [`Options`](#options)

What is this?

This package is a unified
(remark) plugin to add a simpler image syntax.

When should I use this?

Images are notoriously unintuitivetweet in markdown. This projects adds a different way to include images: by pasting in a URL or path to them (such as ./image.jpg). The behavior added by this plugin is nice when you’re authoring your own markdown and are sure that you’re explaining what happens in images in surrounding prose (as you can’t add alt text with this).
Another plugin, remark-unwrap-imagesremark-unwrap-images, could be useful to unwrap images on their own in a paragraph.


This package is ESM onlyesm. In Node.js (version 16+), install with npm:
npm install remark-images

In Deno with esm.shesmsh:
import remarkImages from ''

In browsers with esm.shesmsh:
<script type="module">
  import remarkImages from ''


Say we have the following file
Original plates from Clyde Tombaugh’s discovery of Pluto:

…and a module example.js:
import {remark} from 'remark'
import remarkImages from 'remark-images'
import {read} from 'to-vfile'

const file = await remark()
  .process(await read(''))


…then running node example.js yields:
Original plates from Clyde Tombaugh’s discovery of Pluto:



This package exports the identifier defaultImageExtensionsapi-default-image-extensions. The default export is remarkImagesapi-remark-images.


Extensions recognized as images by default (Array<string>). Currently ['avif', 'gif', 'jpeg', 'jpg', 'png', 'svg', 'webp'].

unified().use(remarkImages[, options])

Add a simpler image syntax.
— configuration
Transform (Transformerunified-transformer).


Configuration (TypeScript type).
  • imageExtensions (Array<string>, default:
— file extensions (without dot) to treat as images


This plugin looks for URLs and paths, on their own, that end in an image extension. If they occur inside a link already, then only an image is created. If they instead do not occur in a link, the image is also linked.
Some examples of URLs and paths are:
  • /image.jpg
  • ./image.jpg
  • ../image.jpg

Syntax tree

This plugin adds mdast Imagemdast-image and Linkmdast-link nodes to the syntax tree. These are the same nodes that represent images through ![](url) and links through [text](url) syntax.


This package is fully typed with TypeScript. It exports the additional type Optionsapi-options.


Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of Node. This means we try to keep the current release line, remark-images@^4, compatible with Node.js 16.
This plugin works with unified version 3+ and remark version 4+.


Although this plugin should be safe to use, always be careful with user input. For example, it’s possible to hide JavaScript inside images (such as GIFs, WebPs, and SVGs). User provided images open you up to a cross-site scripting (XSS)wiki-xss attack.
This may become a problem if the markdown later transformed to rehype (hast) or opened in an unsafe markdown viewer.


— remove the wrapping paragraph for images
— embed local images as data URIs


contributing in remarkjs/.githubhealth for ways to get started. See support.mdsupport for ways to get help.
This project has a code of conductcoc. By interacting with this repository, organization, or community you agree to abide by its terms.


MITlicense © John Otanderauthor