Folding sections in code blocks

[brendanzab]

🚀 Feature

Allow irrelevant sections of code to be folded away in code samples.

Have you read the Contributing Guidelines on issues?

Yes

Motivation

Sometimes it's nice to be able to fold away irrelevant sections in a full code example, so that you can focus on the important parts.

Pitch

For example, if I wrote a Rust function:

fn main() {
    // sample:start
    println!("hello!");
    // sample:end
}

I'd want it to display as (note the indentation):

println!("hello!");

There would be a button on the code block to allow this to be expanded to the full code:

fn main() {
    println!("hello!");
}

Example: Kotlin's documentation

For a live example, you can check out the Kotlin docs. They seem to have a nice UI for unfolding examples. For example, here is their documentation on defining variables:

• Folded:

  

• Unfolded:

  

• Markdown source:

  

[brendanzab]

I tried posting this on Canny, but I ran into an error:

Screenshot

[elviswolcott]

I have built something like this before in Docusaurus v1, I can take a tool at it if it's something the maintainers think is worth having as a core feature.

[lex111]

I do not think that this feature should be included in core of D2. After all, you can create a plugin and enable it on demand, right?

[yangshun]

It could be a fun thing to work on, but lower priority. The main reason why Kotlin docs needed it was because they allowed running code in the browser, and hence they needed to include a bunch of boilerplate runner code which was not relevant to the sample.

[brendanzab]

Yeah no worries!

It can also be helpful if you're running your docs through CI, and want to have the setup code there to ensure all examples are runnable.

[Josh-Cena]

Time to revive this FR since we need it on our own website: a lot of the examples can be much more concise (e.g. https://docusaurus.io/docs/sidebar#collapsible-categories) if we have the other boilerplate/context collapsed

[Josh-Cena]

This will be closed without getting implemented in core. See #5783 (comment)

In the near future, I will send a PR to dogfood this on our own website, which can be used as an inspiration. I'll keep this open for now until I make that demo.