Publican v0.5.0 update

Publican v0.5.0 was released on January 28, 2025.

There are no breaking changes, but additional configuration options have been added for heading links and in-page navigation menus.

Omit heading links #

By default, Publican makes your content headings linkable so:

<h2>My heading</h2>

is transformed to (carriage returns added for clarity):

<h2 id="my-heading" tabindex="-1">
  My heading
  <a href="#my-heading" class="headlink">#</a>
</h2>

#my-heading is then available as a link target.

This works well most of the time … unless a title is already inside a link! It results in invalid link nesting, e.g.

<a href="/page/">
  <h2 id="my-heading" tabindex="-1">
    My heading
    <a href="#my-heading" class="headlink">#</a>
  </h2>
</a>

A new Publican option allows you to omit the # link when a heading tag contains a specific string (the default is nolink):

publican.config.js excerpt

// omit link from heading
publican.config.headingAnchor.nolink = 'nolink';

Therefore:

<h2 class="nolink">My heading</h2>
<!-- OR -->
<h2 data-nolink>My heading</h2>

is transformed to HTML without a link:

<h2 id="my-heading" tabindex="-1" class="nolink">My heading</h2>

Heading IDs are retained #

Publican no longer rewrites heading IDs. Therefore:

<h2 id="myh2">My heading</h2>

keeps its ID:

<h2 id="myh2" tabindex="-1">
  My heading
  <a href="#myh2" class="headlink">#</a>
</h2>

Omit from in-page menus #

The code <nav-heading></nav-heading> can be placed in any content or template file to show a nested menu of content heading links. A new Publican option allows you to omit a heading from this menu when its tag contains a specific string (the default is nomenu):

publican.config.js excerpt

// omit heading from menu
publican.config.headingAnchor.nomenu = 'nomenu';

For example, the following headings:

<h2 class="nomenu">Heading 1</h2>
<h2 class="nolink">Heading 2</h2>
<h2 data-nolink-nomenu>Heading 3</h2>

are transformed to:

<h2 id="heading1" tabindex="-1" class="nomenu">Heading 1 <a href="#heading1" class="headlink">#</a></h2>
<h2 id="heading2" tabindex="-1" class="nolink">Heading 2</h2>
<h2 data-nolink-nomenu>Heading 3</h2>

and the <nav-heading> block only shows Heading 2:

<nav-heading>
  <nav class="contents">
    <ol>
      <li><a href="#heading2" class="head-h2">Heading 2</a><li>
    </ol>
  </nav>
</nav-heading>

Get started #

The Publican documentation provides a quick start guide, a detailed set-up guide, API references, and common recipes you can use and adapt for your own projects.

• Get started
• Donate