Where communities thrive

• Join over 1.5M+ people
• Join over 100K+ communities
• Free without limits
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

• 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

• 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

apopova
@AnastasiaTWW
hi guys! have you ever tried to solve the problem with cached css and js contents? I've deployed a new script but it works only after all saved browser files are deleted. can I force css and js files update on the mkdocs-material side? I want to try to solve the problem on my side without changing the deployment configuration
Martin Donath
@squidfunk
All Material for MkDocs assets have chunk hashes, so I guess your problem relates to custom/extra CSS?
If so, the probably easiest thing you can try is using query-string based cached busting: https://css-tricks.com/strategies-for-cache-busting-css/#query-strings – albeit it's not a best practice, it's easier to implement than chunk hashes, which demand a build process.
apopova
@AnastasiaTWW
@squidfunk thanks a lot! looks like this hack helped :)
Martin Donath
@squidfunk
Benjamin Staneck
@Stanzilla
found some more search oddities, inserted "MoveTo" into a few more documents, search finds it but the preview does not show it
Martin Donath
@squidfunk
The search preview currently shows the text from the beginning, highlighting any words it finds in the first few sentences. The match may be at a latter point in the document.
Better search summaries are already on the roadmap: https://squidfunk.github.io/mkdocs-material/insiders/#biquinho-vermelho – it's something I wanted to do before, but it's far from easy to solve this for all of the 40 languages. However, it will definitely be addressed in the next months.
Benjamin Staneck
@Stanzilla
hrm yeah
it gives the impression that it does not find the searched for term at all currently
Martin Donath
@squidfunk
Jep, I'll push it up on my priority list, definitely something to improve 😊In the meantime, the search highlighting feature of Insiders helps to highlight the occurrences in the results.
Try searching for "awesome" on the Insiders docs and just press ENTER, it'll highlight the result in the text: https://squidfunk.github.io/mkdocs-material-insiders/deprecations/?h=+awesome#bundled-plugins
Benjamin Staneck
@Stanzilla
yeah insiders search is way better
luzai
@luzai
Hi, may I ask whether we could encrypt the pages with a password while rendering latex code successfully?
Martin B
@martinbira
Try it out with the mkdocs-encryptcontent-plugin, https://github.com/CoinK0in/mkdocs-encryptcontent-plugin
luzai
@luzai
Thank you, but I cannot render the latex code when using this plugin.
Martin Donath
@squidfunk
You probably need some logic that triggers MathJax after the content has been decrypted
Isaac Muse
@facelessuser
MkDocs uses Markdown, not LaTeX. If you want to parse LaTeX in Markdown, you need some kind of extension that can parse LaTeX inside Markdown, or at least preserve the LaTeX from being treated as Markdown and use a JavaScript Library to parse it afterwards. The latter is how most known Markdown extensions handle LaTeX math. Material’s documentation covers this here: https://squidfunk.github.io/mkdocs-material/reference/mathjax/. And the extension it references gives even more details in its own documentation: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/.
Isaac Muse
@facelessuser
I realize now that you may have been referring to it not working with encryption which may be a separate issue.
luzai
@luzai
Thank you very much! If not encrypted, the formula can be rendered. But it not works with encryption. I would submit an issue to mkdocs-encryptcontent-plugin and ask about the logic that triggers MathJax after decrypted.
Oleh Prypin
@oprypin
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
Oleh Prypin
@oprypin
aha it kicks in for the currently active item. but then why isn't nav_item.active or something used?
Oleh Prypin
@oprypin
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
Oleh Prypin
@oprypin
it'll have to be a plugin messing with html of templates. but if i find some generic and non intrusive way to communicate this just within the nav then maybe the themes will get on board with this
Oleh Prypin
@oprypin
Martin Donath
@squidfunk
Glad you achieved what you were aiming for. However, wouldn’t template extension be a better fit? Why a plugin?
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
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!