`tree.options` meaning and use cases

[andreyvolokitin]

Docs say they are options to process HTML. Also, I found some undocumented use cases:

• tree.options.from: what is it for and where it gets defined?
• other stuff
• maybe I missed something else?

I assume you can put arbitrary properties inside tree.options and then somehow use them. So in general tree.options contains options for the currently processed piece of HTML.

But when we have a "subtree" it can be lacking options property, while "supertree" has it (i.e. when using extend/include plugin), and in certain cases it can break things. To fix this I'm considering copying tree.options of supertree and assign it to the subtree, but I am not sure if I can do that with all these custom properties within tree.options. And I am not sure if it is "ideologically right": it seems that options of supertree should naturally "propagate" to the subtree (if subtree needs to be created i.e. when using include), but on the other hand, I am very not sure, especially considering tree.options.from property, because it looks like path-related, and in case of super- and subtree it probably should differ because super- and subtree represent two different files

[Michael Ciniawsky]

posthtml(plugins).process(html, options) => options === tree.options

const plugin = (options) => {
  return function name (tree) {
     const { from } = tree.options
    
     // ...
  }
}

const plugin = (options) => {
  return function name (tree) {
     const { options } = tree
     const { plugins } = tree.processor

     ...

     if (node.attrs.src) {
       readFile(`${dirname(options.from)}/${node.attrs.src}`)
         .then((file) => posthtml(plugins).process(file, options))
         .then(({ tree }) => // subtree with it's own tree.options... )
     }
    
     ...
  }
}

You can assign them to a subtree 'manually' aswell, nothing wrong with that in general (if actually needed...) or use posthtml.process() inside your plugin with plugin.options && tree.options merged/applied/used as you see fit for your use case (e.g loading and processing (additional) files).

[Michael Ciniawsky]

The 'other stuff' point in your comment I personally wouldn't recommend to use at all (in practice). (It's overriding posthtml-render options, which can be quite confusing and break easily for others, if more then one plugin would override the render options. => Don't do that... :))

In theory you can pass any prop to process(html, { custom: ... }), but using plugin options is clearly the saner approach 😛

[andreyvolokitin]

So tree.options are general postHTML options, and plugin.options are specific plugin options. I still not getting tree.options.from property: is it defined as global general postHTML option and intended to be used for all processing trees/files?

[Michael Ciniawsky]

|– src
| |– components
| | |– file.html
| |– index.html

//  e.g a gulp plugin
const middleware = (file, src) => {
   // plugins like poshtml-include can default to tree.options.from
   // and import files relative to the currently processed file ('path/to/index.html')
   // e.g `<import src="./components/file.html"></import>`
   return posthtml(plugins).process(src, { from: file.dirname })...
}

[Michael Ciniawsky]

plugin.options (e.g options.from) > tree.options (e.g tree.options.from) > process.cwd() > Error

[Michael Ciniawsky]

It provides defaults for the common use case(s), where the file path of the processed file is needed (e.g posthtml-include)