8000 `tags` plugin build error · Issue #7960 · squidfunk/mkdocs-material · GitHub
[go: up one dir, main page]
Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

tags plugin build error #7960

Closed
4 tasks done
blakkheimgw opened this issue Feb 3, 2025 · 6 comments
Closed
4 tasks done

tags plugin build error #7960

blakkheimgw opened this issue Feb 3, 2025 · 6 comments
Labels
bug Issue reports a bug resolved Issue is resolved, yet unreleased if open

Comments

@blakkheimgw
Copy link

Context

Building error since 9.6.x upgrade

Bug description

Our building pipeline fails every time a tags.md file is present in the repo. The file can be empty (like we did until the 9.6.x version) or containing a <!-- material/tags --> section.

The stack trace :

Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ~~~^^
  File "/usr/local/lib/python3.13/site-packages/click/core.py", line 1161, in __call__
    return self.main(*args, **kwargs)
           ~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/site-packages/click/core.py", line 1082, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.13/site-packages/click/core.py", line 1697, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/usr/local/lib/python3.13/site-packages/click/core.py", line 1443, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/site-packages/click/core.py", line 788, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.13/site-packages/mkdocs/__main__.py", line 288, in build_command
    build.build(cfg, dirty=not clean)
    ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/site-packages/mkdocs/commands/build.py", line 319, in build
    env = config.plugins.on_env(env, config=config, files=files)
  File "/usr/local/lib/python3.13/site-packages/mkdocs/plugins.py", line 599, in on_env
    return self.run_event('env', env, config=config, files=files)
           ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/site-packages/mkdocs/plugins.py", line 566, in run_event
    result = method(item, **kwargs)
  File "/usr/local/lib/python3.13/site-packages/material/plugins/tags/plugin.py", line 187, in on_env
    self.listings.populate_all(self.mappings, Renderer(env, config))
    ~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/site-packages/material/plugins/tags/structure/listing/manager/__init__.py", line 327, in populate_all
    self.populate(listing, mappings, renderer)
    ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/site-packages/material/plugins/tags/structure/listing/manager/__init__.py", line 259, in populate
    tree.mappings = self._sort_listing(tree.mappings)
                    ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^
  File "/usr/local/lib/python3.13/site-packages/material/plugins/tags/structure/listing/manager/__init__.py", line 420, in _sort_listing
    return sorted(
        mappings,
        key = self.config.listings_sort_by,
        reverse = self.config.listings_sort_reverse
    )
TypeError: '<' not supported between instances of 'str' and 'int'
Cleaning up project directory and file based variables 00:01
ERROR: Job failed: command terminated with exit code 1

Related links

Reproduction

I've try to reproduce the bug but I was unable to do this on a fresh new install in a virtual env... I've copied every bit of my original doc site and the config files but it builds correctly.

I've compared the version number of every pip packages installed in our production environment VS the virtual one and they are exactly the same.

9.6.1-tags-plugin-build-error.zip

Steps to reproduce

  1. upgrade mkdocs-material from pre-3.6.x version to 3.6.x
  2. build a site with the tags plugin enabled

Browser

No response

Before submitting
@squidfunk
Copy link
Owner
squidfunk commented Feb 3, 2025 •
edited
Loading

Thanks for reporting and taking the time to try to narrow it down. Unfortunately, I'm not observing the bug, the build works fine:

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /.../9.6.1-tags-plugin-build-error/site
INFO    -  Documentation built in 0.20 seconds

It must be something else. I recommend to purge all caches and try to narrow it down further. To fix it, we need a minimal reproduction that show cases the problem, or we can't fix it. If you or somebody else can reproduce it, we'll reopen this issue.

@squidfunk squidfunk added the needs reproduction Issue lacks a minimal reproduction .zip file label Feb 3, 2025
@kamilkrzyskow
Copy link
Collaborator
kamilkrzyskow commented Feb 3, 2025 •
edited
Loading

I haven't run it myself, but investigating from the error message, I got to this idea:

The default self.config.listings_sort_by function uses the item.title value to compare the mapping for sorting:

mkdocs-material/src/plugins/tags/__init__.py

Lines 38 to 40 in ebf1257

# Return item title for sorting
def item_title(mapping: Mapping):
return mapping.item.title

A Mapping item, can be a Page | Link object, and title is assumed to be of type str.
So I asked myself how to get an int title 🤔
https://github.com/mkdocs/mkdocs/blob/7e4892ab2dd4a52efd95a9de407eee63310e0780/mkdocs/structure/pages.py#L244-L245

The title can be fetched from the meta.title front matter value, and AFAIK there is no preprocessor to assure that the title value will be loaded as str. So I'm assuming that a plain int value could be causing such issue, however there is no such thing in the example above:

---
title: 12345
---

# Title

@blakkheimgw
Copy link
Author

Hello,

I've finally found the origin of the problem, even if I don't understand why the crashing occured (but @kamilkrzyskow was on the good track I think).
In my old markdown notes (made with Obsidian), I had some front metadata like these ones :

---
title: 20240425
updated: 2024-04-26 07:04:02Z
created: 2024-04-25 08:58:26Z
tags:
  - incident
---

The crashing reason was the title item. As soon as I removed it, the building was OK.

@squidfunk
Copy link
Owner
squidfunk commented Feb 5, 2025 •
edited
Loading

Perfect, thanks for sharing. I now know how to reproduce the error. Create two articles which share the same tag, and use the aforementioned title + another title that is a string. This will be fed to the sorting function, and the, boom:

TypeError: '<' not supported between instances of 'int' and 'str'

Fixed in 4861c7d. Reopening and keeping open until released.

@squidfunk squidfunk reopened this Feb 5, 2025
@squidfunk squidfunk added bug Issue reports a bug resolved Issue is resolved, yet unreleased if open and removed needs reproduction Issue lacks a minimal reproduction .zip file labels Feb 5, 2025
@kamilkrzyskow
Copy link
Collaborator
kamilkrzyskow commented Feb 5, 2025 •
edited
Loading

Oh right, I didn't run it myself, so I missed the crucial part of adding tags to the front matter to trigger the tag comparison 😅

Thanks for the follow up, at least I now know, that I guessed right 🤘 , and that's probably the same fix I would make, as the assert isinstance(item.title, str) should likely be in MkDocs itself.

EDIT:
Also not all plugins do the conversion, so such issues could come up again, so @blakkheimgw better wrap the title in quotes to make it a string

---
title: '20240425'
---

@squidfunk
Copy link
Owner

Released as part of 9.6.3.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug Issue reports a bug resolved Issue is resolved, yet unreleased if open
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@squidfunk @blakkheimgw @kamilkrzyskow
0