v1.3.0 vento utilities

What's Changed

• Release v1.3.0: Add Vento TOC and heading anchor processors by @RickCogley in #4

New Contributors

• @RickCogley made their first contribution in #4

Full Changelog: v1.2.1...v1.3.0

Summary

This release adds comprehensive table of contents (TOC) and heading anchor support for pure Vento (.vto) pages, matching the
functionality that markdown-it plugins provide for markdown pages.

Added

New Processors for Vento Pages

• ventoHeadingAnchors - Add ID attributes and anchor links to headings in Vento-rendered pages

  • Automatic unique slug generation with collision prevention
  • Configurable heading levels (min/max) and anchor positioning
  • Matches markdown-it-toc-done-right behavior by default
  • Supports containerSelector option to limit scope to main content

• ventoTOC - Generate hierarchical table of contents from headings in Vento pages

  • Builds nested TOC tree structure stored in page.data.toc
  • Generates full URLs with anchors for each heading
  • Supports containerSelector option for scoped extraction

• ventoTOCInject - Inject TOC HTML into rendered pages at marker position

  • Works around Lume's build order limitation (processors run after layouts)
  • Finds <!-- VENTO-TOC-INJECTION-POINT: --> marker and replaces with TOC HTML
  • Respects show_toc frontmatter setting

New Utility Modules

• utils/slugify.ts - URL-safe slug generation from text
• utils/headings.ts - Heading extraction and manipulation utilities
• types/vento_toc.ts - TypeScript types for TOC functionality

Changed

• ventoHeadingAnchors default behavior now matches markdown-it style:
  • anchorPosition: "inside" (anchor wraps heading text)
  • anchorSymbol: "" (empty - use CSS ::before for icon)
  • Ensures consistent appearance between Vento and markdown pages

Fixed

• Prevent duplicate anchors/TOC on markdown pages by skipping pages with "md" in templateEngine chain
• Only pure Vento pages (templateEngine: ["vto"]) are now processed by Vento processors

Documentation

• Comprehensive documentation for all three Vento TOC processors in README
• Complete workflow examples showing processor ordering
• CSS styling examples for anchor links
• Explanation of Lume build order and HTML injection solution
• New RELEASE_GUIDE.md with step-by-step release process

Installation

{
  "imports": {
    "lume/": "https://deno.land/x/[email protected]/",
    "hibana/": "https://deno.land/x/[email protected]/"
  }
}

Or from GitHub:

{
  "imports": {
    "hibana/": "https://raw.githubusercontent.com/RickCogley/hibana/v1.3.0/"
  }
}

Quick Start

import lume from "lume/mod.ts";
import { ventoHeadingAnchors, ventoTOC, ventoTOCInject } from "hibana/mod.ts";

const site = lume();

// 1. Add IDs and anchors to headings
site.process([".html"], ventoHeadingAnchors({
  level: 2,
  maxLevel: 4,
  containerSelector: "article",
}));

// 2. Generate TOC data structure
site.process([".html"], ventoTOC({
  level: 2,
  maxLevel: 4,
  containerSelector: "article",
}));

// 3. Inject TOC HTML at marker
site.process([".html"], ventoTOCInject());

export default site;

See the https://github.com/RickCogley/hibana#ventoheadinganchors for more details.