mirror of
https://github.com/boostorg/unordered-ui-bundle.git
synced 2026-01-19 04:42:15 +00:00
add dedicated page for code blocks
- move code blocks page under UI elements styles and behaviors - introduce code blocks - move copy to clipboard information to page - add information about how to add (or remove) support for a language in the syntax highlighter
This commit is contained in:
Dan Allen
@@ -8,10 +8,10 @@
|
||||
* xref:add-static-files.adoc[]
|
||||
* xref:stylesheets.adoc[]
|
||||
** xref:add-fonts.adoc[]
|
||||
* xref:copy-to-clipboard.adoc[]
|
||||
* xref:style-guide.adoc[]
|
||||
** xref:inline-text-styles.adoc[]
|
||||
** xref:admonition-styles.adoc[]
|
||||
** xref:code-blocks.adoc[]
|
||||
** xref:list-styles.adoc[]
|
||||
** xref:sidebar-styles.adoc[]
|
||||
** xref:ui-macro-styles.adoc[]
|
||||
|
||||
92
docs/modules/ROOT/pages/code-blocks.adoc
Normal file
92
docs/modules/ROOT/pages/code-blocks.adoc
Normal file
@@ -0,0 +1,92 @@
|
||||
= Code Blocks
|
||||
:page-aliases: copy-to-clipboard.adoc
|
||||
|
||||
This page describes some of the styles and behaviors of code blocks and how to support them in a custom UI.
|
||||
|
||||
In AsciiDoc, code blocks a referred to as source and listing blocks.
|
||||
A source block is a listing block that has a source language defined on it (e.g., javascript).
|
||||
Refer to xref:antora:asciidoc:source.adoc[source blocks] to learn more about source blocks in AsciiDoc and how they are used in Antora.
|
||||
|
||||
Readers typically expect that a source block will be presented with syntax highlighting, so we'll start there.
|
||||
|
||||
== Syntax highlighting
|
||||
|
||||
Antora uses highlight.js as syntax highlighter in the AsciiDoc processor by default.
|
||||
|
||||
If you want to turn off syntax highlighting, you can do so by unsetting the `source-highlighter` attribute in the Antora playbook.
|
||||
|
||||
[,yaml]
|
||||
----
|
||||
asciidoc:
|
||||
attributes:
|
||||
source-highlighter: ~
|
||||
----
|
||||
|
||||
If you soft unset the value instead (i.e., set the value to `false`), it allows individual pages to selectively turn syntax highlighting back on.
|
||||
|
||||
By default, Antora highlights a restricted set of languages in order to minimize the size of the supporting asset files.
|
||||
However, you can add or remove support for languages in your own UI bundle.
|
||||
To do so, follow these steps:
|
||||
|
||||
. Switch to your UI project.
|
||||
. Open the file [.path]_src/js/vendor/highlight.bundle.js_.
|
||||
. Add or remove one of the `registerLanguage` statements.
|
||||
|
||||
For example, to add AsciiDoc syntax highlighting, add the following line:
|
||||
|
||||
[,js]
|
||||
----
|
||||
hljs.registerLanguage('asciidoc', require('highlight.js/lib/languages/asciidoc'))
|
||||
----
|
||||
|
||||
Keep in mind, the language must be supported by highlight.js.
|
||||
To find out what languages are supported and how to abbreviate them, set the https://github.com/highlightjs/highlight.js/tree/9-18-stable/src/languages[languages] folder in the project on GitHub.
|
||||
|
||||
== Copy to clipboard
|
||||
|
||||
This page describes the copy to clipboard feature added to source blocks when using the default UI.
|
||||
|
||||
=== Source blocks
|
||||
|
||||
The default UI provides JavaScript that adds a clipboard button to all source blocks.
|
||||
The clipboard button shows up next to the language label when the mouse is hovered over the block.
|
||||
When the user clicks the clipboard button, the contents of the source block will be copied to the user's clipboard.
|
||||
|
||||
You can try this behavior below:
|
||||
|
||||
[,ruby]
|
||||
----
|
||||
puts 'Take me to your clipboard!'
|
||||
----
|
||||
|
||||
IMPORTANT: Copy to clipboard only works for a local site or if the site is hosted over https (SSL).
|
||||
The copy to clipboard does not work on an insecure site (http) since the clipboard API is not available in that environment.
|
||||
In that case, the behavior gracefully degrades so the user will not see the clipboard button or an error.
|
||||
|
||||
=== Console blocks
|
||||
|
||||
The default UI also adds a clipboard button to all console blocks.
|
||||
A console block is either a literal paragraph that begins with a `$` or a source block with the language `console`.
|
||||
|
||||
The script provided by the default UI will automatically strip the `$` prompt at the beginning of each line and join the lines with `&&`.
|
||||
In <<ex-console-copy-paste>>, since the language is `console` and each line begins with a `$`, the console copy-paste logic is triggered.
|
||||
|
||||
.Copy to clipboard for a multi-line console command
|
||||
[#ex-console-copy-paste]
|
||||
------
|
||||
[,console]
|
||||
----
|
||||
$ mkdir example
|
||||
$ cd example
|
||||
----
|
||||
------
|
||||
|
||||
When a user uses the copy-to-clipboard button, they will copy the combined command `mkdir example && cd example` instead of the literal text shown.
|
||||
This can be useful for tutorial examples that a user is expected to copy-paste to run.
|
||||
You can try this behavior below:
|
||||
|
||||
[,console]
|
||||
----
|
||||
$ mkdir example
|
||||
$ cd example
|
||||
----
|
||||
@@ -1,48 +0,0 @@
|
||||
= Copy to clipboard
|
||||
|
||||
This page describes the copy to clipboard feature added to source blocks when using the default UI.
|
||||
|
||||
== Source blocks
|
||||
|
||||
The default UI provides JavaScript that adds a clipboard button to all source blocks.
|
||||
The clipboard button shows up next to the language label when the mouse is hovered over the block.
|
||||
When the user clicks the clipboard button, the contents of the source block will be copied to the user's clipboard.
|
||||
|
||||
You can try this behavior below:
|
||||
|
||||
[,ruby]
|
||||
----
|
||||
puts 'Take me to your clipboard!'
|
||||
----
|
||||
|
||||
IMPORTANT: Copy to clipboard only works for a local site or if the site is hosted over https (SSL).
|
||||
The copy to clipboard does not work on an insecure site (http) since the clipboard API is not available in that environment.
|
||||
In that case, the behavior gracefully degrades so the user will not see the clipboard button or an error.
|
||||
|
||||
== Console blocks
|
||||
|
||||
The default UI also adds a clipboard button to all console blocks.
|
||||
A console block is either a literal paragraph that begins with a `$` or a source block with the language `console`.
|
||||
|
||||
The script provided by the default UI will automatically strip the `$` prompt at the beginning of each line and join the lines with `&&`.
|
||||
In <<ex-console-copy-paste>>, since the language is `console` and each line begins with a `$`, the console copy-paste logic is triggered.
|
||||
|
||||
.Copy to clipboard for a multi-line console command
|
||||
[#ex-console-copy-paste]
|
||||
------
|
||||
[,console]
|
||||
----
|
||||
$ mkdir example
|
||||
$ cd example
|
||||
----
|
||||
------
|
||||
|
||||
When a user uses the copy-to-clipboard button, they will copy the combined command `mkdir example && cd example` instead of the literal text shown.
|
||||
This can be useful for tutorial examples that a user is expected to copy-paste to run.
|
||||
You can try this behavior below:
|
||||
|
||||
[,console]
|
||||
----
|
||||
$ mkdir example
|
||||
$ cd example
|
||||
----
|
||||
@@ -1,7 +1,7 @@
|
||||
= UI Element Style Guide
|
||||
:navtitle: UI Element Styles
|
||||
= UI Element Style and Behavior Guide
|
||||
:navtitle: UI Element Styles and Behaviors
|
||||
|
||||
When creating a UI theme for Antora, there are certain elements in the UI that require support from the CSS to work correctly.
|
||||
When creating a UI theme for Antora, there are certain elements in the UI that require support from the CSS--as well as JavaScript in some cases--to work correctly.
|
||||
This list includes elements in the shell (i.e., frame) and in the document content.
|
||||
This document identifies these UI elements.
|
||||
|
||||
@@ -21,3 +21,4 @@ These elements include:
|
||||
* xref:list-styles.adoc[Lists]
|
||||
* xref:sidebar-styles.adoc[Sidebars]
|
||||
* xref:ui-macro-styles.adoc[Button, keybinding, and menu UI macros]
|
||||
* xref:code-blocks.adoc[Code blocks]
|
||||
|
||||
Reference in New Issue
Block a user