Apex Inline Attribute Lists Update

I’m excited to share that Apex version 0.1.41 has comprehensive support for Inline Attribute Lists (IALs), including inline IALs for span-level elements, key-value pairs, and Attribute List Definitions (ALDs). This brings Apex’s IAL support to full feature parity with Kramdown.

In case you haven’t been keeping up, Apex is my universal Markdown processor project. The goal is to create one Markdown processor that incorporates all the best features from other Markdown processors, like Pandooc, Kramdown, Maruku, MultiMarkdown, and more. One processor to rule them all. Learn more on the wiki.

What Are IALs?

Inline Attribute Lists are a Kramdown extension (inspired by Maruku) that let you add HTML attributes (IDs, classes, and custom key-value pairs) directly to Markdown elements. Instead of dropping into raw HTML every time you need to add a class or ID, you can use a simple {: attributes} syntax.

For block-level elements, IALs go on the line immediately after:

# My Heading
{: #section-1 .highlight}

This paragraph has custom attributes.
{: .important .note title="Important Note"}

For inline elements, IALs appear right after the element within the paragraph:

Here's a [styled link](https://example.com){:.button} with a class.

This has **bold text**{:.bold-style} and *italic text*{:.italic-style}.

What’s New

Inline IAL Support

Previously, IALs only worked for block-level elements. Now you can apply attributes to links, images, emphasis, strong text, and code spans—all inline within your paragraphs.

Here's a [button-style link](url){:.btn .btn-primary} that looks great.

You can even style **bold**{:.highlight} and *italic*{:.accent} text separately.

Code spans like `example`{:.code-inline} can have classes too.

Key-Value Pairs

Beyond IDs and classes, you can now add any custom HTML attributes using key-value pairs:

Paragraph with custom attributes.
{: title="Tooltip Text" lang="en" data-id="123"}

[External Link](https://example.com){:rel="nofollow" target="_blank"}

Attributes support quoted values (single or double quotes) and unquoted values for simple cases.

Attribute List Definitions (ALDs)

ALDs let you define reusable attribute sets and reference them multiple times. This is perfect for maintaining consistent styling across your document:

# Header 1
{:section-heading}

# Header 2
{:section-heading}

# Header 3
{:section-heading}

{:section-heading: #main .large .bold lang="en"}

All three headers in the example above get the same set of attributes from the ALD definition on the last line. Much cleaner than repeating attributes everywhere!

Nested Elements

One of the trickier features I implemented is support for nested inline elements with IALs:

**Bold text with *italic*{:.nested-italic} inside**{:.bold-wrapper}

Both the italic and bold elements get their respective classes, even when nested.

How It Works

The implementation uses element indexing to correctly match attributes to elements, even when multiple elements share the same content (like two links with the same URL). This ensures that each element gets the right attributes based on its position in the document.

For inline elements, the processing is recursive, so it handles nested structures correctly. The IAL syntax is extracted from the text nodes and attributes are attached to the corresponding AST nodes before HTML rendering.

Usage

IALs are available in Kramdown and unified modes. In unified mode (the default), they’re enabled automatically. To use Kramdown mode:

apex document.md --mode kramdown

Complete Documentation

I’ve created comprehensive documentation for IALs:

Inline Attribute Lists Guide - Complete user guide with examples
Syntax Reference - Quick reference in the syntax docs

The documentation covers all the edge cases, shows examples for every element type, and explains both block-level and inline IAL syntax in detail.

Try It Out

Grab the latest version of Apex and start adding attributes to your Markdown! Homebrew is updated, just follow the Installation instructions in the README. See the release notes for the latest details.

Whether you’re styling links, adding IDs for anchor navigation, or using ALDs to maintain consistent styling, IALs make it easy to add HTML attributes without leaving the comfort of Markdown syntax.

apex, html, markdown