> This is the styling of our website so I want us to be consistent here.
It's a different subdomain though, just like discourse.brew.sh, bot.brew.sh, etc. (Note that discourse.brew.sh, another domain that's reading intensive, is also dark on light.)
> Markdown rendering generally renders the code font smaller in all cases. I'm game for making the difference closer but not identical.
It's not a problem of glyph size difference. This is a stylesheet issue, which results in 18px regular text vs 14.625px (let's say 15px) code. The difference is much smaller if they are both 16px, or 18px, or whatnot, which is what I'm suggesting.
> The width is optimised for readability (min-width: 25em; max-width: 35em). You'll find Safari's Reader View is only slightly wider. As a result, I'm game for increasing the width to match Safari's Reader View.
Well, reading technical documentation is different from reading stories. People typically don't read from beginning to end. GitHub's 888px wide layout is a much better compromise. (GitHub's stylesheets are specifically designed for code and technical documentation, so its design probably carries more weight than Safari Reader View's design.)
> > github.com
>
> You can still use this version.
Of course. I didn't raise the issue for myself. I would use the GitHub version regardless.
docs.brew.sh theme not very readable
====================================
Okay, this is apparently subjective, but I find the docs.brew.sh theme not very readable. A couple of points that hopefully shouldn't be too controversial (not exhaustive):
1. Light text on dark background is in general less readable than the contrary.
2. The main article area is pretty narrow (630px), a lot of space is wasted. I find cross-referencing very important when reading technical documents (just like when reading code), so more information on a single screenful really helps.
3. There's a big font size discrepancy between regular text (18px San Francisco) and monospaced text (14.625px Courier), so interspersed code looks very strange. It would be much better to use a uniform 16px font size.
4. Table styling is pretty horrible at the moment.
Overall I find it a big downgrade from the GitHub version. Compare the two screenshots at the end for instance. In fact, even plain old user agent stylesheet (see attached screenshot) is arguably much more readable. (HTML docs of old school software — often found in `/usr/local/share/doc` — usually don't include any stylesheet at all; I still find those very readable and delightful. Granted, a bit of syntax highlighting would be nice.)
Having a uniform theme across brew.sh sure is a good thing, but in this case I think readability trumps branding. I'd suggest less styling, and maybe taking some cues from GitHub's stylesheet.
---
docs.brew.sh:
github.com:
Plain user agent stylesheet:
