From 0ad5212fe8859cd71d29aa9f8cbb2692dc9999fa Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Tue, 31 Oct 2023 14:15:11 -0600 Subject: [PATCH] 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 --- docs/modules/ROOT/nav.adoc | 2 +- docs/modules/ROOT/pages/code-blocks.adoc | 92 +++++++++++++++++++ .../modules/ROOT/pages/copy-to-clipboard.adoc | 48 ---------- docs/modules/ROOT/pages/style-guide.adoc | 7 +- 4 files changed, 97 insertions(+), 52 deletions(-) create mode 100644 docs/modules/ROOT/pages/code-blocks.adoc delete mode 100644 docs/modules/ROOT/pages/copy-to-clipboard.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 0318a13..fdbccfa 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -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[] diff --git a/docs/modules/ROOT/pages/code-blocks.adoc b/docs/modules/ROOT/pages/code-blocks.adoc new file mode 100644 index 0000000..3347a95 --- /dev/null +++ b/docs/modules/ROOT/pages/code-blocks.adoc @@ -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 <>, 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 +---- diff --git a/docs/modules/ROOT/pages/copy-to-clipboard.adoc b/docs/modules/ROOT/pages/copy-to-clipboard.adoc deleted file mode 100644 index 0eaf058..0000000 --- a/docs/modules/ROOT/pages/copy-to-clipboard.adoc +++ /dev/null @@ -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 <>, 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 ----- diff --git a/docs/modules/ROOT/pages/style-guide.adoc b/docs/modules/ROOT/pages/style-guide.adoc index 24c245e..e1559ed 100644 --- a/docs/modules/ROOT/pages/style-guide.adoc +++ b/docs/modules/ROOT/pages/style-guide.adoc @@ -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]