mkdocs material theme

[drscream]

Provide an update to the latest stable version of mkdocs. This change
require to many modification of an outdates theme, for that reason a new
theme "Material" is included.

The new theme provide extensions to handle notes and other admonitions.
For that reason the class="well" html code is removed and replaced by
the new prefix (extension method).

The logo should no longer be part of the sub-pages or pages because it's
part of the header. This is required to make the documentation more
readable for the user.

Add css code to create grid overview based on the html and markdown
code. Update copyright to the current year (2022).

References: #226

[JMadgwick]

The MkDocs Material "admonitions" for notes look good, but unfortunately the change from using a div to using the non standard !!! indented notation cannot be parsed by pandoc which is used for PDF generation. With this PR the formatting in the PDFs is broken.

This is because Pandoc uses the div to determine the location of the note sections. I don't think this can be converted to use the MkDocs Material notation because these don't use a div at all.

[drscream]

I will have a look to get it working also with pdf creation. I’m sure there will be a solution.

[JMadgwick]

I've had a look and the solution for the existing doc theme is as follows:

Replace the div class of well with card card-body bg-light for all files - this is because the themes are now based on Bootstrap 4 and this introduced a change to how this feature was annotated.

Add the markdown extension md_in_html using this in the yaml config:

markdown_extensions:
    - md_in_html

With this extension the markdown inside the div elements is rendered correctly.

With the Material theme, the note sections can be specified as follows in order to leave the divs for the PDF generation scripts to use:

<div class="note" markdown="1">
!!! note
    Indented note text
</div>

The script will require changes to no longer look at the line which was adding the icon, but it should otherwise work as before.

[drscream]

Well that was basically the reason why I ask if it make sense to work on a more modern theme or not.

Sure it was always possible to make a solution with a existing css change. But the idea was to go into a more modern and maintained theme at all.

[drscream]

You need to add markdown to the div which contains the markdown code.

[JMadgwick]

I noticed a mistake in my brief test and edited the post. Unfortunately GitHub was too slow refreshing. We could keep the existing approach or modernise as explained in the edited post.

[JMadgwick]

I'm happy to add the required commits to this branch to add basic div as required and fix the PDF generation. Probably better I do that as I wrote the PDF Lua filters originally.

Should then by ready for review and merge after some minor linting fixes or rule changes.

[drscream]

I'm happy to add the required commits to this branch to add basic div as required and fix the PDF generation. Probably better I do that as I wrote the PDF Lua filters originally.

Should then by ready for review and merge after some minor linting fixes or rule changes.

Sounds great :-)