Currently the guides use the h1 tag for the guides logo instead of the
guides title. As the guides title is more important in describing the
content of a guide, the title should use the h1 instead.
This also move every other heading to a more important heading (h3 becomes h2, etc.).
This change should improve SEO for the guides.
The Rails guides were migrated from Turbolinks to Turbo in
0f6575a534
The PR discussion explains that the file was grabbed from unpkg, and a
decision was made to not run it through a minifier.
This commit adds a rake task to automate the process of grabbing the
turbo js file using Importmap::Packager, which is what importmap-rails
uses for `bin/importmap pin --download`.
The extra Importmap module definition is necessary because the
Importmap::Packager file uses the shorthand module syntax, meaning that
an error is thrown if the Importmap module is not previously defined.
`require "importmap-rails"` would normally define this module, but one
of its dependent requires will not load outside of a Rails application.
The turbo.css file was removed as it appears to be leftover from
Turbolinks and Turbo does not provide any css files in its dist.
Removes kindlerb logic
Adds template for epub generator
Renames the kindle dir to /epub
Adds epub module to generator and replaces kindle
Fixes mimetype
Creates basic epub book
Deletes old kindle module
Adds zip package
Updates rubyzip gem name
Removes now unused gepub gem
Adds the required container file for epubs
Fixes media type
Adds new epub generation logic
Removes all buttons from output html
Refactors and generates valid epub files
Removes frontmatter logic used for kindlegen
Filters out epub files in zip
Updates link to kindle doc on sidebar
Fixes rubocop issues
Adds deprecation warning for the old kindle task
Refactors and cleans up epub module
Cleans up epub code
Cleans up private internal method code style
Removes unnecessary imagemagick check
When `main.css` is updated, it is easy for `main.rtl.css` to be
overlooked (see #45423).
This commit eliminates `main.rtl.css` in favor of a unified approach to
LTR / RTL styling in `main.css`. To accomplish this, the `<body>`
element is rendered with a [`dir` attribute][] (which has the same
effect as setting the CSS `direction` property), and LTR- / RTL-specific
styles are prefixed with `:where(body[dir="..."])` selectors. (The
[`:where()` pseudo-class][] ensures that selector specificity is not
changed.)
This change also paves the way for automatic detection and application
of LTR / RTL styles when the [`:dir()` pseudo-class][] gains widespread
browser support.
[`dir` attribute]: https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
[`:where()` pseudo-class]: https://developer.mozilla.org/en-US/docs/Web/CSS/:where
[`:dir()` pseudo-class]: https://developer.mozilla.org/en-US/docs/Web/CSS/:dir
Rendering copy-to-clipboard text in an invisible element causes
invisible extraneous matches when searching text on the page (e.g. with
Ctrl+F). Rendering in an element attribute avoids this problem.
The theme used for syntax hilighting has a number of colors that
do not meet the 4.5:1 minimum contrast ratio of the Web Content
Accessibility Guidelines (WCAG) 2.1 standard.
All colors that were below 4.5:1 on a background of #eeeeee have
been adjusted to be at or slightly above 4.5:1 using tweaked
versions of the tools in this repository:
https://github.com/mpchadwick/pygments-high-contrast-stylesheets/
Links in the header and footer of the guides currently have a
contrast ratio of 4.1:1 which is below the 4.5:1 ratio required
to pass the minimum Web Content Accessibility Guidelines (WCAG) 2.1
standard.
WCAG 2.1 Understanding Success Criterion 1.4.3: Contrast (Minimum)
https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html
Red text on a dark grey background (#22222) is generally considered
hard to read so the links were changed to the pink color from the
Rails Guides logo. Using pink avoids adding yet another shade of red
to the guideline color palette and as an added bonus has a contrast
ratio of 7.04:1 which meets the 7:1 ratio of the enhanced contrast
success criterion.
Understanding Success Criterion 1.4.6: Contrast (Enhanced)
https://www.w3.org/WAI/WCAG21/Understanding/contrast-enhanced
Restore the default browser focus indicator to improve the
accessibility of the guides for users who rely on a keyboard
for navigation.
For more information see:
Understanding Success Criterion 2.4.7: Focus Visible
in the Web Content Accessibility Guidelines (WCAG) 2.1
https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html
Adds dark mode classes using the @media query `prefers-color-scheme`. Also adds a dark color scheme for code highlighting to make code snippets more readable.
[ci skip] Adds Dark Mode to Rails Guides
Adds dark mode classes using the @media query `prefers-color-scheme`. Also adds a dark color scheme for code highlighting to make code snippets more readable.
Instead of carefully selecting the code in examples, use a copy button
for copying the code. This uses https://clipboardjs.com/ for copying.
For the bash code examples only line starting with $ prompt are copied.
The $ prompt itself is not copied.
Follow-up to #39594, which added CSS in order to select shell commands
sans prompts on triple-click.
This commit adds several bash code fences and prompts where they were
missing, and removes a few where they were inappropriate.
Replace SyntaxHighlighter with prism.js. SyntaxHighlighter does not seem
to be maintained. Prism.js seems a nice alternative with support for
Ruby, javascript, erb and yaml. Prism.js uses the MIT License.
https://github.com/PrismJS/prism
For bash a customized definition of the bash+shell-session themes is
used with the following comamnds added commands:
brew, bundle, cat, git, gem, rackup, rake, rails, ruby, rubocop and
yarn
The previous version wasn’t matching the Rails Guides logo source file
listed at https://github.com/rails/homepage/blob/master/materials/rails_guides_logo.psd
somehow. It was also a GIF when an 8-bit PNG results in a smaller file (2KB vs 4KB) which
should be just as widely compatible with browsers.
And that’s just for the 1x version. I added a new 2x version for “retina” or high-density
displays and a CSS @media query to progressively enhance with this high density
version of the logo. I’ve ensured that this query is supported across browsers by
using vendor-specific versions when necessary. See:
https://caniuse.com/#feat=css-media-resolution
[ci skip]
This notably allows us to tile each category without pushing the page down vertically
as much as we previously did on any viewport wider than mobile sizes.
It also means we can fit more guides which will become useful in the future since
we have several new guides in the work.
Finally the new layout allows three clearly distinct columns to emerge:
- Start Here and Rails basics: Models, Views, Controllers, Other Components
- Digging Deeper, Extending Rails, Contributing, Maintenance
- Release Notes
Having Release Notes shoot back up to the top of the third column is great
because that makes finding the latest released version and its associated
release notes much easier without having to scroll down a bunch.
[ci skip]
* .clearfix is overridden.
* .clear is not currently used.
* #extraCol is not currently used.
* table th, table td are overridden. Merged them.
* Removed needless comment lines which are added on #6475
Alysson Rosa