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.
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.
We recently switched to use Rouge for syntax highlighting in the guides,
but in doing so we dropped support for highlighting the following
syntaxes, which are used in the guides:
apache
diff
json
markdown
nginx
scss
xml
There was also css and the "javascript" alias, but @eugeneius already
addressed these two.
They syntaxes were all being converted to "plaintext". This change allows
all the lexers mentioned above as well as any other lexers available
through Rouge.
We have deliberately decided to not support passing rougue custom lexer
options from the code fences. Instead any lexer options that are needed
can be set by adding an entry to the lexer_language case statement. This
should lead to more consistency in formatting and gives us more control
over what Rogue options are allowed.
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
This commit is not precisely atomic, but the changes have evolved, summary:
* The ENV-based interface has been moved upwards, the generator has now a conventional
initializer.
* RAILS_VERSION is now assumed to be a Git tag. A blank RAILS_VERSION means edge guides.
* In consequence, the EDGE env variable is gone.
* The "local" version is also gone, the current SHA1 is computed for edge guides.
* Assumes guides are generated from a repo checkout (time ago users could
generate them from gems.)
* The WARNINGS flag is gone in consequence, you cannot disable warnings.
* The `api_link` Markdown helper is fixed.
* Docs about usage have one single place: rake guides:help.
* Links in guides have been revised.
To ease reading the "Active Support Core Extensions" guide, let's
automatically link references to Ruby files.
It's also possible to reference other components' files in the even
though it's not used in the guides at the moment.
[Petr Skocik & Robin Dupret]
To make sure that the user won't look at a feature that doesn't
already exist if they are looking at a previous version of the guides,
let's automatically inject the Rails version the guides have been
generated against.
To highlight ERB snippets, both `erb` and `html+erb` are used as a
language passed to the code block. However, only the former will be
correctly highlighted.
