HTML Plugins for Eleventy

Eleventy allows for step-by-step conversion of existing websites comprising of static HTML files to Markdown, Liquid, and Eleventy. However, the tools it provides for pages (templates) in plain HTML format are rather limited. There are many plugins for markdown-it that can be used to enhance pages by tables of contents, attributes, etc., which are missing for HTML templates.

The website H. Wagner’s VB.Any consisted of static complete HTML documents that were edited by hand. These pages make heavy use of semantic HTML markup, such as abbr, b, and cite, which would have to be retained even when converting the pages to Markdown. Therefore, the decision was made to keep these pages in HTML format and use them as Eleventy templates.

The HTML head section, the navigation, and the page footer were removed from the individual HTML files by a Node.js script using regular expressions. During this conversion, page metadata (date of creation and last modification, title, description, etc.) was extracted and converted to Eleventy front matter in YAML format. The resulting partial HTML files, mainly consisting of everything inside the main element, were processed by Eleventy and converted to output HTML pages using the project’s Liquid layout:

---
title: Sample Page
description: This is a sample page.
---
<h1>Sample Page</h1>
<p>Sample paragraph.</p>

Source code listings enclosed in code elements were augmented by a language-vb (for Classic Visual Basic) HTML class, but syntax highlighting did not work out of the box. Also, automatic generation of tables of contents based on the page’s heading elements would have been desirable.

These shortcomings were mitigated by writing a set of Eleventy plugins based on the parse5 HTML manipulation library:

HTML Container Plugin

Wraps the contents of HTML containers such as <div class="remark"> into div elements to enable advanced CSS styling using flexbox or grid.

HTML External Links Plugin

Adds target="_blank" and rel="noopener noreferrer" attributes to hyperlinks referencing external websites.

HTML Syntaxhighlight Plugin

Syntax highlighting for HTML source code listings based on the Eleventy Syntax Highlighting Plugin. This plugin allows for highlighting of source code in HTML-based templates without the use of Eleventy shortcodes or filters.

HTML TOC Plugin

Creates an hierarchical table of contents based on headings present in the HTML document and adds it to the document. The plugin retains existing IDs set on the headings and adds IDs based on the heading’s slug to headings without ID.