Where to put custom Javascript in Material?

[mgriff88]

I have a particular use case where I am placing tags within a heading. I want the text from the heading to appear in the page TOC, but not the tag itself.

This is the Markdown:

### alertsSearchQuery [String](#string){: .api-tag}
And it looks like this:

Body:

TOC:

In this example, alertsSearchQuery is the h3 part, but String is from the tag and I don't want it to appear there.

My idea is to write a Javascript function for use in toc-item.html partial that strips out any characters that appear between [ and }. Can someone explain to me how I can get Material to register that function? I've tried placing the JS file in overrides and adding it as a plugin or a markdown_extension, but it's never able to find it, and I just get serve errors.

TL;DR: Where do you place custom Javascript in Material?

[kamilkrzyskow]

Hello @mgriff88,
MkDocs and with that the Material for MkDocs theme uses Python to generate the static site. There is no way to simply connect/enable JavaScript during the Python execution. Running external JavaScript processors and passing strings between Python and JavaScript isn't the best idea here, definitely not recommended.

Where do you place custom JavaScript in Material?

• https://squidfunk.github.io/mkdocs-material/customization/#additional-javascript

As per the documentation the recommended/the least invasive way to add JavaScript is to use a extra.js file and add it in your mkdocs.yml file. The logic of that JavaScript to properly execute after document$.subscribe or document.addEventListener("DOMContentLoaded") is left up to you.

• https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event

You can use something like this to change all of the TOC elements:

for (const el of document.querySelectorAll('[data-md-type="toc"] .md-typeset')) {
  el.innerHTML = "123";
}

However, this is JavaScript code that runs after the page is rendered, so if there is a delay in processing it then users will see the changes happening in real time (removal of the [String])

---

If you want to change it directly in HTML during the source creation process, you'll need to work with Python or templates.

The TOC is attached to the page object:

mkdocs-material/src/templates/partials/toc.html

Line 31 in 68332de

{% set toc = page.toc %}

You could edit it in for example in the on_page_context event.

• https://www.mkdocs.org/dev-guide/plugins/#events
• I consider this the best approach ✌️

---

If you accept the idea of overriding a template and replacing it then you could try modifying the TOC item content inside the template:

mkdocs-material/src/templates/partials/toc-item.html

Line 27 in 68332de

{{ toc_item.title }}

I didn't check if .title is a string, but I'm assuming it is a string containing the <span> 🙂, so you can try {{ toc_item.title.replace('[String]', '') }}

[mgriff88]

Hi @kamilkrzyskow , thanks for the detailed response! I'm all for overriding a template, unfortunately that replace() filter isn't working quite right...

I've tried adding tags around the text I want to remove too, but still not working.

When I ask ChatGPT about this, it says I need to add Python instead. Any guidance on where to place custom .py file?

[kamilkrzyskow]

that replace() filter isn't working quite right...

It would be good to know how it doesn't work, is there some error, create a minimal reproduction? Also replace() isn't a filter, just the str.replace method.
As for the example from ChatGPT this code will remove everything, including the span tags, not only the stuff within.
I'm not sure if regex is the best approach here, performance-wise 🤔 But better use capture groups to separate elements in the string and return the group you want to display.

To implement this logic in MkDocs you would use the on_env event in a hook:

• https://www.mkdocs.org/user-guide/configuration/#hooks
• https://www.mkdocs.org/dev-guide/plugins/#on_env
• Example from the Material for MkDocs blog plugin:
  

  mkdocs-material/src/plugins/blog/plugin.py

  Line 323 in 68332de

  env.filters["date"] = date_filter