From f7b11fe27529b132c3136598b7695446a80a7184 Mon Sep 17 00:00:00 2001 From: Charlotte Wickham Date: Wed, 2 Apr 2025 14:32:42 -0700 Subject: [PATCH] Add special span classes (#1601) * Add special span classes * Add callout for format exceptions (cherry picked from commit 4deb1313b055e8098cac281e9af0c1aa848f2c28) --- docs/authoring/markdown-basics.qmd | 42 +++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 3 deletions(-) diff --git a/docs/authoring/markdown-basics.qmd b/docs/authoring/markdown-basics.qmd index 62e17ed959..3c301a4b98 100644 --- a/docs/authoring/markdown-basics.qmd +++ b/docs/authoring/markdown-basics.qmd @@ -397,7 +397,12 @@ Videos can refer to video files (e.g. MPEG) or can be links to videos published ## Divs and Spans {#sec-divs-and-spans} -You can add classes, attributes, and other identifiers to regions of content using Divs and Spans (you'll see an example of this below in [Callout Blocks]). +You can add classes, attributes, and other identifiers to regions of content using Divs and Spans. +Although the terms *Div* and *Span* originate in HTML, the syntax is used in Quarto across output formats. +For example, [Callout Blocks](#callout-blocks) are specified using the div syntax, and [Small Caps](#other-spans) are specified using the span syntax, and both work for many formats beyond HTML. +You may also use CSS and/or a [Filter](/docs/extensions/filters.qmd) along with Divs and Spans to provide styling or other behavior within rendered documents beyond what Quarto provides. + +### Divs For example, here we add the "border" class to a region of content using a div (`:::`): @@ -441,6 +446,8 @@ Once rendered to HTML, Quarto will translate the markdown into: Fences without attributes are always closing fences. Unlike with fenced code blocks, the number of colons in the closing fence need not match the number in the opening fence. However, it can be helpful for visual clarity to use fences of different lengths to distinguish nested divs from their parents. +### Spans + A bracketed sequence of inlines, as one would use to begin a link, will be treated as a `Span` with attributes if it is followed immediately by attributes: ``` markdown @@ -455,8 +462,6 @@ Once rendered to HTML, Quarto will translate the markdown into: ``` -Typically, you'll use CSS and/or a [Filter](/docs/extensions/filters.qmd) along with Divs and Spans to provide styling or other behavior within rendered documents. - ### Ordering of Attributes Both divs and spans in Pandoc can have any combination of identifiers, classes, and (potentially many) key-value attributes. In order for these to be recognized by Pandoc, they have to be provided in a specific order: identifiers, classes, and then key-value attributes. Any of these can be omitted, but must follow that order if they are provided. For example, the following is valid: @@ -514,6 +519,37 @@ Learn more in the article on [Callout Blocks](callouts.qmd). | ``` | | +--------------------------+--------------------------+ +## Other Spans {#other-spans} + +To create text in small caps, that is underlined, or that is highlighted, use a span with one of the +classes `.smallcaps`, `.underline` or `.mark` respectively. + ++----------------------------------------+-------------------------------------------+ +| Markdown Syntax | Output | ++========================================+===========================================+ +| ``` markdown | [This text is smallcaps]{.smallcaps} | +| [This text is smallcaps]{.smallcaps} | | +| ``` | | ++----------------------------------------+-------------------------------------------+ +| ``` markdown | [This text is underlined]{.underline} | +| [This text is underlined]{.underline} | | +| ``` | | ++----------------------------------------+-------------------------------------------+ +| ``` markdown | [This text is highlighted]{.mark} | +| [This text is highlighted]{.mark} | | +| ``` | | ++----------------------------------------+-------------------------------------------+ + +::: {.callout-note} + +## In supported formats only + +Support for these classes comes directly from Pandoc. +Not all formats support all of these classes. +In particular, `.mark` is not currently supported in `format: pptx`. + +::: + ## Special Characters +-----------------+---------------+