README

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

• Code of Conduct
• Contributing
• Governance
• Versioning
• Security
• Coding Standards and Style