pug-lint-parser
A concrete syntax tree (CST) parser for Pug templates, built for linting and formatting tools. It is the parser behind eslint-plugin-pug-vue.
- Never throws. Input it cannot parse becomes an entry in
errors, and parsing continues on the next line. - Exact source ranges. Every node, attribute, value, shorthand, comma and line has a
[start, end)range: UTF-16 offsets into the text you pass in, so you can slice the source or build a minimal edit without adjusting positions. - Parses a slice in place.
parsePug(text, { start, end })parses onlytext[start, end)(for example the content of a<template lang="pug">block); ranges still refer to the wholetext. - Keeps line endings. LF and CRLF are both handled;
doc.eolis the first line ending found. - No runtime dependencies. ESM only. Node.js
^20.19.0 || ^22.13.0 || >=24.
Usage
js
import { parsePug, walk } from 'pug-lint-parser'
const text = 'ul#list\n li.item(v-for="x in xs" :key="x") {{ x }}\n'
const doc = parsePug(text)
console.log(doc.errors) // []
walk(doc, (node) => {
if (node.type === 'Tag') console.log(node.name?.value ?? 'div', text.slice(...node.range))
})
// ul ul#list
// li li.item(v-for="x in xs" :key="x") {{ x }}API
parsePug(text, options?)→PugDocument.options.start/options.endlimit parsing to that range oftext.walk(doc, visit): callsvisit(node, parent)for every node in document order, including the tags inside tag interpolations (#[…]).fingerprint(doc)→string: a structural summary of the tree (tags and their nesting, class and id sets, attribute counts, the shape of text and interpolation). It ignores whitespace, quoting, attribute order, attribute names and values other than staticclassandid, tag-name casing, text content and the content of code and control heads, sop(class="a b")andp.a.bhave the same fingerprint. The ESLint plugin compares fingerprints to reject fixes that change a template's structure.literalSpans(text, range)→ the ranges of the string and template literals in a JavaScript expression.- Types for every node:
PugDocument,PugNode,Tag,AttributeBlock,Attribute,AttributeValue,Text,Comment,Code,Control,MixinCall,Filter,PugLine,PugParseErrorand more (seesrc/ast.ts).
A PugDocument has children (the tree), errors ({ code, message, offset }), lines (one entry per source line with its indentation range, kind and logical depth), eol and indentUnit.
Unsupported syntax
Some Pug forms are reported with the error code unsupported-syntax, and a few are parsed without an error but differently from Pug. They are listed in docs/unsupported-syntax.md.
License
MIT