[Docs] Hide example code by default

[mbrookes]

Given the number of examples for some components resulting in a large page, (even with some of the code hidden as it currently is), and due to the scrolling behaviour when scrolling past the partially shown code, I think it would look cleaner, and be easier to navigate to the properties if we hide the example code completely by default.

I have made a simple change locally (but not submitted yet) that looks like this:

Code hidden (default)

#### Code revealed

Let me know what you think.

[oliviertassinari]

I had the same feeling. I have reduced the number of displayed lines from 17 to 7. That wasn't deployed, the material-ui website still use 17 lines.
Do you think it's enought?

[oliviertassinari]

due to the scrolling behaviour when scrolling past the partially shown code

Well, that's a good point.

[mbrookes]

Hi Olivier, yes, I had looked at it with the reduction to 7 and it's certainly an improvement, but personally I still think it looks cleaner and is easier to navigate with the code hidden.

Another benefit is comparing different component variations side-by-side.

I know css frameworks often show the markup, but usually it is just a few lines of html / css inline with the docs.

[oliviertassinari]

Well, that sounds like a good idea. I'm up for it. Let see what @alitaheri and @newoga think.

[oliviertassinari]

I was also wondering, we will have more space, should we add a title to each example?

[newoga]

@mbrookes @oliviertassinari Yeah I agree how the examples are currently shown could be improved. Still not completely sure about best approach and haven't tinkered myself but I think @mbrookes suggestion is worth a shot.

@mbrookes Could you make a PR so I can check out the branch?

I think it would look cleaner, and be easier to navigate to the properties if we hide the example code completely by default.

Another idea (that maybe could be done in addition) is to put id tags on examples and props. We could link to the props from the top.

[mbrookes]

Here you go: https://github.com/mbrookes/material-ui/tree/docs-hide-examples

[newoga]

Mm, yeah I think I like this better 👍

I think I agree that a title for example could be worth it, might help give each example more context, though I'd be curious to see how it looks and I'm not sure how easy it would be to appropriately naming the examples (naming things is hard).

Adding a new title bar on the top of the example would probably take up too much space. However, the bar that has Show the code could be a good place to put a title, but only if we can have the title stay in that position and not cascade to the bottom of the example, that could be confusing.

[newoga]

For what it's worth, I still think at some point we should look at implementing number 2 of this list.

The API/props docs would be nice to have in its own section.

[mbrookes]

@newoga I'd had the same thought about giving the examples some context.

Are you proposing to have the title appear beside the button when collapsed, but above the code when opened?

[newoga]

@mbrookes Yeah that's what I currently have in mind but it's just an idea. I'm not sure if that would work well in reality. Feel free to take a stab if you have some time.

[newoga]

Another idea is to do it similarly to angular material. https://material.angularjs.org/latest/demo/autocomplete

They just put everything, including the code above the rendered example.

What they do is actually pretty interesting because they almost write docs for the example inline with the rendered element. So it doesn't seem like a random element in a box. That also helps with the "context" problem.

[mbrookes]

Okay, let me have a go at that.

[mbrookes]

Ok, take a look: https://github.com/mbrookes/material-ui/tree/docs-hide-examples

The first example in AppBar is the only one I've updated to take full advantage of the new layout, but hopefully you can see the potential.

CodeBlock now has a title-bar (which is an AppBar), and takes an optional title and description prop.

title defaults to "Example", and description is blank by default, so docs updates to add a title ad description can be dome in stages while still looking fine with the defaults.

The description can be markdown, either in a string in SomeComponent/Page.jsx or optionally in its own file, as in the AppBar example - probably only necessary for longer descriptions, but we can agree on the best approach.

The whole title-bar is currently clickable to open the code example, but that can easily be changed, for example if we manage to get CodePen or similar working at some point and want to add another icon to the title-bar. And I'm not set on the icon, it was the first one that seemed remotely relevant, so can be happily changed.

Hope you like it! 😀

[mbrookes]

Code hidden (default)

Code revealed

[newoga]

Mmmmmm, I like it! Nice work! 👍 I'd probably be fine with the code icon. I'll check the latest from you branch and try it out in a bit.

@oliviertassinari @alitaheri Thoughts?

[oliviertassinari]

I love it 😍. @newoga I agree with you for the icon.

[mbrookes]

Found, it thanks - now updated. I'll submit a PR for review, as I'm sure there will be other tweaks needed.

[mbrookes]

I've updated the screenshots.

[alitaheri]

Wow! nice work @mbrookes It's fantastic 😍