Expose _useHtmlParser2 as a proper option

[voithos]

I'd like to configure Cheerio to use htmlparser2 internally since it works better with the template code I'm trying to parse, but I don't want to use xmlMode as that causes other problems. I found that there's a hidden _useHtmlParser2 option that you can pass into the configuration, which works, but seems a bit sketchy. Would it be possible to make this into a real option?

Alternatively, I saw elsewhere in the issue tracker that the future-proof way to do this is:

const dom = htmlparser2.parseDOM(file.contents, options)
const $ = cheerio.load(dom)

Which is fine, if that's the case - just would like confirmation that this is the recommended approach, and that there isn't a desire to expose useHtmlParser2.

[fb55]

I do think we should make this a documented option, and ideally drop the underscore in front of the name.

[matthewmueller]

@fb55 I think you're right that passing the DOM tree directly into cheerio is the way to go.

Suggested Solution

1. Make loading separate parsers slightly easier

Instead of:

const dom = htmlparser2.parseDOM(file.contents, options)
const $ = cheerio.load(dom)

// or

const dom = parse5.parse(content, {
    treeAdapter: htmlparser2Adapter,
    sourceCodeLocationInfo: options.sourceCodeLocationInfo,
  });
const $ = cheerio.load(dom)

It's something like:

const parse5 = require("cheerio/parse5")
const htmlparser2 = require("cheerio/htmlparser2")
cheerio.load(htmlparser2("<h2>hi world</h2>"))
cheerio.load(parse5("<h2>hi world</h2>"))

By default cheerio.load("<h2>hi world</h2>") uses parse5.

We'd also need to document this, since that's part of this issue. @voithos wasn't sure if this was the recommended approach.

2. Remove _useHtmlParser2 altogether

_useHtmlParser2 or useHtmlParser2 both seem a bit strange to me. I don't think we should bake in switches like this. I think instead we say we support any htmlparser2 AST. If you don't want to use parse5, you can use cheerio/htmlparser2 or bring in your own.

We could either keep this switch (undocumented) for 1.0.0 or choose to remove it and break folks. Since 1.0.0 is a major change, I think we're allowed to break things. I don't have strong opinions on this though.

3. Remove { xml: true }?

cheerio.load("<h2>hi world</h2>", { xml: true })

I think this option is only relevant with htmlparser2. We could adjust it to:

const ast = htmlparser2("<h2>hi world</h2>", { xml: true })
const $ = cheerio.load(ast)

---

🙏 Really curious to hear everyone's thoughts!