squidfunk
Hiding long sections partially
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
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
- [X] I have read and followed the change request guidelines.
- [X] I have verified that my idea is a change request and not a bug report.
- [X] I have ensured that, to the best of my knowledge, my idea will benefit the entire community.
- [X] I have included relevant links to the documentation, related issues, and discussions to underline the need for my idea.
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.
More specifically, you could try and adapt what I've done here: https://github.com/squidfunk/mkdocs-material/issues/4964#issuecomment-1718085465. The example was specifically targeting code blocks, but it could be adapted for any content.
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!
