Mkdocs-material: Click and reveal functionality.

[gkphilip]

Feature request: Click and reveal functionality.

We use materials for making workshops to teach students and really like it as a theme. However, we have questions and answers sections for students and we would like the answers to be hidden that are only revealed once clicked. There may be additional "hints" given that can be clicked and revealed before the answers as well.

Additionally, it would be useful in the scenarios where we have supplementary background information that is only revealed when clicked as the page would be too long and require a lot of scrolling if it was not "hidden" as such.

I have been using the mdx_showable extension (https://andrewjrobinson.github.io/python-md-showable/) but it would be great if Material for mkdocs natively had the function as there are some issues with this plugin and Material for mkdocs.

[squidfunk]

This could be done with the <detail> and <summary> HTML5 tags, which seem to be the perfect fit: http://html5doctor.com/the-details-and-summary-elements/

I'm not a friend of requiring JavaScript for this, so the showable extension is out of the question. detail/summary should work in any modern browser without JavaScript. However, you would then have to write HTML inside your Markdown.

Currently there is no plan of adding support for this in the theme, but we can leave this issue open, so I may implement it when I find some time, but there are higher priority issues at the moment.

EDIT: also, maybe you can elaborate a little on what issues there are with this extension and Material.

[facelessuser]

A simple extension to implement the HTML5 route has been on my list for a bit now for pymdown-extensions. I plan on keeping it simple though, and I don't have the exact syntax outlined yet. I imagine it would be done in a style similar to Python Markdown's admonition extension. I don't agree with the approach mdx_showable uses to implement this with start and end markers as it makes parsing it overly complicated.

As I mentioned it would be pretty simple. Nesting would be supported, and you could define open if needed, but that is about it. If a fallback JavaScript is desired, the user would be responsible for providing that.

[facelessuser]

Creating a markdown extension to output <detail> and <summary> was trivial. But things like Firefox and IE just don't support them for most people. But at least they can be targeted and styled appropriately. At very least, that can be achieved.

So if the collapsing and opening is desired, you'd still have to implement JavaScript for fallback, but then you also have to detect if it is supported in the browser as some do support <detail> already. Over here I found a code snippet to test for details support, he says it is public domain. I didn't bother looking into his jQuery plugin that then adds closing and opening support as I don't want to include jQuery on my document sites.

So, I will probably continue forward with the extension to implement them with <detail> and <summary> as eventually they should get supported by browsers. At the very least, coding up some decent consistent styling for all browsers can be achieved. And I may end up throwing together some JavaScript, but one day I can drop it once all browsers catch up which makes going <details> attractive.

[max-ci]

Or you can use checkbox "hack" if you don't care about semantics.

http://dabblet.com/gist/34dffedbb64d35d6557c8bf2e87e8129

[facelessuser]

Usually, my preference is to not use JavaScript if I can help it (some things you just have to use it), but in this case I kind of prefer to go with the standard coupled with a JS hack and have it naturally degrade until I can just remove the script.

[gkphilip]

Thanks for your replies and suggestions. In terms of the issues I described about mdx_showable and Material, it is mainly just formatting issues in terms of layout and the extension is not very customisable. @facelessuser, is there documentation or an example that I could see for using your spoilers functionality?

[facelessuser]

@gkphilip, I don't know what you mean about "layout and extension". If you are just talking about its styling in the documentation, I assume both mdx_showable and spoilers will be just as configurable; it's all done with CSS. I think mdx_showable has a couple options that mine won't.

The difference between the two is that mdx_showable will always need JavaScript to make it work. It's also not standards compliant (but you might not care about this).

spoilers will be standards compliant, meaning that once all browsers add support for details and summary tags, the little JavaScript that is currently needed can be completely removed. The script is already not needed in Chrome and does nothing in Chrome and a few others.

@squidfunk wants to avoid locking the Material theme into including JavaScript for this kind of feature when there is an HTML5 feature that doesn't require JavaScript. That is what spoilers is aiming to provide. The only problem right now is that not all browsers have caught up to supporting the HTML5 way, but they most likely will. This means @squidfunk can style it in the theme and one day they will work in all browsers without need of JavaScript. But right now, you still need a fallback JavaScript to make them work which @squidfunk may not be interested in providing.

Anyways, spoilers is still in development as I've not tested it in all scenarios yet, so the documentation is still unpolished and not live yet. You can read what I have written so far here: https://github.com/facelessuser/pymdown-extensions/blob/details/docs/src/markdown/extensions/spoilers.md. I document a little bit about what CSS and JavaScript I currently use, but I still need to polish it up and give up a complete copy/paste-able JavaScript solution, but info enough is there that people can get it going.

So in short, your best chance of getting these styled by material in the future is probably going with something that outputs in details, but spoilers isn't any more configurable than mdx_showable, and maybe you prefer mdx_showable. It just provides your content wrapped in details and summary. I attach a class to details that you can target with CSS and/or JavaScript, and you can apply your own class as well to allow styling some different than others. If you want to tweak the look, you can edit the example CSS that I show in the docs and tweak it your liking. You inject extra CSS through the mkdocs.yml variable extra_css, and you inject extra JavaScript with the extra_javascript variable.

[squidfunk]

@squidfunk wants to avoid locking the Material theme into including JavaScript for this kind of feature when there is an HTML5 feature that doesn't require JavaScript. That is what spoilers is aiming to provide. The only problem right now is that not all browsers have caught up to supporting the HTML5 way, but they most likely will. This means @squidfunk can style it in the theme and one day they will work in all browsers without need of JavaScript. But right now, you still need a fallback JavaScript to make them work which @squidfunk may not be interested in providing.

That's correct. I'm always aiming for the standards way and details/summary seems to be the way to go. Spoilers looks pretty cool, thanks @facelessuser. At the moment I'm really limited in time but I will definitely add support for it when it's finished. Please drop a note in this thread when I can start integrating it.

Regarding the JavaScript fallback - I would just use a polyfill. This one looks good: https://www.npmjs.com/package/details-polyfill.

[facelessuser]

Regarding the JavaScript fallback - I would just use a polyfill. This one looks good: https://www.npmjs.com/package/details-polyfill.

@squidfunk, I'll give the polyfill a try, it looks like it will make the CSS even more simple. I'll drop you a line here when I'm done.

[squidfunk]

THere are obviously some issues with the polyfill, but I think they can all be handled. Otherwise the polyfill links to some other polyfills, but with much larger footprints.

[facelessuser]

Okay, just looked at the polyfill source, looks like it is pretty much what I'm already doing. I think the addition is it injects the arrow markers where I was letting CSS do that. I think that part is unnecessary, but it's nice to have a solution that is importable via node. So I don't think we'll have any issues complying with it's requirements. spoilers shouldn't create any loose text, we can easily remove the summary::before CSS. I think it will be fine.

[squidfunk]

Okay, then I'll just wait for the release of spoilers.

[facelessuser]

No problem. I think the polyfill might be fine, but I usually prefer to let CSS do it's job and JavaScript do its job. A number of these polyfill solutions want to inject the styles in the documents. The injection will just make it difficult if you want to use different markers, or adjust the size of the markers as it will override your CSS.

Some of the others all seem to be based off the same or similar details support check, but some add more support for things like onToggle, el.open = True, el.setAttribute('open', 'open'), and/or toggling on space bar and enter. Some try to support back to IE6 (just let IE6 die already). This is where I don't know what ideally would be desired. I'm sure there are reasons for including all of this, but the question is how far do we want to go.

In the end, I think I'm just going to roll a very simple and small example that generally works and gives a good starting point. I'll let the experts figure out the best polyfill to use :slightly_smiling_face:.

[gkphilip]

Thank you both for your replies and efforts. Here is an example of what mdx_showable looks like when using Material (https://gkphilip.github.io/btp-module-template-md/modules/example/#questions-and-answers). I looked into the changing the stylesheet provided with mdx_showable (https://github.com/andrewjrobinson/python-md-showable/blob/master/mdx_showable/media/mdx_showable.css) but mdx_showable assigns an ID for every element and it appears that Material adds vertical space before ID and I didn't want to change that in case I affected the Material theme for the rest of the document (Unfortunately that's as far as my skills could take me as I'm not from a technical background!). It seems that using spoilers is a more elegant solution so will look into using it in future.

[facelessuser]

@gkphilip Material does this thing where it injects element with ids :before as block.

Try this:

.myclass[id]:before {
    display: inline;
}

This should help hopefully remove the weird spacing thing. I ran into that issue with other custom stuff I'm doing.

[gkphilip]

Thanks @facelessuser. That worked for me. I have had various other issues with mdx_showable breaking with extensions I am using (independent of Material), so I will keep an eye open for when spoiler is available. Thanks again for your and @squidfunk's efforts.

[facelessuser]

So I got the basics done, now I just want to finish up testing:

@squidfunk, I tired out details-polyfill, but I ended up having to fight it inserting the disclosure triangle if I wanted to style it Material-ish. It also had weird behavior if the details object started in open state -- you had to click it twice to close the object, at least in IE. I found the simple approach I was doing which avoided themes and didn't and avoided messing with properites worked best for a simple static site. I imagine more feature rich pages would need things like toggle events etc., but I don't think it is necessary for simple docs.

I still need to test how it renders in mobile before I can release and push out new documentation.

[squidfunk]

Wow, well done! I'm happy to integrate this.

[facelessuser]

Glad you like it :).

[facelessuser]

Feature has been released (in pymdown-extensions).

[tseemann]

This is excellent, thank you all!

[facelessuser]

For anyone that is looking to get started with this before it gets integrated over here. You can grab the Material-ish styles and JavaScript (or just the basic polyfill) you need by pulling it from the project's source folder; I have the 'extra' source broken up by what it does, so you can just look for spoilers. You'd have to convert it from es2015 and SCSS, but it's all there.

Technically you could also grab the whole theme extender folder and get it, but I also package styles and JavaScript for all of PyMdown Extension's features with a couple of extra preference tweaks which may not be desired, but it is a good way to quickly play around with this feature or other features until you throw together what you personally want or it gets integrated over here.

And you can always just view the docs which serves as a big demo for all the features.

[facelessuser]

It is likely I will rename "Spoilers" to "Accordions". It seems that there are some who feel spoilers are not necessarily accordions, and as there seems to be discussions about on CommonMark about what an official (official to CommonMark) spoiler syntax would be, it seems to avoid confusion, an rename is probably in order.

[squidfunk]

It seems that there are some who feel spoilers are not necessarily accordions

Exactly my thought, but it's only a name.

[facelessuser]

People can be quite passionate about names :).

[max-ci]

I think toggles would be more appropriate, for me accordions are when you have for example 3x details > summary and when you open one, other close. But... it's just a name :D

[squidfunk]

or just details.

People can be quite passionate about names :).

I am very passionate about names 💃

[facelessuser]

This is good. Usually I'm in an echo chamber bouncing ideas off myself.

I agree it's just a name. I realized they weren't just for spoilers when I named it. I just thought it sounded better than details :slightly_smiling_face: . I was having a conversation with someone who had very specific opinion of what a spoiler is. And it makes sense. Stack Exchange had their spoilers and so on. I figure to avoid confusion, I probably should better reflect what this is.

[facelessuser]

Maybe details is going to be the most descriptive.

[squidfunk]

There is this great principle of least astonishment ;-)

[facelessuser]

There is this great principle of least astonishment ;-)

Well said. I think that's my plan moving forward. I'll just call it details. Yeah, some early adopters will get hit with the name change (that's my fault), but I think it's for the best. I may provide a deprecation path, or maybe I'll just rip the bandage off.

[gkphilip]

As an early adopter, I'm OK with ripping the bandage off!

[facelessuser]

It is done.

[squidfunk]

Did some preparation work in #439, rest to come.

[facelessuser]

Interesting. I do like how the admonition style is more confined to the header. Excited to see your take on the details and how they will differ from admonitions.

[squidfunk]

See #441 - some polishing missing (polyfill, cleanup CSS), but in general good to go. For me it's really working with the new cleaner Admonition styles.

[squidfunk]

Finished and released as part of 1.9.0. Also added new Admonition styles: info and question, the latter of which should be pretty well suited for the purpose of FAQs or tests.

[facelessuser]

@squidfunk Looks good. Really like the new look of admonitions and how it's leveraged for details.

[gkphilip]

Looks great. Thanks very much.