Skip to content

Latest commit

 

History

History
117 lines (82 loc) · 3.14 KB

README.md

File metadata and controls

117 lines (82 loc) · 3.14 KB
Raw

Remark Accessible Image Plugin

Build

This is a plugin for Remark, and allows you to embed accessible images in markdown files. This plugin can also be used with Gridsome.

Installation

npm i remark-a11y-image --save-dev
# yarn add remark-a11y-image --dev

Configuration

If you want alignment to work, you'll have to supply css classes.

There's three options:

  • cssClassToCenterImage

    Example value w-full flex justify-center

  • cssClassToLeftAlignImage

    Example value w-full flex justify-start

  • cssClassToRightAlignImage

    Example value w-full flex justify-end

Remark configuration:

  const remark = require("remark");
  const a11y_image = require("remark-a11y-image");

  const processor = remark().use(a11y_image, {
    cssClassToCenterImage: "w-full flex justify-center",
    cssClassToLeftAlignImage: "w-full flex justify-start",
    cssClassToRightAlignImage: "w-full flex justify-end",
  });

Gridsome configuration:

module.exports = {
  plugins: [
    {
      use: "@gridsome/source-filesystem",
      options: {
        path: "blog/**/*.md",
        route: "/blog/:year/:month/:day/:slug",
        remark: {
          plugins: [
            [
              "gridsome-remark-a11y-image",
              {
                  cssClassToCenterImage: "w-full flex justify-center",
                  cssClassToLeftAlignImage: "w-full flex justify-start",
                  cssClassToRightAlignImage: "w-full flex justify-end",
              },
            ]
          ]
        }
      }
    }
  ]
}

Usage in markdown

The markdown must consist of all the possible attributes (image, decorative, alt & placement), and you must enclose the markdown in backticks (`).

Format:

`image [IMAGE_LINK] decorative [TRUE|FALSE] alt [ALT_TEXT] placement [Left|Center|Right]`

Examples:

`image https://avatars.githubusercontent.com/u/9387114?s=60&v=4 decorative true alt placement Center`

or

`image https://avatars.githubusercontent.com/u/9387114?s=60&v=4 decorative true alt This alt text won't be shown placement Center`

or

`image https://avatars.githubusercontent.com/u/9387114?s=60&v=4 decorative false alt This is alt text will be shown placement Center`

Output

Image

This is how the image should appear on the screen:

Generated HTML

<div class="w-full flex justify-start"> <!-- whatever css you've provided -->
  <img src="https://avatars.githubusercontent.com/u/9387114?s=60&v=4" role="presentation" alt="">
</div>

Errors

When the plugin detects errors, i.e. an incorreclty formatted a11y-image element, it will render a red fat error instead of an image.

remark-a11y-image Error: The markdown is not correctly formatted.

License

MIT