-
Notifications
You must be signed in to change notification settings - Fork 50
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.
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
Icons / Emoji fail to render in header with Macros enabled #215
Comments
Welcome to this project and thank you!' first issue |
I have half an idea of why that could be. Would you have an Minimal Reproducible Example that I could test? |
mkdocs.ymlsite_name: My Docs
plugins:
- search
- macros
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
theme:
icon:
annotation: material/arrow-right-circle
name: material
language: en Index.md# Test :material-robot-happy-outline:
## Test2 :smiley:
|
Thanks. 🙂 |
Hi thanks for taking a look. I've yet to dig deeper but I found the culprit causing it. This is the first time i've tried to debug a mkdocs plugin. So it'll probably take me some time to figure out exactly what's causing this. mkdocs-macros-plugin/mkdocs_macros/plugin.py Lines 789 to 790 in bf6c8e4
Disabling title rendering in the above line makes it so mkdocs renders the icon correctly but obviously any macros in the title won't be rendered. |
That's very good: it narrows it down a lot. If I rewrite the title, that will of course overwrite that kind of processing. Should not be too difficult to fix. |
I had a look, and I confirm your observations: if we re-assign It seems mystical, since the new string is identical. Just writing this causes the bug (so MkDocs-Macros is not directly at cause): page.title = page.title + "" At this point, I would invoke @squidfunk. What do you think could be the cause? In the mean time, I put a test for the presence of a |
- to prevent a problem in case pymdownx.emoji is being used
I pushed a workaround on Github. Could I ask you to test it? That should leave us the time to investigate this strange behavior. |
Yeah that's what I observed too. maybe memory address change or something makes the emoji renders to not be called / fail?
@fralau I'm sorry, am I missing something it seems the recent commit only contains a change to the doc file. |
Yup as long as the Title doesn't contain any macros or It's a viable solution until we figure out the culprit causing it I guess. What do you think about leaving this issue open? Thanks for the fix :) |
Absolutely, let's leave it open. |
I'm not sure, but be aware that the |
okay looking at But from what I could gather none of the plugins I checked explicitly did any changes to mkdocs-macros-plugin/mkdocs_macros/plugin.py Lines 791 to 796 in 814205a
@fralau was there any reason for the above code? I would like to understand why this was added if there was any edgecase that I might be overlooking. But I can remove that completely and everything works fine. Page title renders correctly everywhere. ( I'm still yet to trackdown any other places that title could be assigned from but this is the only instance I could find where the Title could be extracted from. |
Did more digging. Looks like when I'm guessing there should be a way to replace the meta var title and not directly mess with page.title. I'll have a look at all the preprocessors and report back If i find a solution. ps: emoji rendering is not possible in metavar title anyway as |
Could you take a look at my fork. I did fix the issue. mkdocs.ymlextra:
test: "macro 1"
hi: ":material-robot-happy-outline: emoji_macro" I've also taken a look at issue #144 but menu and title seem to be rendered without any issues as seen in the screenshot above. currently only the below test case doesn't pass. But this is not a problem raised from macros as disabling the plugin still doesn't render emoji. It's most likely that the emoji plugin forgot to check meta variables.
The way I've handled the rendering of title meta variable might not be desirable for you. Please review the changes and let me know if you'd like any adjustments. If the changes are satisfactory, please confirm so I can proceed to create a pull request. Thanks :) |
- allow macros in meta variables - allow automatic parsing of title by mkdocs as explicitly assigning page.title will override that.
Thanks, because your investigation is helping a lot.
Curious: what is
Interesting 🤔 .
Are you refering to the call to macro rendering? Yes: MkDocs-Macros must be able render correctly macros in the headers of pages (when used for navigation), in the same way that references to emojis or icons must be correctly rendered. Correctly rendering macros for navigation (page names and contents table for each page) is an essential feature, just as rendering them in pages. (Actually, it is even possible write a title for a page that contains a call to a macro, in the As you noted with #144, it's not the first mysterious issue that I am having with navigation in MkDocs. There must be something to know about it, that I haven't discovered yet. Rather than jumping to fixes (which might or might not work for the 2'500+ Github projects that are using this plugin, not to mention the others I don't know about), I would like to first grasp better what the problem is, with its potential ramifications. |
What's failing right nownav:
- Home {{ test }} : index.md
- first {{ test }}:
- Second {{ test }}:
- test {{ test }}:
- Environment for {{test}}: Docs/index.md
- Also for {{ macro2}}: Docs/sub/index.md
- Not interpreted: Docs/file2.md
extra:
test: "macro 1"
hi: ":material-robot-happy-outline: emoji_macro"
macro2: "macro 2"
macro3: "macro 3" Right now with code change macros in yaml keys for nav are not rendered. vs I'll dig through the on_nav function later to see if I can get around to fixing everything. What's working right now
It's a custom class defined in mkdocs utils class weak_property:
"""Same as a read-only property, but allows overwriting the field for good."""
def __init__(self, func):
self.func = func
self.__doc__ = func.__doc__
def __get__(self, instance, owner=None):
if instance is None:
return self
return self.func(instance)
I believe this works perfectly right now even without page.title reassignment as I tested examples from these issue
And all of them render correctly without any issues. Why this works
|
Removing that call, because it is redundant? Mmm... we might be doing some progress 🤔 Providing that MkDocs can handle navigation strings nicely on its own, while we handle explicitly the entry points of MkDocs-Macros (variables whose macros must be interpreted), we might have something that works. Of course, this idea should be well formalized and tested in practice, and then it would be necessary to check that all test cases pass as before. It might be a little tedious to do, since making sure that |
Currently we are only doing a update of page title on I see two paths to make sure all macros in navs are rendered (not just the pages but sections too)
Method 1 is the most ideal. But respecting |
This commit should handle rendering of titles in navigation. Error handling for nav.title = self.env.from_string(nav.title).render(**self.variables) Hasn't been implemented yet. You have a custom At least from what I can tell all test cases seem to be passing expect one |
Awesome exploration work.
Could explain a little more in detail what the problem is with sections?
Why is it not compatible with More generally, there is a sequence issue with doing that action Trying to manipulate the nav at that stage might thus not be the right approach. It must be possible to access that object in However, assuming that the first solution that you proposed works; which is summarized (if my understanding is correct) by:
And assuming that it leaves out only a scope of unsolved issues (which we should explain clearly), then I believe it would definitely be a progress. |
I believe we need to go back to a number of key points about page title, when it appears as a section (navigation). In standard MkDocs, that can be defined in (by priority order):
MkDocs decides which one it takes, according to its own logic. I believe that MkDocs-Macros should avoid interfering with the building of the navigation. When I remove the code: debug("Page title:",page.title)
if "{" in page.title:
page.title = self.render(markdown=page.title,
force_rendering=force_rendering)
debug("Page title after macro rendering:",page.title) The nav:
- Home: index.md
- Environment for {{ unit_price}}: environment.md
- Second:
- other.md
- Not interpreted: literal.md Right now, I do not see any better solution than enforcing the rendering of macros the title. If the side effect is the non-rendering of emojis when used at the same time as macros, I am willing to live with that problem, rather than jumping into a rabbit hole. 🙂 |
Ah what I meant here is that the jinja template renderer
Yes this is correct. In situations where all three are defined Nav title is displayed in the menu while the title from meta var is displayed as the page title
Yup. The current Implementation i did wholey relies on Mkdocs to decide it. Macro plugin should just render the macros and pass it along as it is.
Yeah. Trying to obey render_macros defined in meta variables for navigation will just cause more problems than it solves. But right now with the updated solution I'm not honoring |
Submit a PR and I will have a look at it. But to be honest, the chances are that I will not pass it: adding potientally complex code (that even I might have trouble to fully understand and therefore maintain) might not worth it, considering that it is such a corner case. In any case, that PR will remain there as a research item. Who knows that it might turn useful in the future? |
@squidfunk wrote:
Sorry, I missed your remark! Makes sense. |
I documented this in the online documentation. |
Icons / Emoji fail to render in sidebar and header section when macros is enabled with mkdocs material
index.md
mkdocs.yml
Plugin Versions
When macros is enabled
Disabling macros plugin fixes the issue.
The text was updated successfully, but these errors were encountered: