🥳 Material for MkDocs 9.2 – Beta

squidfunk commented 1 year ago

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

pip install mkdocs-material==9.2.0b3

Note – This is a beta release, so please test thoroughly before deploying to production.

Changes

Beta 0

[x] Added blogging support via built-in blog plugin
[x] Added Chinese language support to built-in search plugin
[x] Added support for annotations (outside of code blocks)
[x] Added support for navigation icons
[x] Added support for navigation pruning
[x] Added support for navigation status
[x] Added support for customizing site icons
[x] Improved rendering of (code) annotation markers
[x] Improved print styles for (code) annotations
[x] Improved customizability of navigation tabs
[x] Removed Universal Analytics integration
[x] Removed ancient polyfills to reduce size of bundled JavaScript by 20%

Beta 1

[x] Automatically download ResizeObserver polyfill when necessary – 54bef7bfe
[x] Removed necessity for Array.flat and Array.flatMap polyfill – b37c668a9
[x] Fixed announcement bar button being visible when JavaScript is not available – 320c85256
[x] Added support for customizing (code) annotation icons – f64d8658d
[x] Added focus outline to admonitions and details – 3e34f6c72

Beta 2

[x] Fixed rendering of tags when announcement bar is present – ef448ed94
[x] Improved plugin inter-op with external tools like mike – ab178b2bc221603321bfdbf88ea5baa347d1fd63
[x] Updated MkDocs to 1.5.0 – 571f12978

Beta 3

[x] Added support for adding date of last update to blog posts
[x] Fixed #5599: Insufficient contrast for default link color

Final

[x] Fixed #5826: Blog post drafts with tags show up in tags index – https://github.com/squidfunk/mkdocs-material/commit/15c024cbbfd1ed747df1ca20a81c8b2860c7da8c
[x] Tags index renders links to excluded pages – https://github.com/squidfunk/mkdocs-material/commit/15c024cbbfd1ed747df1ca20a81c8b2860c7da8c
[x] Switched info plugin to importlib to mitigate deprecations – 0be617276
[x] Automatically focus and bring up keyboard on touch devices – 50f455ec0
[x] Added prompt for bug report name to info plugin – 554976f90
[x] Added Luxembourgish translations – 245278b7

Upgrading

Changes to `mkdocs.yml`

None.

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:

You 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.

HonkingGoose commented 1 year ago

Added support for navigation pruning

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.

squidfunk commented 1 year ago

@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.

vedranmiletic commented 1 year ago

I don't know how I can quantify this slowdown, or if there really is a slowdown.

Have you tried measuring the performance via the Network tab in Firefox/Chrome developer tools?

HonkingGoose commented 1 year ago

@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 😊

Production is currently using these dependencies:

mkdocs-material==9.1.18
mkdocs==1.4.3

Select me to see production mkdocs.yml file

```yaml # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json site_name: Git Gosling strict: true repo_name: HonkingGoose/git-gosling repo_url: https://github.com/HonkingGoose/git-gosling edit_uri: edit/main/docs/ theme: name: material icon: repo: fontawesome/brands/github features: - navigation.top - navigation.instant - toc.integrate - toc.follow - content.action.edit - navigation.footer palette: - media: "(prefers-color-scheme: light)" scheme: default primary: indigo accent: indigo toggle: icon: material/weather-night name: Switch to dark mode - media: "(prefers-color-scheme: dark)" scheme: slate primary: light blue accent: light blue toggle: icon: material/weather-sunny name: Switch to light mode markdown_extensions: - admonition - pymdownx.superfences - pymdownx.highlight - abbr - pymdownx.snippets: auto_append: - includes/abbreviations.md nav: - Home: "index.md" - Git Basics: - "git_basics/short_introduction_to_git.md" - Getting Started: - "getting_started/conventions.md" - "getting_started/installing_git.md" - "getting_started/create_a_github_account.md" - "getting_started/configuring_git.md" - "getting_started/getting_help_with_git.md" - The Nano text editor: - "the_nano_text_editor/introduction_to_the_nano_text_editor.md" - Git Sandbox: - "git_sandbox/setup_your_git_sandbox.md" - "git_sandbox/shell_expansion.md" - "git_sandbox/explore_your_git_sandbox.md" - "git_sandbox/introduction_to_git_status.md" - "git_sandbox/create_a_new_file_and_track_it.md" - "git_sandbox/making_your_first_commit.md" - "git_sandbox/add_extra_lines_to_file.md" - "git_sandbox/use_git_restore_to_undo_things.md" - "git_sandbox/create_a_new_branch.md" - "git_sandbox/switching_between_branches.md" - "git_sandbox/your_first_merge.md" - "git_sandbox/create_your_first_github_repo.md" - "git_sandbox/editing_a_file_on_github.md" - "git_sandbox/merge_pull_request.md" - "git_sandbox/fetching_changes_merging_git_pull.md" - "git_sandbox/check_the_repository_history_with_git_log.md" - Recommendations: - "recommendations/use_a_gitignore_file.md" - "recommendations/split_up_your_commits.md" - "recommendations/write_good_commit_messages.md" - "recommendations/git_aliases.md" - "recommendations/use_a_linter.md" - "recommendations/dealing_with_merges.md" - "recommendations/use_a_dependency_bot.md" - "recommendations/testing_and_github_actions.md" - Advanced Topics: - "advanced_topics/working_with_large_files.md" - "advanced_topics/advanced_git_configuration.md" - "advanced_topics/contribute_to_a_project_by_forking.md" - "advanced_topics/clean_up_your_git_history.md" - "advanced_topics/use_git_bisect_to_find_bugs.md" - "advanced_topics/github_cli.md" - Further Resources: - "further_resources/recommended_reading.md" - License: "license.md" ```

I created three branches on my git-gosling repository:

reproduction/current-production-frozen-branch, this is my current production site with mkdocs-material==9.1.18
reproduction/material-for-mkdocs-beta-nine-two where I only upgrade to 9.2.0b0
reproduction/upgrade-and-navigation-pruning with the upgrade to 9.2.0b0 plus enabling navigation pruning

The easiest way to test is to use GitHub Codespaces or Gitpod, or you may use a local environment.

Run make to install the dependencies, then after run make serve to get the preview site. You may also combine both steps with make && make serve.

squidfunk commented 1 year ago

Thanks for the reproductions.

Have you tried measuring the performance via the Network tab in Firefox/Chrome developer tools?

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 😊

Valastiri commented 1 year ago

Thanks for the reproductions.

Have you tried measuring the performance via the Network tab in Firefox/Chrome developer tools?

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 9.1.18 and 9.2.0b0 with network tab just as a sanity check.

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.

Local System

W10
Python 3.10.0

requirements.txt

mkdocs-material==9.2.0b0 # or set to whatever is required for build
mkdocs-awesome-pages-plugin
mkdocs-git-revision-date-localized-plugin
mkdocs-redirects
mkdocs-embed-external-markdown
mkdocs-video
mkdocs-glightbox
pillow
cairosvg
urllib3<2.0

Page Sample

This 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 Chrome

9.1.18 Local Build reg-speed

9.2.0b0 Local Build beta-speed

No Cache

9.1.18 Local Build reg-nch-speed

9.2.0b0 Local Build beta--nch-speed

squidfunk commented 1 year ago

@Valastiri thanks for the benchmarks! What I read from that (no cache case):

DOMContentLoaded is faster: 343ms -> 317ms (-8%)
Load is faster: 493ms -> 417ms (-16%)

We are using awesome-pages plugin for our navigation though.

That is only relevant during build time, since it assemble your nav entry automatically, but shouldn't have any penalty when navigating in the browser.

Valastiri commented 1 year ago

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!

johnthagen commented 1 year ago

@squidfunk Excited for the new page icon support.

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!

squidfunk commented 1 year ago

@johnthagen yes, of course, just set up additional icons and you're good to go!

johnthagen commented 1 year ago

@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! ❤️

johnthagen commented 1 year ago

@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 overrides, we to change the image path from a path to a static folder within docs to the new overrides:

![][custom_icon]{ width=36 } Title

[custom_icon]: ../../overrides/.icons/custom/icon.svg

But this produces a warning:

WARNING  -  Documentation file 'pages/page.md' contains a link to '../overrides/.icons/custom/icon.svg' which is not found in the documentation files.

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: Title

Then 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?

squidfunk commented 1 year ago

Using the custom icon integration with the :icon-name: shortcode is the way to go. Regarding icons not showing up in the navigation, you currently have two options:

If you want to use titles with arbitrary placed icons and formatting, the built-in typeset plugin is what you're looking for
Otherwise, you can use the regular page icon integration, which will place the icon left of the title

johnthagen commented 1 year ago

Thank for the information and tips.

One other observation I noticed when refactoring to use custom icons, is that :icon-name:'s are stripped from the right hand side table of contents navigation, which is nice, as they can be used within ## section headings without cluttering the table of contents.

Otherwise, you can use the regular page icon integration, which will place the icon left of the title

So that I'm clear, I was trying to use both the new icon: integration and also show the user the icon in the title heading in the page itself, without that :...: showing up in the left side navigation. I can totally understand why this isn't supported out of the box (looks like maybe with typeset in insiders), but I just wanted to make sure I was explaining clearly what I was trying to do.

As always, Material for Mkdocs is awesome. Thank you.

squidfunk commented 1 year ago

@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.:

diagrams

johnthagen commented 1 year ago

@squidfunk That worked, thanks!

vedranmiletic commented 1 year ago

@squidfunk I think tag styling got broken, but only on individual pages and not on tag index. E.g.

page with tags (no gray background): https://gaseri.org/en/blog/2023-06-10-should-i-do-a-phd/
tag index (gray background as before): https://gaseri.org/en/blog/tags/

If that would help, I can produce a minimal example for reproduction, optionally in a separate bug report.

squidfunk commented 1 year ago

@vedranmiletic a reproduction would be great, you can just post it here, thanks!

vedranmiletic commented 1 year ago

Working on it. By the way, unrelated, but when I added - blog under plugins: while mkdocs serve is runing, I got:

INFO     -  [16:11:00] Detected file changes
INFO     -  Building documentation...
Traceback (most recent call last):
  File "/home/vedranm/software/mkdocs-venv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/mkdocs/__main__.py", line 234, in serve_command
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 116, in serve
    server.serve()
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/mkdocs/livereload/__init__.py", line 162, in serve
    self._build_loop()
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/mkdocs/livereload/__init__.py", line 184, in _build_loop
    func()
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 76, in builder
    build(config, live_server=live_server, dirty=dirty)
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/mkdocs/commands/build.py", line 270, in build
    config = config.plugins.run_event('config', config)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/mkdocs/plugins.py", line 520, in run_event
    result = method(item, **kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^
  File "/home/vedranm/software/mkdocs-venv/lib/python3.11/site-packages/material/plugins/blog/plugin.py", line 128, in on_config
    if self.is_serve and self.config.draft_on_serve:
       ^^^^^^^^^^^^^
AttributeError: 'BlogPlugin' object has no attribute 'is_serve'. Did you mean: 'on_serve'?

Running mkdocs serve afterwards works fine.

vedranmiletic commented 1 year ago

Interesting, minimal example that enables blog plugin doesn't fail. I will need to dig deeper to find out what combination of plugins/features results in this, but for now I noticed that wrongly styled tags use md-tagmaterial/close class, while correctly styled tags use md-tag.

vedranmiletic commented 1 year ago

@squidfunk Here's a minimal example. Overriding announce block via custom_dir and enabling announce.dismiss feature causes the issue with tags; other features and plugins don't matter. I checked and, to the best of my knowledge, you didn't change anything related to the main.html template that would require the changes to the overrides.

Finally, this is a regression from 9.1.8 and it doesn't have anything to do with the blog plugin. (The other issue with blog plugin and serve I described two comments above still stands, of course.)

Minimal example: unstyled-tags.tar.gz

squidfunk commented 1 year ago

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:

but when I added - blog under plugins: while mkdocs serve is runing, I got:

This is because when you add configuration while MkDocs is running, the on_startup hook in the plugin is not executed, which is the only place to detect whether you're serving or not before doing a full build. Thus, it is nothing we can fix, and the issue disappears when the server is restarted. You can raise this to the maintainers of MkDocs if you want.

vedranmiletic commented 1 year ago

@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.

squidfunk commented 1 year ago

Okay thanks, does it also not occur on 9.1.18? 9.1.8 is quite old.

vedranmiletic commented 1 year ago

@squidfunk apologies, a typo on my side the whole time. I have separate stable and beta virtual environments, and stable is obviously using the latest stable, which is 9.1.18 and not 9.1.8. So, to finally clarify, 9.1.18 does not have the issue I described, while 9.2.0b0 does.

squidfunk commented 1 year ago

Perfect, thanks for clarifying! I'll look into it.

squidfunk commented 1 year ago

Beta 1 has been released, instructions have been updated.

squidfunk commented 1 year ago

@vedranmiletic thanks for the excellent reproduction! Fixed in ef448ed94. It'll be part of the Beta 2. If you need it now, you can copy the tags template and add it to your overrides as a temporary measure.

vedranmiletic commented 1 year ago

@squidfunk Wow, that was fast! Thank you.

ofek commented 1 year ago

I'm getting the same error with mike:

$ mike deploy --config-file mkdocs.insiders.yml --update-aliases dev
error: 'BlogPlugin' object has no attribute 'is_serve'

squidfunk commented 1 year ago

@ofek thanks for reporting. Does it also happen if you use mkdocs gh-deploy? It might be related to mike.

ofek commented 1 year ago

No it does not, I just tested. How would you recommend I write the bug report? I'm not sure what part I should say is broken.

ofek commented 1 year ago

I was able to see the full traceback with the --debug flag:

cmd [1] | mike --debug deploy --config-file mkdocs.insiders.yml --update-aliases dev
Traceback (most recent call last):
  File "C:\Users\ofek\AppData\Local\Programs\Python\Python38\lib\runpy.py", line 193, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "C:\Users\ofek\AppData\Local\Programs\Python\Python38\lib\runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "C:\Users\ofek\AppData\Local\hatch\env\virtual\hatch\eof-W-rA\docs\Scripts\mike.exe\__main__.py", line 7, in <module>
  File "C:\Users\ofek\AppData\Local\hatch\env\virtual\hatch\eof-W-rA\docs\lib\site-packages\mike\driver.py", line 364, in main
    return args.func(parser, args)
  File "C:\Users\ofek\AppData\Local\hatch\env\virtual\hatch\eof-W-rA\docs\lib\site-packages\mike\driver.py", line 138, in deploy
    cfg = load_mkdocs_config(args, strict=True)
  File "C:\Users\ofek\AppData\Local\hatch\env\virtual\hatch\eof-W-rA\docs\lib\site-packages\mike\driver.py", line 97, in load_mkdocs_config
    cfg = mkdocs_utils.load_config(args.config_file)
  File "C:\Users\ofek\AppData\Local\hatch\env\virtual\hatch\eof-W-rA\docs\lib\site-packages\mike\mkdocs_utils.py", line 33, in load_config
    return cfg['plugins'].run_event('config', cfg)
  File "C:\Users\ofek\AppData\Local\hatch\env\virtual\hatch\eof-W-rA\docs\lib\site-packages\mkdocs\plugins.py", line 520, in run_event
    result = method(item, **kwargs)
  File "C:\Users\ofek\AppData\Local\hatch\env\virtual\hatch\eof-W-rA\docs\lib\site-packages\material\plugins\blog\plugin.py", line 128, in on_config
    if self.is_serve and self.config.draft_on_serve:
AttributeError: 'BlogPlugin' object has no attribute 'is_serve'

It doesn't look like it's doing anything crazy, are you sure it's a bug there?

ofek commented 1 year ago

Also, I'm not sure if you're aware but when MkDocs loads config it looks like the keys for your plugins are now namespaced (maybe they always were?):

 'plugins': {'git-revision-date-localized': <mkdocs_git_revision_date_localized_plugin.plugin.GitRevisionDateLocalizedPlugin object at 0x000001C75D1A8400>,
             'glightbox': <mkdocs_glightbox.plugin.LightboxPlugin object at 0x000001C75D0D7EB0>,
             'material/blog': <material.plugins.blog.plugin.BlogPlugin object at 0x000001C75D440730>,
             'material/search': <material.plugins.search.plugin.SearchPlugin object at 0x000001C75D0D76A0>,
             'mike': <mike.mkdocs_plugin.MikePlugin object at 0x000001C75D1E12E0>,
             'minify': <mkdocs_minify_plugin.plugin.MinifyPlugin object at 0x000001C75D0E73D0>,
             'mkdocstrings': <mkdocstrings.plugin.MkdocstringsPlugin object at 0x000001C75D37A520>,
             'redirects': <mkdocs_redirects.plugin.RedirectPlugin object at 0x000001C75D37A850>},

squidfunk commented 1 year ago

@ofek raise that issue to mike then. mike likely does not call on_startup and on_shutdown which were introduced in (I think) MkDocs 1.4. And yes, regarding the namespacing, this was also introduced in MkDocs 1.4.1 to allow themes to bundle plugins that have the same names as already existing plugins, e.g. the tags plugin.

We can't merge your PR, since this is an issue with mike, not with MkDocs. It makes no sense for us to build around unsupported behavior in mike, it needs to be fixed upstream.

ofek commented 1 year ago

I can open an issue if you really want me to but it seems a bit odd to me to access a variable when it's possible that it has not been initialized, for example if that file went through static analysis it would fail

ofek commented 1 year ago

Actually it seems the documentation also discourages that https://www.mkdocs.org/dev-guide/plugins/#on_startup

Note that for initializing variables, the __init__ method is still preferred. For initializing per-build variables (and whenever in doubt), use the on_config event.

squidfunk commented 1 year ago

Alright, let's move variable initalizations to __init__ then!

squidfunk commented 1 year ago

Moved all variable initializations to __init__ in ab178b2bc.

Edit: Changes were upstreamed in squidfunk/mkdocs-material-insiders@a04eef0c2 and also applied to Insiders plugins.

mfoulds commented 1 year ago

Hi. I hope this is the right place to raise this problem, and that it's not a duplicate.

I am using v9.2.0b1 and using the blog plugin. When I try to run mkdocs serve I now get error below. The problem occurs even when I disable the blog plugin in mkdocs.yml. It also occurs when using v9.2.0b0. It does not occur under v9.1.19.

I had been using 9.2.0b0 since 10-Jul-23 and did not have this problem until yesterday. I'm not sure why it started today. I am running mkdocs serve within a docker container, and I haven't made any changes to the image for a while.

Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mkdocs/__main__.py", line 270, in serve_command
    serve.serve(**kwargs)
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 98, in serve
    builder(config)
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/serve.py", line 79, in builder
    build(config, live_server=None if is_clean else server, dirty=is_dirty)
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/build.py", line 340, in build
    _build_theme_template(template, env, files, config, nav)
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/build.py", line 110, in _build_theme_template
    output = _build_template(template_name, template, files, config, nav)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/mkdocs/commands/build.py", line 89, in _build_template
    output = template.render(context)
             ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/jinja2/environment.py", line 1301, in render
    self.environment.handle_exception()
  File "/usr/local/lib/python3.11/site-packages/jinja2/environment.py", line 936, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/usr/local/lib/python3.11/site-packages/material/404.html", line 4, in top-level template code
    {% extends "main.html" %}
  File "/usr/local/lib/python3.11/site-packages/material/main.html", line 4, in top-level template code
    {% extends "base.html" %}
  File "/usr/local/lib/python3.11/site-packages/material/base.html", line 252, in top-level template code
    {% block scripts %}
^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/material/base.html", line 255, in block 'scripts'
    {% if path.endswith(".mjs") %}
^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.11/site-packages/jinja2/utils.py", line 83, in from_obj
    if hasattr(obj, "jinja_pass_arg"):
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
jinja2.exceptions.UndefinedError: 'mkdocs.config.config_options.ExtraScriptValue object' has no attribute 'endswith'

squidfunk commented 1 year ago

@mfoulds I'm not able to reproduce the error you reported. We're happy to look into it once you provide a minimal reproduction. It might be related to the release of MkDocs 1.5.0 that happened just before your comment, but I've upgraded to MkDocs 1.5.0 and I'm not seeing this problem.

squidfunk commented 1 year ago

9.2.0b2 was just released. Upgrade with:

pip install mkdocs-material==9.2.0b2

Finally that MkDocs 1.5.0 is out, we can walk towards a stable release of 9.2.0. We'll take some opportunities to adapt Material for MkDocs to 1.5.0, as Material for MkDocs will be based on MkDocs 1.5.0 from 9.2.0 onward.

mfoulds commented 1 year ago

9.2.0b2 was just released. Upgrade with:
pip install mkdocs-material==9.2.0b2
Finally that MkDocs 1.5.0 is out, we can walk towards a stable release of 9.2.0. We'll take some opportunities to adapt Material for MkDocs to 1.5.0, as Material for MkDocs will be based on MkDocs 1.5.0 from 9.2.0 onward.

Hi @squidfunk I installed 9.2.0b2 and the problem above is now resolved. Thanks!

jake-anto commented 1 year ago

I am using Beta 2 (9.2.0b2) and using the search plugin raises this error:

Traceback (most recent call last):
  File "/opt/python/3.10.8/lib/python3.10/site-packages/mkdocs/livereload/__init__.py", line 189, in _build_loop
    func()
  File "/opt/python/3.10.8/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 79, in builder
    build(config, live_server=None if is_clean else server, dirty=is_dirty)
  File "/opt/python/3.10.8/lib/python3.10/site-packages/mkdocs/commands/build.py", line 354, in build
    config.plugins.on_post_build(config=config)
  File "/opt/python/3.10.8/lib/python3.10/site-packages/mkdocs/plugins.py", line 542, in on_post_build
    return self.run_event('post_build', config=config)
  File "/opt/python/3.10.8/lib/python3.10/site-packages/mkdocs/plugins.py", line 509, in run_event
    result = method(**kwargs)
  File "/opt/python/3.10.8/lib/python3.10/site-packages/material/plugins/search/plugin.py", line 124, in on_post_build
    if self.is_dirty:
AttributeError: 'SearchPlugin' object has no attribute 'is_dirty'

vedranmiletic commented 1 year ago

I am using Beta 2 (9.2.0b2) and using the search plugin raises this error:

Traceback (most recent call last):
  File "/opt/python/3.10.8/lib/python3.10/site-packages/mkdocs/livereload/__init__.py", line 189, in _build_loop
    func()
  File "/opt/python/3.10.8/lib/python3.10/site-packages/mkdocs/commands/serve.py", line 79, in builder
    build(config, live_server=None if is_clean else server, dirty=is_dirty)
  File "/opt/python/3.10.8/lib/python3.10/site-packages/mkdocs/commands/build.py", line 354, in build
    config.plugins.on_post_build(config=config)
  File "/opt/python/3.10.8/lib/python3.10/site-packages/mkdocs/plugins.py", line 542, in on_post_build
    return self.run_event('post_build', config=config)
  File "/opt/python/3.10.8/lib/python3.10/site-packages/mkdocs/plugins.py", line 509, in run_event
    result = method(**kwargs)
  File "/opt/python/3.10.8/lib/python3.10/site-packages/material/plugins/search/plugin.py", line 124, in on_post_build
    if self.is_dirty:
AttributeError: 'SearchPlugin' object has no attribute 'is_dirty'

To save time, I'm going to ask what I am sure @squidfunk will ask, can you provide a minimal reproduction?

squidfunk commented 1 year ago

Yes, please provide a minimal reproduction. You can attach it here, you don't need to create a new issue for now.

jake-anto commented 1 year ago

After rebooting my computer, the issue seems to have resolved itself. Sorry for wasting your time.

squidfunk commented 1 year ago

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 mkdocs build, it should work again. We'll fix this issue as well.

squidfunk commented 1 year ago

9.2.0b3 was just released. Upgrade with:

pip install mkdocs-material==9.2.0b3

usulpt commented 1 year ago

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! minimal-example.zip

squidfunk / mkdocs-material