🥳 Material for MkDocs 9.2 – Beta #5686
Comments
squidfunk
changed the title
I tried the 9.2 beta on my simple Git Gosling site, and enabled navigation pruning. The beta "feels slower to load new pages" compared to the production deployment, which uses the latest non-beta. To confirm the new beta slowed things down, I had the beta in production for a short while, which still felt slower than normal. I don't know how I can quantify this slowdown, or if there really is a slowdown. Or maybe navagation pruning slows down the instant page loading feature. |
|
@HonkingGoose Thanks for the feedback. That's surprising and "feels slower" is hard to quantify. However, there might always be side effects between features, and given that Material for MkDocs has a gazillion of them, anticipating all possible side effects is quite an impossible task. If you deploy the beta without enabling any new features, does it also "feel slower"? Could you try to quantify the slowness? Does the side load longer? Also, what version did you have in production before? I read that you have instant loading enabled, which got a complete rewrite 4 months ago in 9.1.4. Without knowing exactly what changes you applied, we can only guess – as always 😊 If you find the time, a side-by-side comparison with runnable examples would be amazing. I'm sure we can mitigate the issues that you now observe. Additionally, Beta 1 will ship a 20% smaller JavaScript bundle, so our general expectation is that 9.2.0 will feel faster than before. Furthermore, navigation pruning should not impact instant loading in any way. It should actually even speed it up, because the pages to download are smaller due to reduced navigation. Finally, you should measure if navigation pruning is actually benefiting your site, as it hugely depends on your navigation structure. |
Have you tried measuring the performance via the Network tab in Firefox/Chrome developer tools? |
Production is currently using these dependencies: Select me to see production
|
|
Thanks for the reproductions.
Jup, this is exactly what we need. Some numbers would be amazing, because "feels slow" is not really quantifiable for us. Happy to help, and Material for MkDocs should feel fast at all times, but we need more data 😊 |
I'm unsure if this would be immediately helpful since it's an entirely different project but did a test in a local env using Anecdotally i didn't experience any difference in navigation even on our staging build on vercel. Although I figured a local test would be better to showcase. Page SampleThis is a sample of the page that was loaded and associated navigation strcuture: We are using awesome-pages plugin for our navigation though. Network tab in Chrome9.1.18 Local Build 9.2.0b0 Local Build No Cache 9.1.18 Local Build 9.2.0b0 Local Build |
|
@Valastiri thanks for the benchmarks! What I read from that (no cache case):
That is only relevant during build time, since it assemble your |
|
Yes apologies I forgot to summarize! It does indeed have better performance based on my tests and I couldn't replicate any perceived slowdowns. Great to feature to have looking forward to release! |
|
@squidfunk Excited for the new page Is it possible to use a custom icon? We have a bunch of custom SVG icons that we use in our application and mirror in the user guide. What I'm imaging is passing a relative path to a small SVG file: ---
icon: ../static/icons/icon.svg
---Thanks for the consideration! |
|
@johnthagen yes, of course, just set up additional icons and you're good to go! |
|
@squidfunk Wow, yep! In case it is helpful, I might suggest a small admonition/link back to that page from these pages to help others discover it:
Thank you! ❤️ |
|
@squidfunk Some more feedback, we used to host our custom SVG icons as static files, and we could use them both in the body and page titles so that they would show up at the top of the page next to the title. When we moved to ![][custom_icon]{ width=36 } Title
[custom_icon]: ../../overrides/.icons/custom/icon.svgBut this produces a warning: If we change to - pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
options:
custom_icons:
- overrides/.icons# :custom-icon: TitleThen the page renders properly (the emoji is in the Title block), but the emoji identifier is in the navigation bar: 
Should emoji identifiers be stripped from the navigation bar? |
|
Using the custom icon integration with the
|
|
Thank for the information and tips. One other observation I noticed when refactoring to use custom icons, is that
So that I'm clear, I was trying to use both the new As always, Material for Mkdocs is awesome. Thank you. |
|
@johnthagen you can override the navigation title, removing the icon code from it, and then set the icon via metadata as well – without the typeset plugin, this is likely going to be the best option: ---
title: Document title
icon: material/pencil
---
# :material-pencil: Document title
...I agree that this looks a little redundant, but it allows us to annotate the page with a distinct icon, which we can also use in the new social plugin's cards and other parts of the site, e.g.:
|
|
@squidfunk That worked, thanks! |
|
@squidfunk I think tag styling got broken, but only on individual pages and not on tag index. E.g.
If that would help, I can produce a minimal example for reproduction, optionally in a separate bug report. |
|
@vedranmiletic a reproduction would be great, you can just post it here, thanks! |
|
Working on it. By the way, unrelated, but when I added Running |
|
Interesting, minimal example that enables |
|
@squidfunk Here's a minimal example. Overriding Finally, this is a regression from 9.1.8 and it doesn't have anything to do with the Minimal example: unstyled-tags.tar.gz |
|
Thanks for investigating! If it also happens on 9.1.x, then please create a new issue. This issue is reserved for everything related to the 9.2 and the new beta release. Regarding your other issue:
This is because when you add configuration while MkDocs is running, the |
|
@squidfunk sorry, I might have not been clear enough. The issue with tag display is a regression compared to 9.1.8, i.e. it does not occur on 9.1.8 and it does occur in 9.2.0b0. |
|
Okay thanks, does it also not occur on 9.1.18? 9.1.8 is quite old. |
To save time, I'm going to ask what I am sure @squidfunk will ask, can you provide a minimal reproduction? |
|
Yes, please provide a minimal reproduction. You can attach it here, you don't need to create a new issue for now. |
|
After rebooting my computer, the issue seems to have resolved itself. Sorry for wasting your time. |
|
No worries, I think I know where this is coming from. It should only happen if you add the search plugin during serve mode. If you restart |
|
9.2.0b3 was just released. Upgrade with: |
|
hello! I'm having a weird behavior using navigation.prune, where an internal folder is opened when it's parent folder is selected through the menu. I am attaching a minimal example but I'm unsure as to whether the problem is related to material for mkdocs or awesome-pages, in any case it only started happening after I moved to the beta and used prune (which, by the way, is a life saver) so I decided to post it here under the beta discussion. thanks in advance! |
|
@usulpt we need a reproduction without awesome pages, since we don't have official support for it. Please create a new issue and create a reproduction that does not use awesome pages, so we're sure that the bug is on our side 😊 |
|
I found a workaround using awesome-pages and I tried reproducing the issue without awesome-pages and it works fine. sorry to bring this up, carry on the great work! :) |
|
Perfect! Could you please share a little about the problem with awesome pages and the workaround you found? Other users might be impacted, too, so you will do them a great favor |
|
will do! :) |
|
Update: just to let all of you know, I'm currently doing a deep refactor of the blog plugin to address the remaining issues, primarily remove the limitation that a |
|
@squidfunk thanks for this. I was about to report this issue as well on the nav element being required after beating my head against this in a dockerized build for a few hours. The lack of need to specify nav is one of my favorite features for the more complex docs. I did run into one other behavior and I'm not certain it's expected. Putting under summary section to avoid noise. Please advise if I should open a new discussion or if this is relevant to beta release. details on the blog posts slug issue I've run intoI try to keep my blog very level in url. While I see the ability to set the blog directory as For now I can move this to a new discussion item if the behavior is intentional, but thought I'd mention as it impacts the url structure for adoption for me at least. The posts below are all served with
|
|
@sheldonhull I'm currently rewriting the plugin from the ground up and the navigation issue is already fixed - there are now no limitations to where you place the blog, or whether you specify Regarding the issue with slugs – you should set .
├─ docs/
│ ├─ posts/
│ │ └─ hello-world.md
│ ├─ reference/
│ │ ├─ index.md # example.com/reference/
│ │ ├─ foo.md # example.com/reference/foo/
│ │ └─ bar.md # example.com/reference/bar/
│ ├─ baz.md # example.com/baz/
│ └─ index.md # example.com/
└─ mkdocs.ymlNote that when there's no blog prefix, you must make sure that your slugs don't collide with URLs of other pages. |
|
Additionally, for the sake of completeness: you can organize your posts as you like – everything in the |
|
Thanks a lot for all the work you put in the blog feature, this is so awesome! For me, mkdocs-material now has finally become a real hugo/jekyll alternative. I guess this might be the right issue to mention a few missing translation options for the blog. The docs currently only mention easy translation of these parts: but the following are missing (afaik):
I guess I could just modify the templates, but it doesn't feel right as the other settings are located in the |
|
Those translations are provided as part of localizations: mkdocs-material/src/partials/languages/en.html Lines 31 to 38 in ccc3c44 mkdocs-material/src/partials/languages/en.html Lines 51 to 52 in ccc3c44 You can override them easily, as mentioned in our docs. |
|
Thanks for the links! |
|
Yes, exactly, both options are regarded as content and not part of the site structure. They are also part of the translations, so that we can provide good defaults per language. In German, the default will be "Archiv" and "Kategorien". |
|
Hey! We just deployed using the beta and I think perhaps something related to CSS changed https://datadoghq.dev/integrations-core/
The site should be using our branded purple color but it seems like it is not. Did something change that I missed? |
|
@ofek What did you use before? There were no recent changes from 9.1 to 9.2 that could explain the behavior. Looking at your CSS; it looks like you're coming from an older version. You need to adjust the selector when overriding primary colors. This was changed in 8.5.10 (see diff) which was released 9 months ago. |
|
That was it indeed; thank you and sorry for the noise! |
|
No worries, it was a necessary change to make color customization easier, and there are probably some installations (like yours) out there that need updating. However, we can't do a major release for every little bit of customization we change, or we would be at v237 already 😅 Glad we could sort it out so quickly |
|
Material for MkDocs 9.2.0 was just released! It brings many new capabilities and fixes some long standing bugs. Thank you all for testing the beta releases and for your patience ❤️ |
This is still an issue in the container version of mkdocs (tested today 2023-11-21). version = "9.4.8" (material) |
|
@TimChaubet-I4U Sorry, I don't know what you mean (I haven't skimmed through all comments here and the quote does not provide enough context). If you're referring to #6364, this is fixed on |
With the help of our awesome sponsors, I'm happy to announce that the 'Piri Piri' funding goal has been reached, which means that amongst other awesome features, the built-in blog plugin is finding its way into the community edition!
If you experience any problems, for now, please report them as a comment in this issue.
Installation
Changes
Beta 0
Beta 1
ResizeObserverpolyfill when necessary – 54bef7bArray.flatandArray.flatMappolyfill – b37c668Beta 2
Beta 3
Final
Upgrading
Changes to
mkdocs.ymlNone.
Changes to customizations
If you've customized Material for MkDocs with theme overrides, and added your own partials, you need to update the following partials, as they got updated with new functionality. If you don't update them, you'll not be able to use some of the new features:
footer.htmlheader.htmllanguage.htmlnav-item.htmlnav.htmlsearch.htmltabs-item.htmltabs.htmlYou can check the full list of changes here:
https://github.com/squidfunk/mkdocs-material/pull/5683/files
Closing thoughts
We're super happy to finally give the built-in blog plugin into the hands of all users, so we can improve it even more. Before issuing the final release, we'll take the opportunity to refactor some edges that need a little polishing and incorporate your feedback.
❤️ ❤️ ❤️
Thanks again to all of our awesome sponsors for making our work on this project possible in the first place! Without you, all of those features would not exist. We hope for your continued support, as it allows us to ship more useful and unique features, like for example the latest improved social plugin, which allows to build entirely custom social cards.
The text was updated successfully, but these errors were encountered: