search

fralau / mkdocs-macros-plugin

Create richer and more beautiful pages in MkDocs, by using variables and calls to macros in the markdown code.
https://mkdocs-macros-plugin.readthedocs.io
Other
321 stars 50 forks source link

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

Closed fralau closed 1 year ago

fralau commented 2 years ago

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 commented 2 years ago

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

fralau commented 2 years ago

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 commented 1 year ago

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