Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Anchoring a content tab possible? #350

Open
riccstick opened this issue May 6, 2024 · 5 comments
Open

Anchoring a content tab possible? #350

riccstick opened this issue May 6, 2024 · 5 comments
Labels
feat: upstream a feature that exists upstream but is not well supported in sphinx-immaterial

Comments

@riccstick
Copy link

I tried to add a reference to a content tab, so that if I click on a reference link I will be directly navigated to the content tab. Like it is in the mkdocs.

I think it is not implemented yet, or is something like this already possible?

Thank you for any answer.

@2bndy5
Copy link
Collaborator

2bndy5 commented May 6, 2024

Currently, our main branch includes updates from mkdocs-material up to v8.5.6. So, no the hyperlink-able content tabs are not implemented in this port of the mkdocs theme because they were not made publicly available until v9.0 (or v9.2 I can't remember which).

There is nothing you can do from an end-user standpoint. We have #338 in the works, but that is not a guarantee that the hyperlink-able content tabs will work. EDIT: Using content tabs as anchors works in the RTD build for #338 (empirical evidence), but it may need a new md-tab-item option for :name: (like with md-tab-set).

For now, you can only make references to a group of content tabs, not an individual content tab.

.. md-tab-set::
    :name: my-cool-tab-set

    .. md-tab-item:: Tab title
    
        This is a :ref:`reference <my-cool-tab-set>` to the entire content tabs group.

@riccstick
Copy link
Author

Thank you.

What would also be nice to have, would be to add the cross-ref (.. _my-ref:) into a collapsible block and after clicking on the link, the collapse block expands (this is already working) and the page jumps to the content tab.

.. md-tab-set::

    .. md-tab-item:: tab1

            .. collapse::  content1
            .. collapse::  content2

    .. md-tab-item:: tab2

            .. collapse::  content3
            .. collapse::  content4
                   .. _my-ref:

Just if this use case is of interest. 😃

@2bndy5
Copy link
Collaborator

2bndy5 commented May 6, 2024

That .. _my-ref: doesn't make sense to me; I've only ever used that syntax to add a referencable name to a section title; my understanding of that syntax is that it must come before a block element, not finish a block element.

Any collapsible elements that this theme explicitly supports is the collapsible admonitions. And our admonitions also support the :name: option as well.

clicking on the link, the collapse block expands (this is already working) and the page jumps to the content tab.

If it doesn't work upstream, and involves JS (as that feature request definitely would), then we ask that such feature requests go upstream to mkdocs-material repo. Although, I'm not sure if your usage is practical/common.

@riccstick
Copy link
Author

Sorry for the delay, but in my case, what I would like to do is to use the name of the collapsible admonitions as a reference, either in the documentation itself or to share the URL with someone else. The link should than bring me to the correct content tab and should open the collapsible admonitions.

image

In my image, the collapsible admonition is located in the second content tab and if I click on a link with the URL and the :name: it does not bring me to the second content tab and it does not open the collapsible admonition. So what I was looking for is that I have a link and that link brings me to the second content-tab and opens the collapsible admonition.

But maybe this is already possible and I simply does not know how this could work.

@2bndy5
Copy link
Collaborator

2bndy5 commented May 17, 2024

I already understand what you're requesting, and my answer hasn't changed.

It might be better to do an old fashioned writer review. In your case, I think the structure of the document you've written can be adjusted to use less admonitions and content tabs and more section titles.

As maintainers of the theme, we cannot just start making changes to the JS that we inherit from upstream mkdocs-material. Such deviations have proven impossible to maintain when merging in updates from upstream.

If you devise some custom JS to implement what you want, then you can include the custom script in the doc build (see html_js_files).

@2bndy5 2bndy5 added the feat: upstream a feature that exists upstream but is not well supported in sphinx-immaterial label Jun 26, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
feat: upstream a feature that exists upstream but is not well supported in sphinx-immaterial
Projects
None yet
Development

No branches or pull requests

2 participants