Support MkDocs Material >= 7

[jhkennedy]

mkdocs-material>=7.0 will cause the header to look like:

Edit: Should close this issue before release:

• Finalize mkdocs-material upgrade before release #39

[Jlrine2]

@jhkennedy version 7.1.6 includes some security improvements and doesn't have this issue with regards to format, here is the tea website with mkdocs-material==7.1.6

[jhkennedy]

@Jlrine2 🥳 So I should be able to just restrict to >=7.1.6?

[Jlrine2]

I think so

[jhkennedy]

I'll try it!

[jhkennedy]

@Jlrine2 I'm still seeing it for hyp3-docs: https://jhkennedy.org/hyp3-docs/

Looks like it might be the second (HyP3) logo? I'll have to play more

[jhkennedy]

nope. not that. harumph.

[jhkennedy]

@Jlrine2 if it works for you though we could cut a release and pin lower for hyp3-docs

[reweeden]

This continues to generate pyup and snyk warnings for us in TEA because the pinned version of mkdocs-material has security issues.

[jtherrmann]

With mkdocs-asf-theme pinned to mkdocs-material==9.4.2, everything builds successfully, but the header is still broken in hyp3-docs.

I confirmed that:

• removing the logo: line from hyp3-docs/mkdocs.yml (or specifying an empty logo: line) removes the hyp3 logo as expected, but does not fix the layout
• removing the icon: block removes the github logo, but does not fix the layout
• removing both logo: and icon: blocks makes everything even worse

Also, it's not just the header that's broken. There are also broken elements in the footer, as well as slight style differences in some of the headings (e.g. for the left and right menus), which we may not care about. But the header is the most obvious.

I downloaded all of the HTML/CSS/JS files from the two versions of the hyp3-docs website and confirmed that there are significant differences across multiple files. Copy-pasting some of the CSS from the old version to the new version resulted in slight improvements, but not a fix.

Then I found the mkdocs-material upgrade guide, which lists the differences between each major version. I think we will want to follow this guide starting at Upgrading from 6.x to 7.x and working up to the current major version, 9.x.x.

Edit: Follow the upgrade guide hosted on their website: https://squidfunk.github.io/mkdocs-material/upgrade/

[jtherrmann]

I've started the upgrade on branch https://github.com/ASFHyP3/mkdocs-asf-theme/tree/upgrade-mkdocs-material. So far, I updated the header by starting with the latest upstream version and applying minimal changes (it's possible that I missed some important aspects of our current header). It still doesn't look quite as nice as the current version. Edit: I had to update a CSS class name and now it looks pretty close to the current version.

After we've updated all of the files and have everything looking how we want, we will likely want to be more explicit about tracking differences between our theme and upstream going forward. For example, for each overridden template file, we may want to document which upstream version of the file our version is based on, and what the important differences are. Or, perhaps our commit history should start with the original upstream version of the file, followed by our changes.

Edit: Also, corresponding changes for hyp3-docs are on branch https://github.com/ASFHyP3/hyp3-docs/tree/upgrade-theme.

[jtherrmann]

The footer is proving much more tricky, but I got it pretty close. The main problem is that I can't get the ASF social media icons to display. If we fix that, then we'll want to go back and fine-tune the footer height and color to more closely match the current version.

[jtherrmann]

I went through the contents of mkdocs-asf-theme/asf_theme/main.html and compared it to https://github.com/squidfunk/mkdocs-material/blob/9.4.2/src/templates/base.html and I don't see any obvious updates that need to be made.

[artisticlight]

I needed to use the latest version of mkdocs-material because it supports "MkDocs static i18n plugin" (https://pypi.org/project/mkdocs-static-i18n/). That is what I use to provide multi-lingual support in MkDocs. The version of mkdocs-material supported by asf_theme didn't support the plugin because it was using a old version. I don't know if the work you are currently doing upgrades mkdocs-material. I don't know if tha

…

On Mon, Oct 2, 2023 at 11:40 AM Jake Herrmann ***@***.***> wrote: I went through the contents of mkdocs-asf-theme/asf_theme/main.html and compared it to https://github.com/squidfunk/mkdocs-material/blob/9.4.2/src/templates/base.html and I don't see any obvious updates that need to be made. — Reply to this email directly, view it on GitHub <#27 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJG6H6BAOPOMEHSHZRQNI3X5MDA5AVCNFSM4YR4MBCKU5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TCNZUGM2TMNBTHE2Q> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

-- Andrew Anderson Alaska Satellite Facility 513 762-9900

[jtherrmann]

@artisticlight Yes, we are in the process of upgrading mkdocs-material.

[artisticlight]

Great. Thanks.

…

On Mon, Oct 2, 2023 at 12:24 PM Jake Herrmann ***@***.***> wrote: @artisticlight <https://github.com/artisticlight> Yes, we are in the process of upgrading mkdocs-material. — Reply to this email directly, view it on GitHub <#27 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJG6H3F4AKGQSJ73AGUMJ3X5MIFVAVCNFSM4YR4MBCKU5DIOJSWCZC7NNSXTN2JONZXKZKDN5WW2ZLOOQ5TCNZUGM3DEMZXGY2Q> . You are receiving this because you were mentioned.Message ID: ***@***.***>

-- Andrew Anderson Alaska Satellite Facility 513 762-9900

[jtherrmann]

Remaining TODOs have been moved to #39 which should be closed before closing this issue.

[jhkennedy]

@reweeden @artisticlight @Alex-Lewandowski we've released v0.3.0 of this theme that works with mkdocs 9.4.2+ at least for HyP3 Docs. The release notes should let you know what changes you need to make to upgrade.

@artisticlight feel free to open PRs to make the changes you need to support multi-languages and we can release subsequent versions for that.