can someone explain to me in which situation this line of code kicks in?
https://github.com/squidfunk/mkdocs-material/blob/86a4c47c0a/material/partials/nav-item.html#L38
https://github.com/squidfunk/mkdocs-material/blob/86a4c47c0a/material/partials/nav-item.html#L38
i'm now determined to implement clickable links.
still no idea why it wasn't added.
mkdocs/mkdocs#1042
https://gitter.im/squidfunk/mkdocs-material?at=5f8770e93775d02b5a0e8178
still no idea why it wasn't added.
mkdocs/mkdocs#1042
https://gitter.im/squidfunk/mkdocs-material?at=5f8770e93775d02b5a0e8178
even with that, i wasn't satisfied with how much of the pre-existing html i needed to duplicate. that'd go stale quick
but the main point is, this template modification is just the smaller half of this. the important part is it introduces a "protocol" into the nav that themes could agree to cooperate on, i.e. just apply this modification upstream; it's backwards-compatible
I'll follow up on this later and send requests to theme owners. if they don't want, i can just keep maintaining a hack for that theme
There was quite a disussion in some issue (haven't looked yet) some time ago regarding this topic. Personally, I don't think the plugin approach will be resilient enough, as the HTML is subject so changes (sometimes), and some people are even still stuck on Material 4. Thus, it's better to integrate it with the themes, as you already suggested. However, I think that this should be solved at the template level. However, I don't know whether MkDocs currently supports this. There's a rather old issue which might have gone stale: mkdocs/mkdocs#1042
We could move this topic forward, if there's a native way of defining section-level pages (mabe just call them
index.md?) However, given the significant time investment this bears, as Material has so many navigation options all of which still would need to work, I would consider this being an Insiders feature. If there actually is a way to do it (mostly) natively with MkDocs without the support of a plugin, we can discuss stuff in an issue over after the Material for MkDocs repository.
Ok, turns out, it's possible (I was too curious). You can just add an
index.md page in a folder and MkDocs will treat it as an index.html file of that folder. Thus, content could be added to sections. The only thing that needs to be checked is how to list those pages out in the navigation. Maybe we would need to define a special title that is treated as "don't include in nav".
the current idea is to just rely on the user to specify the titles of all items in the nav and intentionally omit the title of the first item of a section
i also made a separate extension that happens to make that natural if you write your nav in markdown https://github.com/oprypin/mkdocs-literate-nav/blob/438ef076ce8000257bccd1b4f2216abcdb8654de/tests/markdown_to_nav/test_section_with_link.yml#L9 - turns the above sample into the below nav
so that is also what i used in my demo. this is the source for the nav: https://github.com/oprypin/crystal-book/blob/mkdocs/SUMMARY.md
If there actually is a way to do it (mostly) natively with MkDocs without the support of a plugin
there really isn't and it had been rejected as you know. the best you can do is do some magic check against the first child of a section, and move it outside. that is too messy for a template to implement, and also too controversial to have on by default
a plugin really is the perfect way to implement opt-in
I need to think about this a little. Feel free to open an issue so we can discuss.
@squidfunk i finally finished a README, which at the bottom also clarifies my arguments so far.
https://github.com/oprypin/mkdocs-section-index#readme
https://github.com/oprypin/mkdocs-section-index#readme
:tada: Material for MkDocs Insiders 1.11.0 brings support for rendering Admonitions as inline blocks - no configuration required! Documentation: https://squidfunk.github.io/mkdocs-material/reference/admonitions/#inline-blocks
@squidfunk should I create a new issue? (or #1008) / how much noise can I make on pre-existing issues (in case those people are still interested)?
An issue is also a good idea to see how many users have this problem and if it's worth integrating
And yeah you can make some noise, so we get a discussion going.
1 reply
Everything works, just wondering about the warning
I'll check it out on Sunday, when I continue working on Insiders. The warning should definitely not be there.
Context for the
search.xml change: I was trying to integrate OpenSearch, which is a standard that allows to search directly from the browser bar (i.e. try to type "github.com" and then TAB), you can search GitHub directly. I haven't managed yet to get it working on Chrome, but it works 'okayish' on Firefox:
