macro_info() generates its own h1 heading and may cause a confusion in the TOC

[fralau]

Just adding this in case someone stumbles across this in the future as I was debugging it for a colleague :) macros_info() generates its own h1 heading and will lead to the same behavior when there's another h1 heading in the file.

I'm fairly sure https://github.com/fralau/mkdocs_macros_plugin/blob/master/test/module_dir/docs/environment.md would also be affected if run with material. Not really an issue as no one will have that in production but just in case people get confused.

Originally posted by @nejch in https://github.com/fralau/mkdocs_macros_plugin/issues/122#issuecomment-1031850986

[fralau]

I plan to downgrade the macro_info() markdown header to second level (corresponding to h2)

[fralau]

This raises another issue: in order not to change implementation too much, I would like to allow the user to give an optional argument macro_info(3) which would require to "demote" or "promote" the headers (i.e. make all headers of level 2 to 3, etc.).

This is a fairly obvious and mundane requirement for text management, but I have not seen any implementation so far in Python. The only tool that has done this is pandoc shift heading level argument.

If anyone knows a solution for that?

[fralau]

For the time being, we will just demote the titles by one level (main title is level 2).