Focussable & Collapsible code blocks.

[UltraInstinct05]

Was just going through the documentation for Torchlight (from #3943). Looks like they have focus sable & collapsible code blocks.

I believe this would be a great feature to have in mkdocs for material, since it makes following through code along examples, easier by just make the relevant code sections focused (while dimming the rest of the section). Even collapsible section (folded code blocks) makes it easier for the user to manually fold blocks in larger code examples and focus on one part.

[squidfunk]

Could you elaborate what you mean by focusable code blocks? It would be very helpful if you could provide some examples. Also, collapsible code blocks would probably need to be supported by the Highlight extension, which we use for highlighting.

[UltraInstinct05]

This link has an example of it https://torchlight.dev/docs/annotations/focusing

[SilentGlasses]

Have you tried using their css options to see how it would work for you?

I'm not a coder but I'm pretty sure if you add the CSS functions and then updated whatever code converts markdown to html, you could achieve this without introducing a hole other system to the base of material.

Just thinking out loud.

[SilentGlasses]

I think that while Torchlight is great, from what I saw on the example link, I feel like it's a bit overkill for this purpose and more on the "fancy" trick side of things. What purpose would it serve other than just look "cool"?

This is already an option for highlighting the lines you want to focus on using the hl_lines argument in your code block. For example, to highlight line 3 in your code block you would do this:

``` ruby hl_lines="3"
# -*- coding: us-ascii -*-
if yr % 400 == 0
	puts "#{yr} is a leap year"
elsif yr % 4 == 0 && yr % 100 !=0
	puts "#{yr} is a leap year"
else
	puts "#{yr} is not a leap year"
end

Which would work like so:

As for collapsible code block, this is already available, see here:

Collapsed

    ???+ note "Collapsable but open"
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa.

Not Collapsed

??? note "Collapsed"
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
    massa, nec semper lorem quam in massa..

Example using both collapsible boxes and highlighting

Write your docs section like this:

??? note "Collapsed"
    ``` ruby hl_lines="3"
    if yr % 400 == 0
    	puts "#{yr} is a leap year"
    elsif yr % 4 == 0 && yr % 100 !=0
    	puts "#{yr} is a leap year"
    else
    	puts "#{yr} is not a leap year"
    end
    ```

Collapsed

Expanded:

[squidfunk]

This needs deep language support, either on the Python or JavaScript side, and a proper editor like Monaco, and we'd currently consider it out of scope for us. It could however be implemented in something like MkDocstrings, maybe.

[WildeTechSolutions]

Looking at the Torchlight documentation, I don't think that is true. It appeared that you manually specified the blocks of code that you want to be collapsible. It seems like a nice ability, not really necessary, but certainly not embedding an IDE instance or anything like that.

[squidfunk]

Well, we at least need theme support, and Pygments will not add semantic information of what constitutes as a block and what not. This is different per language, e.g., for Python (whitespace) and JavaScript (curly braces or even keyword, e.g. if/else) Therefore, we need a preprocessor that adds that information to the code block which we in turn can use to add the collapsing functionality. AFAIK, Pygments doesn't provide those semantics.

[squidfunk]

It appeared that you manually specified the blocks of code that you want to be collapsible.

That is of course always an option, but the question is: how do you specify it? If we add support for this functionality, we need it to be language agnostic. If you like to prototype this, and can show that it works for any language, we're happy to discuss it in a PR.

[guhuajun]

For me, I understood the original demand, but also accepted the existing approach.