Skip to content
Write contextual headings using <h> in HTML
JavaScript HTML
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
test
.editorconfig
.gitignore
.rollup.js
.tape.js
.travis.yml
CHANGELOG.md
CONTRIBUTING.md
INSTALL.md
LICENSE.md
README.md
package.json

README.md

pHTML H Element pHTML

NPM Version Build Status Support Chat

pHTML H Element lets you use contextual headings in HTML.

<h>Heading</h>
<p>...</p>
<article>
  <h>Heading</h>
  <p>...</p>
  <section>
    <h>X Heading</h>
    <p>...</p>
  </section>
</article>
<article>
  <p>...</p>
  <h>Heading</h>
  <p>...</p>
</article>

<!-- becomes -->

<h role="heading" aria-level="1">Heading</h>
<p>...</p>
<article>
  <h role="heading" aria-level="2">Heading</h>
  <p>...</p>
  <section>
    <h role="heading" aria-level="3">X Heading</h>
    <p>...</p>
  </section>
</article>
<article>
  <p>...</p>
  <h role="heading" aria-level="2">Heading</h>
  <p>...</p>
</article>

Usage

Transform HTML files directly from the command line:

npx phtml source.html output.html -p @phtml/h-element

Node

Add pHTML H Element to your project:

npm install @phtml/h-element --save-dev

Use pHTML H Element to process your HTML:

const phtmlHElement = require('@phtml/h-element');

phtmlHElement.process(YOUR_HTML /*, processOptions, pluginOptions */);

Or use it as a pHTML plugin:

const phtml = require('phtml');
const phtmlHElement = require('@phtml/h-element');

phtml([
  phtmlHElement(/* pluginOptions */)
]).process(YOUR_HTML /*, processOptions */);

pHTML H Element runs in all Node environments, with special instructions for:

Node CLI Eleventy Gulp Grunt

Options

heading

The name option defines the element name transformed into a contextual heading.

phtmlHElement({ heading: 'h1' });
<h1>Heading</h1>
<p>...</p>
<article>
  <h1>Heading</h1>
  <p>...</p>
  <section>
    <h1>X Heading</h1>
    <p>...</p>
  </section>
</article>
<article>
  <p>...</p>
  <h1>Heading</h1>
  <p>...</p>
</article>

<!-- becomes -->

<h1 role="heading" aria-level="1">Heading</h1>
<p>...</p>
<article>
  <h1 role="heading" aria-level="2">Heading</h1>
  <p>...</p>
  <section>
    <h1 role="heading" aria-level="3">X Heading</h1>
    <p>...</p>
  </section>
</article>
<article>
  <p>...</p>
  <h1 role="heading" aria-level="2">Heading</h1>
  <p>...</p>
</article>

headingLevel

The headingLevel option determines whether heading elements should be used and from which level they should begin. By default, they are disabled.

phtmlHElement({ headingLevel: 2, ariaLevel: false });
<!-- becomes -->

<h2>Heading</h2>
<p>...</p>
<article>
  <h3>Heading</h3>
  <p>...</p>
  <section>
    <h4>X Heading</h4>
    <p>...</p>
  </section>
</article>
<article>
  <p>...</p>
  <h3>Heading</h3>
  <p>...</p>
</article>

ariaLevel

The ariaLevel option determines whether the heading role and aria-level attributes should be used and from which level they should begin. By default, they are set to 1.

phtmlHElement({ headingLevel: false, ariaLevel: 2 });
<!-- becomes -->

<h role="heading" aria-level="2">Heading</h>
<p>...</p>
<section>
  <h role="heading" aria-level="3">Heading</h>
  <p>...</p>
  <section>
    <h role="heading" aria-level="4">X Heading</h>
    <p>...</p>
  </section>
</section>
<section>
  <p>...</p>
  <h role="heading" aria-level="3">Heading</h>
  <p>...</p>
</section>

sections

The sections option determines the element names of sectioning tags used to calculate the hierarchical level of heading tags. The default sectioning tags are article, aside, nav, and section.

phtmlHElement({
  sections: [ 'article', 'aside', 'nav' ]
});
<!-- becomes -->

<h role="heading" aria-level="1">Heading</h>
<p>...</p>
<article>
  <h role="heading" aria-level="2">Heading</h>
  <p>...</p>
  <section>
    <h role="heading" aria-level="2">X Heading</h>
    <p>...</p>
  </section>
</article>
<article>
  <p>...</p>
  <h role="heading" aria-level="2">Heading</h>
  <p>...</p>
</article>
You can’t perform that action at this time.