Nachos Pillage Milwaukee

    remark-images
    TypeScript icon, indicating that this package has built-in type declarations

    3.1.0 • Public • Published

    remark-images

    Build Coverage Downloads Size Sponsors Backers Chat

    remark plugin to add a simpler image syntax.

    Contents

    What is this?

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

    unified is a project that transforms content with abstract syntax trees (ASTs). remark adds support for markdown to unified. mdast is the markdown AST that remark uses. This is a remark plugin that transforms mdast.

    When should I use this?

    Images are notoriously unintuitive 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.

    Another plugin, remark-unwrap-images, could be useful to unwrap images on their own in a paragraph.

    Install

    This package is ESM only. In Node.js (version 12.20+, 14.14+, or 16.0+), install with npm:

    npm install remark-images

    In Deno with Skypack:

    import remarkImages from 'https://cdn.skypack.dev/remark-images@3?dts'

    In browsers with Skypack:

    <script type="module">
      import remarkImages from 'https://cdn.skypack.dev/remark-images@3?min'
    </script>

    Use

    Say we have the following file example.md:

    Below will render an image:
    
    https://c8r-x0.s3.amazonaws.com/lab-components-macbook.jpg

    And our module example.js looks as follows:

    import {read} from 'to-vfile'
    import {remark} from 'remark'
    import remarkImages from 'remark-images'
    
    main()
    
    async function main() {
      const file = await remark()
        .use(remarkImages)
        .process(await read('example.md'))
    
      console.log(String(file))
    }

    Now, running node example yields:

    Below will render an image:
    
    [![](https://c8r-x0.s3.amazonaws.com/lab-components-macbook.jpg)](https://c8r-x0.s3.amazonaws.com/lab-components-macbook.jpg)

    API

    This package exports the identifier defaultImageExtensions. The default export is remarkImages.

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

    Plugin to add a simpler image syntax. Transform URLs in text that reference images (see defaultImageExtensions) to images.

    options

    Configuration (optional).

    options.imageExtensions

    List of file extensions recognized as images (Array.<string>?, default defaultImageExtensions).

    defaultImageExtensions

    List of file extensions recognized as an image by default (constant ['svg', 'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif']). Note: extension does not include ., only the extension name.

    Syntax

    This plugin looks for URLs and paths, on their own, that end in an image extension (see defaultImageExtensions). 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:

    • https://example.com/image.jpg
    • /image.jpg
    • ./image.jpg
    • ../image.jpg

    Syntax tree

    This plugin adds mdast Image and Link nodes to the syntax tree. These are the same nodes that represent images through ![](url) and links through [text](url) syntax.

    Types

    This package is fully typed with TypeScript. There are no extra exported types.

    Compatibility

    Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 12.20+, 14.14+, and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.

    This plugin works with unified version 3+ and remark version 4+.

    Security

    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) attack.

    This may become a problem if the markdown later transformed to rehype (hast) or opened in an unsafe markdown viewer.

    Related

    Contribute

    See contributing.md in remarkjs/.github for ways to get started. See support.md for ways to get help.

    This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

    License

    MIT © John Otander

    Install

    npm i remark-images

    DownloadsWeekly Downloads

    9,649

    Version

    3.1.0

    License

    MIT

    Unpacked Size

    13.8 kB

    Total Files

    5

    Last publish

    Collaborators

    • johno
    • wooorm