Hiding long sections partially

[ojacques]

Context

This request is a follow to a GitHub discussion.

Description

I write documentation and tutorials which may have long sections, between two options. For example:

You could do it this way:

- long set of instructions

Or this other way:

- Another long set of instructions

I would like the ability to show a preview of long sections of texts and fold/unfold to see the full text.

Related links

• AWS documentation site with this capability

Use Cases

On a long documentation page, not all sections are relevant to the reader, or sections which contain explanations and long code blocks. I would like readers to judge whether they need to see and read those sections, or continue reading the rest of the documentation.
I expect this to improve readability of long pages.

Visuals

An example on how this is done on this AWS documentation site:

As you can see, some sections are partially hidden, until the reader presses "Show more", which unfolds the section.

One can then click "Show less" to fold the section back.

Before submitting

• I have read and followed the change request guidelines.
• I have verified that my idea is a change request and not a bug report.
• I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
• I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.

[alexvoss]

An immediate solution would be to use a custom admonition that is collapsible. With some tweaking, this could be made to look similar to what Amazon do - if, say, you do not like the border around the admonition. If you use the block syntax that the Pymdown Extensions provide then you don't have to worry about indentation as much.

[facelessuser]

More specifically, you could try and adapt what I've done here: #4964 (comment). The example was specifically targeting code blocks, but it could be adapted for any content.

[squidfunk]

Thanks for suggesting! We'll evaluate this as a potential change request in the future. If you want to go ahead and check if you can find any potential approaches how this can be elegantly solved, feel free to share them here!