I've added a .sidebar-header element (which currently includes .search-box) which makes the search box stand out a bit from the results list. This would also be a good spot for name, version and date of the documented API as suggested in #4754

The live preview shows the current state.

There is also an enhanced search interface based on this PR and #4746. I'd like to get this or the other merged so I can rebase accordingly and keep a simple commit history.

Good job! Can't wait for this

There is also an enhanced search interface based on this PR and #4746. I'd like to get this or the other merged so I can rebase accordingly and keep a simple commit history.

I am against using web fonts. Keep it lightweight.

Inline code looks weird.
Compare Overview in old/new

There is way too much spacing added in the sidebar, both regarding the width and line spacing. I'd say the spacing is too much even as it is right now.

Thanks for your remarks @oprypin, I'll address your comments in one:

• Web fonts don't add much overhead, it just needs to be downloaded once. From a technical point this is negligible considering the API docs are usually browsed relatively frequently. It is rather a question of visual style: should there be a unique look everywhere (which requires to provide font definitions) or more variation and usage of system-specific fonts (this is used for the monospace fonts).
• I added a slight border around inline code to highlight it against regular text. In the current style it is not always easy to distinguish. Although I believe I added this before I changed the fonts, and Roboto and Consolas have a higher contrast than Avenir and Consolas. If we keep this fonts it might be okay to remove the border, but that also depends on the other monospace fonts.
• The paddings there did not change. I think this entire type list needs some review in a dedicated topic, There are some usability issues in the way this is implemented and it might be worth rethinking navigation overall. There have been a few comments and ideas about that in the past.

Here's what I see.

Can't agree with "paddings there did not change". We don't need to discuss the sidebar's general problems to see that something is off.

Tahoma on the left (which is the current default if Avenir is not available) has much bigger letters than Roboto on the right, even at the same font-size. The paddings are exactly the same, it's just that the letters on the right are smaller and therefore increase the impression of space around the text.

Do you not see that the picture on the right has a wider sidebar and also fits in less text vertically? They are taken at the exact same scale and viewport size

Mobile before/after ☹️

• You should set the list vertical padding to 0 and use line-height: 1.5 for the list.
• Web fonts are fine as long as there's a defined fallback which also looks good.
• Mobile in general needs the sidebar to be toggleable.

@oprypin Oh yes, the width of the sidebar changed slightly but this has nothing to do with paddings. Before, it was a relative value (20% of viewport width) and I changed it to an absolute 30em which makes more sense in general, considering that the viewport could be very large or very small but the sidebar should always be about the same width. This could be further improved by making the width slightly responsive.

Mobile sucks before and after. I have a few improvements for that (including toggleable sidebar) but I'd address this in another PR because this one is already quite extensive and tweaking a responsive layout can be challenging by itself. I'd prefer to get this merged as the standard layout for "normal size" screens and then work on improving other sizes.
I guess I should remove the viewport meta attribute until there is proper support for smaller screens.

@RX14 I don't see any benefit in using line-height over vertical padding. There shouldn't be any line breaks inside a type list item, so there shouldn't be any difference. But if there would be one by any chance, it's better to have the space between items defined as padding instead of line-height.
You proposed values lead to misplaced triangles (tree node symbols), so this would need some adjustments. But I'd prefer not to touch the specifics of the type list style in this PR because this might need to be reworked anyway.

@straight-shoota the benefit of line-height is that it's relative to the font size. Just replacing .types-list a with line-height: 1.5; padding-left: 30px makes the left arrows more central. At least in firefox.

@RX14 I guess that depends on your defaults. The triangle element a::before has a fixed height of 30px. A font-size of 16px (that's the default value in my Chrome installation) with line-height: 1.5 results in the total height of the anchor element at 24px - which means a misaligned triangle. With a default line-height of (usually) 1.2 the line height is 19.2px and with two 5px paddings it adds up to about 30px total height - which makes the triangles fit.
So yes, this whole type list needs a big overhaul but also requires a discussion about the usability features (among others).

I'm usually very tolerant to design updates if they aim to minimalism and efficiency. But in this case I strongly dislike new fonts. They are much harder to read. Regarding to headers, it feels like serif font. I vote for Roboto! 👊

What about separate pull requests?

I want all of this except fonts.

Fonts may be subject of another PR.

Sure, I can easily extract the fonts to discuss them separately. Though I'd like to hear what others (especially core members) think first.

First of all, the structural changes are very welcome. It follows overall good practices and cleans things up 👍

I'm not fond of visual changes. The bolder view-source link is attracting the attention too much and isn't very pretty. The new fonts may follow the Crystal branding, but this isn't a crystal branding website, this is a reference. We should focus on readability, try to fit better with the gitbook documentation maybe, not impose Crystal branding to the documentation of each and every project.

To be honest, I don't like the actual fonts either. I wish we used a mere helvetica, sans-serif and consolas, monospace, instead of that huge list of font families. I wish we improved typography with a line-height: 1.4 too. Best rendering, best readability to my taste.

Also, the actual sidebar behaves better on smaller screen than yours. I'm not talking of smartphones screens, but half of my 15" laptop screen for example: yours takes too much space, at the expense of the documentation.

Thanks for the feedback!

• I'll try modify the source links to make them stand out less. Maybe some lighter color and smaller font-size can do this or a lighter font size.
• I think it's best to discuss fonts in a separate issue. I was pretty confident that everyone would agree to follow the Crystal CI but obviously this is not the case ;)
• Half a 15" laptop screen is actually about the size of a smartphone and we need a solid solution for these sizes anyway: Neither the current nor my proposal are very usable. I'll add a max-width: 20% to reduce the width on smaller viewport sizes until there is a proper solution.

No. Half of my 15" inch laptop screen is bigger than my 9.7" iPad. It's a lot bigger than my 5" smartphone !

@ysbaddaden I wasn't talking about physical dimensions but visually perceived size. A typical 15" laptop screen fits about 80 to 85em horizontal, a smartphone or tablet usually somewhere between 50 and 60em. So half a 15" screen actually fits less characters per line than a 5" smartphone in default font size.

I have removed the font changes from this PR and opened #5053
Small-screen display has been improved (basically to be similar as it was before this PR) and the source links have been downsized.
The preview link now contains the updated changes.

@straight-shoota Is this PR dead in the water?

The search input's placeholder text is not accessible as-is, according to the W3C's WCAG specification:

Using this CSS resolves the issue:

.sidebar input::placeholder {
    color: black;
    font-size: 14px;
    text-indent: 2px;
}

Is this PR dead in the water?

Pretty much, yes. Most of the proposed changes have been applied in separate PRs. Not even sure what else is left to do. So I guess it's time to close this. We can alwas cherry pick items from here.

Please open a new PR for the placeholder text.

Okay, I've opened #11604.