Skip to content

An extension of PHP League's CommonMark library to enable accessible Heading Permalinks usage.

Notifications You must be signed in to change notification settings

8fold/commonmark-accessible-heading-permalinks

Repository files navigation

8fold Accessible Heading Permalinks for CommonMark

This library is an extension for the CommonMark parser from the PHP League adding accessible heading permalinks inspired by Amber Wilson.

🗒 Note: The HTML rendered on this page most likely doesn't use this approach.

⚠️ Warning: Do NOT use with the heading permalinks extension provided with CommonMark. I'm not sure what will happen; could be nothing, could be a singularity causing event, who knows?

Installation

composer require 8fold/commonmark-accessible-heading-permalinks

Usage

use League\CommonMark\Environment\Environment;
use League\CommonMark\MarkdownConverter;

use League\CommonMark\Extension\CommonMark\CommonMarkCoreExtension;

use Eightfold\CommonMarkAccessibleHeadingPermalink\HeadingPermalinkExtension;

$environment = new Environment();
$environment->addExtension(new CommonMarkCoreExtension());
$environment->addExtension(new HeadingPermalinkExtension());

$converter = new MarkdownConverter($environment);

Then write the markdown as you normally would.

# Hello

This should be an improvement.

Which will output the following (whitespace added for improved readability).

<div is="heading-wrapper">
  <h1 id="hello">Hello</h1>
  <a hreg="#hello">
    <span aria-hidden="true"></span>
    <span>Section titled Hello</span>
  </a>
</div>

Details

The HTML is treated as a whole component. Styling the inner elements can be accomplished by referencing the containing element and using child and sibling selectors.

For example, the second span in the link should be primarily reserved for those using assistive technologies. Therefore, I want it to be off-screen and still read aloud when on the link has focus.

div[is='heading-wrapper'] > a > span:nth-of-type(2) {
  position: absolute;
  left: -999em;
  right: auto;
}

This example uses the solution provided by the United States Web Design System and is not the only method used or available to accomplish similar results.

Other

About

An extension of PHP League's CommonMark library to enable accessible Heading Permalinks usage.

Resources

Code of conduct

Security policy

Stars

Watchers

Forks

Sponsor this project

  •  
  •  

Packages

No packages published

Languages