Rework typography #283
Rework typography #283
Conversation
|
Thanks for working on this @jonathanhefner ! On OSX using Firefox 116.0.2 the vertical centering of the sidebar items seems a little off. I'm not sure what the design direction of SDoc is. |
The styling for the tree is unfortunately very brittle. As you noticed when working on dark mode, it uses a repeating background image and exact element heights for striping. Eventually I want to address that too, but for now I can force the tree to use the previous font. (That is what I am doing for the search results; it just didn't appear to be necessary for the tree.)
The goal of this rework is to let developers read documentation using their preferred fonts and font sizes. Contrast that to the Rails homepage, where the goal is to market Rails. There is some overlap of course (for example, brand color), but there are many design decisions that are fine for marketing material but not for documentation. With regards to the guides, in my opinion, they should also respect user font preferences. But that's outside the scope of this PR. 😉 |
|
I just noticed this also fixes a styling issue with unordered lists nested in ordered lists. The former Before
After
|
Technically savvy users are more likely to have a font preference configured, and developers are more likely to have a preference for a particular monospace font. This commit removes the font family and base font size from the stylesheet so that users can view the documentation with their preferred fonts. In particular, this stops forcing the use of the Courier font for `<code>` elements nested in `<p>` when the Consolas and Menlo fonts are not installed, which is commonly the case on Linux. This also fixes mismatching fonts for `<code>` elements nested in `<p>` versus `<code>` elements nested in `<pre>`.
Similar to the `full_name` helper, the `short_name` helper escapes its input and wraps the result in a `<code>` tag. But, whereas `full_name` will call `RDoc::CodeObject#full_name` when given an `RDoc::CodeObject`, `short_name` will call `RDoc::CodeObject#name`. This commit also changes the `link_to` helper to no longer escape its input text. Thus it can be used together with the `short_name` helper.
This factors out a `method_signature` helper that wraps method signatures in `<code>` tags and ensures that signatures are always HTML-escaped, including signatures from `:call-seq:` documentation. Incidentally, this fixes a visual disparity between `:call-seq:` signatures and normal method signatures due to the way they were wrapped with `<b>` tags. This commit also forces the postprocessor to use Nokogiri's `HTML5` parser to prevent extraneous newlines from being inserted into a signature's preformatted `<h3>` tag.
The `link.svg` file is from [Feather icons][feather] v4.29.0, and is [licensed under the MIT license][license]. [feather]: https://feathericons.com/ [license]: https://github.com/feathericons/feather/blob/v4.29.0/LICENSE
This changes links to use the brand (i.e. banner) color. This also changes links to be underlined by default, except for links which have a `<code>` element as their only child. Additionally, this fixes hover styles so that they do not linger after tap on mobile.
These resets are not necessary.
jonathanhefner
force-pushed
the
typography-redesign
branch
from
6818338
to
746d017
Compare
|
I've updated this PR to force the tree to use its original font. I think this PR offers a large improvement, so I am going to merge. If we decide we want to force all of the documentation to use a particular font or font size, it will be an easy change. All of the styles in this PR scale based on the root font size and the value of |
This PR is divided into several commits. Together, these commits rework the typography of rendered documentation, including font faces and sizes, margins and spacing, link appearance, and color scheme.
See the individual commits for specific changes, or see the screenshots below for the overall result. All screenshots — both before and after — were taken in Firefox on Ubuntu with DejaVu Serif (desktop @ 18px, mobile @ 16px) as the default font and DejaVu Sans Mono (desktop @ 17px, mobile @ 16px) as the default monospace font.