README

Remark accessible link plugin

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

Installation

npm i gridsome-remark-a11y-link --save-dev
# yarn add gridsome-remark-a11y-link --dev

Configuration

mode

You can configure in which way the link should be accessible.

There's two modes:

aria
hidden text within link

The default mode is hidden text within link, as it has wider support.

Remark configuration:

  const remark = require("remark");
  const a11yLink = require("remark-a11y-link");

  const processorWithoutMode = remark().use(a11yLink);

  const processorWithMode = remark().use(a11yLink, {
    mode: "aria",
  });

Gridsome configuration:

module.exports = {
  plugins: [
    {
      use: "@gridsome/source-filesystem",
      options: {
        path: "blog/**/*.md",
        route: "/blog/:year/:month/:day/:slug",
        remark: {
          plugins: [
            ["gridsome-remark-a11y-link"],
          ]
        }
      }
    }
  ]
}

Usage in markdown

The markdown must consist of all the possible attributes (link, text, alt & inline), and you must enclose the markdown in backticks (`).

Format:

`link [LINK] text [TEXT] alt [ALT_TEXT] inline [TRUE|FALSE]`

Examples:

`link https://github.com/Healios/remark-a11y-link text remark-a11y-link alt Navigate to github and read about remark-a11y-link inline true`

or

`link https://github.com/Healios/remark-a11y-link text Navigate to github and read about remark-a11y-link alt inline false`

Output

ARIA

This is how the link should appear on the screen with aria mode:

remark-a11y-link

Hidden text within link

This is how the link should appear on the screen with hidden text within link mode:

remark-a11y-linkNavigate to github and read about remark-a11y-link

Generated HTML

<!-- ARIA mode -->
<a href="https://github.com/Healios/remark-a11y-link" aria-label="Navigate to github and read about remark-a11y-link" style="display: inline !important;">remark-a11y-link</a>

<!-- Text within link mode -->
<a href="https://github.com/Healios/remark-a11y-link" style="display: inline !important;">remark-a11y-link<span style="position: absolute !important; clip: rect(1px, 1px, 1px, 1px); width: 1px !important; height: 1px !important; padding: 0 !important; border: 0 !important; overflow: hidden; white-space: nowrap;">Navigate to github and read about remark-a11y-link</span></a>

Errors

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

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

License

MIT

Usage no npm install needed!