Where communities thrive


  • Join over 1.5M+ people
  • Join over 100K+ communities
  • Free without limits
  • Create your own community
People
Repo info
Activity
  • 09:25
    squidfunk commented #2245
  • 09:20
    squidfunk commented #2236
  • 09:18
    squidfunk commented #2152
  • 09:07

    github-actions[bot] on gh-pages

    Deployed 603fea6 with MkDocs ve… (compare)

  • 09:06

    squidfunk on master

    Updated Insiders documentation Merge branch 'master' of github… (compare)

  • 08:42
    funkypenguin opened #2245
  • 05:38

    github-actions[bot] on gh-pages

    Deployed b8fb5ee with MkDocs ve… (compare)

  • 05:37

    dependabot-preview[bot] on npm_and_yarn

    (compare)

  • 05:37

    dependabot-preview[bot] on master

    Bump preact from 10.5.10 to 10.… (compare)

  • 05:37
    dependabot-preview[bot] closed #2242
  • 05:36

    github-actions[bot] on gh-pages

    Deployed b0541b1 with MkDocs ve… (compare)

  • 05:35

    dependabot-preview[bot] on npm_and_yarn

    (compare)

  • 05:35

    dependabot-preview[bot] on master

    Bump @types/node from 14.14.21 … (compare)

  • 05:35
    dependabot-preview[bot] closed #2243
  • 05:35
    dependabot-preview[bot] synchronize #2242
  • 05:35

    dependabot-preview[bot] on npm_and_yarn

    Bump preact from 10.5.10 to 10.… (compare)

  • 05:35
    dependabot-preview[bot] edited #2242
  • 05:34

    github-actions[bot] on gh-pages

    Deployed 7454211 with MkDocs ve… (compare)

  • 05:33
    dependabot-preview[bot] edited #2242
  • 05:33

    dependabot-preview[bot] on npm_and_yarn

    (compare)

Oleh Prypin
@oprypin
@squidfunk i haven't heard of "template extension". if you're talking about theme custom_dir, that's a project specific override, i didn't find a way to make it reusable
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
Martin Donath
@squidfunk
Did you check mobile navigation?
Oleh Prypin
@oprypin
not initially, but seems like it just works.
Martin Donath
@squidfunk
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.
Martin Donath
@squidfunk
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".
Oleh Prypin
@oprypin
@squidfunk ah wish i was free to discuss this at length right now
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
Oleh Prypin
@oprypin
as you said, it is indeed possible to check that this page is index.html specifically, and i used to have that clause, but it's inflexible / goes against the philosophy, because the file/directory structure must be decoupled from nav definition
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
Oleh Prypin
@oprypin
as per my implementation, now all that a template needs to do is consider the case that a nav item might have both children and url
Martin Donath
@squidfunk

that is too messy for a template to implement

have you looked at the Material for MkDocs templates? :D There are so many hacks

I need to think about this a little. Feel free to open an issue so we can discuss.
Oleh Prypin
@oprypin
yes let me write this down properly this evening
Martin Donath
@squidfunk
Cool, thanks for our work on this!
Martin Donath
@squidfunk
*your
Oleh Prypin
@oprypin
@squidfunk i finally finished a README, which at the bottom also clarifies my arguments so far.
https://github.com/oprypin/mkdocs-section-index#readme
Martin Donath
@squidfunk
Great write-up!
Stephen Gates
@Stephen-Gates
^^^ Thank you both for progressing this. Would love to use that feature on my sites.
Oleh Prypin
@oprypin
@Stephen-Gates you can do that now 🙃
Stephen Gates
@Stephen-Gates
Just did it. Works perfectly :-) Thanks for your work.
Martin Donath
@squidfunk
@sponsors – I just added all of you with access to the private repository to the new private Docker image on GitHub Container Registry. I don't know whether GitHub sent an email, but I'm currently updating the docs which should explain how to use it
Martin Donath
@squidfunk
: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
admonition-inline-end.png
Oleh Prypin
@oprypin
@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)?
Martin Donath
@squidfunk
You can create a new issue where we can discuss the solution, however I‘m still not convinced this should be a plugin, but let‘s find out 😊
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.
Oleh Prypin
@oprypin
Martin Donath
@squidfunk
Great! Thanks!
Lars
@wilhelmer
WARNING - Template skipped: 'search.xml' not found in theme directories. - what's with that? Introduced with the latest Insiders version
1 reply
Everything works, just wondering about the warning
Martin Donath
@squidfunk
That was an attempt to get OpenSearch to work. I'm not sure about it, yet. search.xml needs to be listed under static_templates.
I'll check it out on Sunday, when I continue working on Insiders. The warning should definitely not be there.
Martin Donath
@squidfunk
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:
Ohne Titel.gif
Martin Donath
@squidfunk
Super small survey regarding theme mods: squidfunk/mkdocs-material#2071
Lars
@wilhelmer
Thanks for the info, Martin
Another thing, related to MkDocs, not Material, but maybe you have some thoughts on this
I use, like many others, the mkdocs-minify-plugin for minification. However, 404.html never gets minified. This is because the on_post_page event isn't fired for 404.html, and the plugin uses that event for HTML minification
Any quick idea how to work around that
Lars
@wilhelmer
Maybe use on_post_build and minify 404.html directly (hard-coded). But that seems a little hacky
Martin Donath
@squidfunk
Interesting, never realized that this was the case. Sounds definitely like a MkDocs issue so maybe create an issue over at their repository?