Fix page metadata also for gallery examples

[smarie]

          Thanks @smarie! Just to say that `feature/96_97_issues` fixes the issue with the `README.md`!

I do have a follow up question/problem though: I'd like to use the same page setup in my examples.

examples/plot_00_test.py

"""
---
hide:
    - toc
---

Plotting Overview
=================
"""
...

generated/gallery/plot_00_test.md

<!--
 DO NOT EDIT.
 THIS FILE WAS AUTOMATICALLY GENERATED BY mkdocs-gallery.
 TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
 "docs/examples/1_plotting/plot_00_plotting_intro.py"
 LINE NUMBERS ARE GIVEN BELOW.
-->

!!! note

    Click [here](#download_links)
    to download the full example code

---
hide:
    - toc
---

Plotting Overview
=================
....

Unsurprisingly mkdocs renders this incorrectly:

Is there any chance you could pass through headers in the example files too?

Originally posted by @schlegelp in https://github.com/smarie/mkdocs-gallery/issues/96#issuecomment-2329073234

[smarie]

The problem here @schlegelp is that the currently inserted header is quite useful : as you can see in the EXAMPLE_HEADER variable used in the below piece of code, it contains a note with the download link to the example code and optionally binder page. So we can not fix this the same way that I did for the README.md

https://github.com/smarie/mkdocs-gallery/blob/3207db9031e2cd88d94061b4c9d1dd1f2ea55808/src/mkdocs_gallery/gen_single.py#L1163

https://github.com/smarie/mkdocs-gallery/blob/3207db9031e2cd88d94061b4c9d1dd1f2ea55808/src/mkdocs_gallery/gen_single.py#L1270

I see three possibilities:

• ask the mkdocs-material project to support placing the metadata anywhere in the page (not only at the top)
• ask mkdocs-material to provide an API to extract the metadata headers from a page
• try to code the above item ourselves - with no guarantee that the format of the metadata headers will not change in the future. This is why I dont like this idea much, but it can be temporary.

I let you decide which path you prefer, and try ? If you managed to clone the project and "pip install ." works for you, then you are almost set to develop: simply edit the above lines of code to change the contents of md_before and md_after, at least to validate that if md_before was set to empty string, the rest of the expected behaviour you target would work :)

For more comfort (but this is optional), you may wish to create a debug configuration in your IDE, so that you can place breakpoints. Here is a recipe with Pycharm : https://github.com/smarie/mkdocs-gallery/issues/54#issuecomment-1479216910

[schlegelp]

I have no clue how receptive the mkdocs material folks are to accommodate downstream projects? Option 1 could potentially break things if people use ---- somewhere else in their documents.

Option 3 would probably be the path of least resistance. I agree it could potentially be brittle but the header syntax feels pretty mature.

I can see two ways of implementing this:

1. Try to extract headers from the .py file and insert at the beginning of md_before
2. Piggy back on the existing # mkdocs_gallery_... syntax: examples/plot_00_test.py

   """
   Plotting Overview
   =================
   """
   ...  
   # mkdocs_gallery_page_title = "my title"
   # mkdocs_gallery_page_hide_toc = True

Pretty busy at the moment but if I get a chance I will try to have a crack at it!

[smarie]

Nice ideas @schlegelp ! I like option 2, and it can even be made generic with a common prefix (everything after the option prefix would be considered a piece of metadata for mkdocs-material headers).

Ok no worries, let me know when you have the time ! At least doing a "fake" PoC manually and showing the expected result (I remember you mentioned hiding the toc) would be great I think, so that other users/contributors looking at this issue understand the interest of this feature