Setting a particular tab to focus when the docs are built.

[UltraInstinct05]

Is there a way to focus on a given tab ?

As an example, take https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#grouping-code-blocks as a reference. There are 2 tabs, C & C++. When the docs are built, I'd like to focus on C++ instead of C i.e. ability to focus a different tab other than first.

[squidfunk]

@facelessuser I thought this was possible with something like ===+ or ===!, similar to how details work, but can't seem to find something on your docs!? If not, would this be something to consider? Also couldn't find a reference in the tests.

[squidfunk]

Happy to fix any issues with content.tabs.link, if you can provide a reproduction showing the error.

[facelessuser]

I'm not sure it's a bug as much as the features are incompatible. I have a branch up. I thought I'd get it in the next release, but I may hold off.

[facelessuser]

Here's the branch for anyone wanting to try it: facelessuser/pymdown-extensions#1725. Syntax is simply:

===+ "Selected tab"
    content

content.tabs.link force linked tabs to be selected instead of the specified tab with checked.

[squidfunk]

Okay, so I had some time to think about this and think you're right, the features are incompatible in a way that if one of the content tabs that is part of a tabbed container was previously selected by the user, Material for MkDocs will always select that tab. The idea is that linking of content tabs only really makes sense if you do it across pages, e.g. when you have API documentation with different languages. It's also the reason why we don't have it enabled on our documentation, as it's not a good fit for mixed documentation.

We could allow to enable linking of content tabs selectively (as we allow it for code annotations) if only we could add attributes or classes to content tabs. This is currently not supported, or I haven't found a way how it works.

Maybe to improve the understanding of the current implementation of linked content tabs, here's how it works: if the user clicks a tab, we extract the text content from that tab (e.g. ignoring icons or other non-textual elements) and push that to the front of a list which we store in local storage. This is done each time the user clicks a tab. Now, when a content tab container is mounted, the list is checked for the first occurrence which can be matched against one of the tabs, and then that tab is selected. Think of it as "always select the tab that the user clicked last".:

mkdocs-material/src/partials/javascripts/content.html

Lines 24 to 39 in 30dcb66

	{% if "content.tabs.link" in features %}
	<script>
	var tabs = __md_get("__tabs")
	if (Array.isArray(tabs))
	main: for (var set of document.querySelectorAll(".tabbed-set")) {
	var labels = set.querySelector(".tabbed-labels")
	for (var tab of tabs)
	for (var label of labels.getElementsByTagName("label"))
	if (label.innerText.trim() === tab) {
	var input = document.getElementById(label.htmlFor)
	input.checked = true
	continue main
	}
	}
	</script>
	{% endif %}

Persistence is handled here:

mkdocs-material/src/assets/javascripts/components/content/tabs/index.ts

Lines 191 to 209 in 30dcb66

	if (feature("content.tabs.link"))
	push$.pipe(skip(1))
	.subscribe(({ active }) => {
	const tab = active.innerText.trim()
	for (const set of getElements("[data-tabs]"))
	for (const input of getElements<HTMLInputElement>(
	":scope > input", set
	)) {
	const label = getElement(`label[for=${input.id}]`)
	if (label.innerText.trim() === tab) {
	input.click()
	break
	}
	}
	/* Persist active tabs in local storage */
	const tabs = __md_get<string[]>("__tabs") || []
	__md_set("__tabs", [...new Set([tab, ...tabs])])
	})

[facelessuser]

Yeah, the easiest way to allow classes would be to use attr_list via === "title" {.class}. Admonitions and details are highly dependent on classes, so classes are built into their syntax via !!! class "title", but it makes less sense for tabs.

Unfortunately, when we created both Details and Tabbed, we based it on the naive regex of Admonitions which assumes that anything between the first quote and the quote at the end of the line is considered the title. This is sloppy and allows the following:

!!! note "I can add "whatever" I want"

On the surface, this is fine, but it makes the regex difficult to extend to the example below without breaking legacy expectations. You then need to parse the title properly and probably require quotes inside a string to be escaped, this is the part that may catch people unawares:

!!! note "I can add \"whatever\" I want" {.class}

This is probably what should be done, but it's definitely an approach that would break stuff.

I guess you could do something like code blocks do and match the start and end quotes ""I can add "whatever" I want"". This idea was rejected when I proposed it for Admonitions though. If I were to come up with an approach, I'd like it to be some approach that could be unified across all the like Admonition approaches.

Anyways, I could add the feature regardless, it doesn't require Material to support both tab linking and defaulted tabs, I would just need to think about how to demonstrate the idea in the docs. Maybe I would just use Codepen 🤷🏻.