Skip to content

Commit 7be6034

Browse files
cdervcderv
committed
New review
1 parent 439b71b commit 7be6034

File tree

1 file changed

+110
-32
lines changed

1 file changed

+110
-32
lines changed

‎vignettes/markdown-html-tables.qmd‎

Lines changed: 110 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Use the `tbl_qmd_*()` functions when:
3131

3232
- Your table package already has built-in Quarto support (like gt's `fmt_markdown()` or tinytable's `format_tt(quarto = TRUE)`)
3333
- You're working outside of Quarto documents (the functions will have no effect)
34-
- Simple formatting is easy enough to write in raw HTML and does not require Quarto Markdown processing.
34+
- Simple formatting is easy enough to write in raw HTML and does not require Quarto Markdown processing
3535

3636
## Basic Usage
3737

@@ -103,14 +103,34 @@ xfun::fenced_block(attrs = ".html", tbl_qmd_span("**Bold text**")) |>
103103

104104
Quarto sees the `data-qmd-base64` attribute and processes the base64-decoded content as Markdown.
105105

106+
### Base64 vs Raw Encoding
107+
108+
The helper functions offer two encoding options:
109+
110+
- **Base64 encoding** (default): Safer for complex content with special characters
111+
- **Raw encoding**: More readable in HTML source, but can have escaping issues
112+
113+
```{r}
114+
# Base64 encoding (default) - safer for complex content
115+
complex_content <- tbl_qmd_span_base64("Content with <em>HTML</em> & special chars")
116+
117+
# Raw encoding - more readable but potential escaping issues
118+
simple_content <- tbl_qmd_span_raw("**Simple bold text**")
119+
120+
data.frame(
121+
Type = c("Base64", "Raw"),
122+
Content = c(complex_content, simple_content)
123+
) |>
124+
knitr::kable(format = "html", escape = FALSE)
125+
```
126+
106127
### Using with knitr::kable()
107128

108129
The `knitr::kable()` function is a common way to create tables in R Markdown and Quarto. By setting `escape = FALSE`, we can include HTML in the table cells:
109130

110131
```{r}
111132
#| label: tbl-kable-equation
112133
#| tbl-cap: A table with a math equation rendered using Quarto's data-qmd attribute
113-
library(quarto)
114134
115135
# Create a data frame with math expressions
116136
tbl <- data.frame(
@@ -129,7 +149,7 @@ knitr::kable(tbl, format = "html", escape = FALSE)
129149

130150
### Display Text
131151

132-
Some features are Quarto features only. If your table can be used in other context than Quarto, you might want to use the `display` argument to provide a text that will be shown in the table instead of the Markdown content, as it won't be processed outside of Quarto documents.
152+
Some features are Quarto-specific. If your table might be used outside of Quarto, you can use the `display` argument to provide fallback text that will be shown when the Markdown content can't be processed.
133153

134154
For example, you might want to show a placeholder when using video shortcodes in a table, as the video player won't be rendered outside of Quarto:
135155

@@ -151,51 +171,109 @@ data <- data.frame(
151171
knitr::kable(data, format = "html", escape = FALSE)
152172
```
153173

154-
Behavior when the table is not processed by Quarto is simulated by opting-out html table processing for this specific table. For example, when `html-table-processing: none` cell option is set like in the Quarto computation cell below.
174+
Behavior when the table is not processed by Quarto is simulated by opting-out HTML table processing for this specific table. For example, when `html-table-processing: none` cell option is set like in the Quarto computation cell below.
155175

156176
```{r}
157177
#| label: video-placeholder
158178
#| echo: fenced
159179
#| html-table-processing: none
160180
```
161181

162-
Output above is a HTML table not processed by Quarto, so the video shortcode is not rendered as a video player, but as a regular text.
182+
Output above is an HTML table not processed by Quarto, so the video shortcode is not rendered as a video player, but as regular text.
163183

164184
See more about disabling HTML table processing in the [Quarto documentation](https://quarto.org/docs/authoring/tables.html#disabling-quarto-table-processing).
165185

186+
## Troubleshooting
187+
188+
### Common Issues
189+
190+
**Content not rendering as Markdown:**
191+
- Check that `escape = FALSE` is set in your table function
192+
- Verify that Quarto HTML table processing is enabled (it's on by default)
193+
- Ensure you're using the functions in a Quarto document
194+
195+
**Escaping problems:**
196+
- Use base64 encoding (the default) for content with special characters
197+
- Use `tbl_qmd_span_base64()` explicitly for complex HTML content
198+
199+
**Performance with large tables:**
200+
- Base64 encoding adds some overhead - consider raw encoding for simple content in very large tables
201+
- Test with your specific use case to determine if performance is acceptable
202+
203+
**Content appears as HTML tags:**
204+
- You may have forgotten `escape = FALSE` in your table function
205+
- Double-check that your table package supports raw HTML content
206+
207+
### Testing Your Setup
208+
209+
Use this simple test to verify everything is working:
210+
211+
```{r}
212+
test_data <- data.frame(
213+
Test = "Markdown Processing",
214+
Result = tbl_qmd_span("**This should be bold**")
215+
)
216+
217+
knitr::kable(test_data, format = "html", escape = FALSE)
218+
```
219+
220+
If the text appears bold, your setup is working correctly.
221+
166222
::: {.callout-important}
167223

168224
## Limitations
169225

170-
Using `data-qmd` or `data-qmd-base64` attributes is a Quarto-specific feature and it will only be working when Quarto is allowed to process HTML tables. If this is used in an environment or a document that do opt-out Quarto HTML table processing, the content will not be rendered as expected.
226+
Using `data-qmd` or `data-qmd-base64` attributes is a Quarto-specific feature and will only work when Quarto is allowed to process HTML tables. If this is used in an environment or document that opts out of Quarto HTML table processing, the content will not be rendered as expected.
171227

172228
:::
173229

174-
## Table package integration
230+
## Table Package Integration
175231

176-
To summarize the question of Markdown processing in HTML tables within Quarto, currently, there are two ways this could be supported:
232+
To summarize Markdown processing in HTML tables within Quarto:
177233

178234
- This is possible thanks to Quarto HTML Table parsing
179-
- This is done using some `<span>` or `<div>` elements with `data-qmd` or `data-qmd-base64` attributes
235+
- This is done using `<span>` or `<div>` elements with `data-qmd` or `data-qmd-base64` attributes
236+
237+
Any R package for producing tables and providing raw HTML as output can support this Quarto feature to allow Markdown content in HTML tables.
238+
239+
Currently, there are two ways this can be supported:
240+
241+
- **Built-in support**: The package already supports Quarto HTML table parsing and offers a way to mark cells as to be processed by Quarto when in Quarto context. In this case, they create the `<span>` or `<div>` elements with the `data-qmd` or `data-qmd-base64` attributes internally.
180242

181-
Any R package for producing tables and providing raw HTML as output needs to support this Quarto feature to allow Markdown content in HTML tables.In this case, they will create themselves the `<span>` or `<div>` elements with the `data-qmd` or `data-qmd-base64` attributes.
243+
- **External helper approach**: The package does not support Quarto HTML table parsing directly but offers a way to insert raw HTML content in table cells. In this case, you can use the helper functions provided by this package to create the `<span>` or `<div>` elements with the appropriate attributes.
182244

183-
Currently, there is two ways this could be supported:
245+
Below we show how this works with some popular R packages for creating tables.
184246

185-
- Either the package already supports Quarto HTML table parsing, and offer a way to mark the cells as to be processed by Quarto when in Quarto context. In this case, they will create themself the `<span>` or `<div>` elements with the `data-qmd` or `data-qmd-base64` attributes.
247+
### For Package Developers
186248

187-
- Either the package does not support Quarto HTML table parsing directly, and offers a way to insert raw HTML content in the table cells. In this case, you can use the helper functions provided by this package to create the `<span>` or `<div>` elements with the appropriate attributes.
249+
If you're developing an R package that creates HTML tables, consider:
188250

189-
Below will show how this works with some popular R packages for creating tables.
251+
**Integration Options:**
252+
1. **Full integration**: Add native support for `data-qmd` attributes (like gt and tinytable)
253+
2. **Raw HTML support**: Allow users to insert raw HTML and let them use these helper functions
254+
3. **Hybrid approach**: Detect Quarto context and automatically apply appropriate attributes
255+
256+
**Recommended Implementation:**
257+
```r
258+
# Example function signature for package developers
259+
your_table_function <- function(data, markdown_cols = NULL, quarto = TRUE) {
260+
# If quarto = TRUE and in Quarto context, apply data-qmd attributes
261+
# to columns specified in markdown_cols
262+
}
263+
```
264+
265+
**Testing Strategy:**
266+
- Test both inside and outside Quarto documents
267+
- Verify that fallback `display` text works correctly
268+
- Test with various Markdown content types (math, links, formatting)
190269

191270
### Using with kableExtra
192271

193-
**kableExtra** is a popular package for creating and styling tables in R. It produces raw HTML but does not have yet specific support for Quarto's HTML table parsing. However, you can use the helper functions to insert Markdown content into the cells, as it allows to insert raw HTML content in the table cells (by setting `escape = FALSE` to keep the raw HTML as-is).
272+
**kableExtra** is a popular package for creating and styling tables in R. It produces raw HTML but does not have specific support for Quarto's HTML table parsing. However, you can use the helper functions to insert Markdown content into the cells, as it allows inserting raw HTML content in table cells (by setting `escape = FALSE` to keep the raw HTML as-is).
194273

195-
So here is a more complex example that combines all these features to create a complete HTML table with Markdown content:
274+
Here is a more complex example that combines all these features to create a complete HTML table with Markdown content:
196275

197276
```{r}
198-
library(quarto)
199277
library(kableExtra)
200278
201279
# Create a data frame with different types of content
@@ -219,25 +297,25 @@ complex_table <- data.frame(
219297
)
220298
221299
# Create and style the table
222-
kbl(complex_table, format = "html", escape = FALSE) %>%
223-
kable_classic() %>%
224-
column_spec(2, width = "40%") %>%
300+
kbl(complex_table, format = "html", escape = FALSE) |>
301+
kable_classic() |>
302+
column_spec(2, width = "40%") |>
225303
row_spec(0, bold = TRUE, background = "#f8f8f8")
226304
```
227305

228306
### Using with **flextable**
229307

230308
By design, **flextable** does not support inserting raw HTML content into its cells. Using the `tbl_qmd_span()` or `tbl_qmd_div()` functions directly in a flextable will not work as expected.
231309

232-
Unfortunately, **flextable** does not yet integrate with Quarto's HTML table parsing features, and does not allow to mark cell content as Markdown to be processed by Quarto.
310+
Unfortunately, **flextable** does not yet integrate with Quarto's HTML table parsing features, and does not allow marking cell content as Markdown to be processed by Quarto.
233311

234312
The Quarto team will be working with **flextable** developers to find a way to support this in the future.
235313

236314
### Using with **gt**
237315

238316
The **gt** package provides a way to create tables with rich formatting.
239317

240-
**gt** allows to insert raw HTML content in the table cells, and it has built-in support for Quarto's HTML table parsing. It uses the `data-qmd` attribute internally to mark cells that contain Markdown content.
318+
**gt** allows inserting raw HTML content in table cells and has built-in support for Quarto's HTML table parsing. It uses the `data-qmd` attribute internally to mark cells that contain Markdown content.
241319

242320
Here is the same table example as above, using **gt** with **quarto** R package functions. `fmt_passthrough()` is used to allow raw HTML content in the table cells, and `escape = FALSE` is set to avoid escaping the HTML content:
243321

@@ -255,7 +333,7 @@ Here is the example with built-in support for Markdown content in **gt**:
255333
data.frame(
256334
Feature = c("Formatting", "Math", "References", "Media"),
257335
Example = c(
258-
c("**Bold**, *italic*, and `code`"),
336+
"**Bold**, *italic*, and `code`",
259337
"$\\int_{a}^{b} f(x) \\, dx$",
260338
"See @tbl-kable-equation for example of a table",
261339
"{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}"
@@ -271,22 +349,22 @@ data.frame(
271349
fmt_markdown(columns = "Example")
272350
```
273351

274-
`gt::fmt_markdown()` is aware of Quarto context and it will internally use the `data-qmd` attribute to render Markdown content correctly when Quarto processes the document.
352+
`gt::fmt_markdown()` is aware of Quarto context and will internally use the `data-qmd` attribute to render Markdown content correctly when Quarto processes the document.
275353

276354
### Using with **tinytable**
277355

278356
From the **tinytable** package website (<https://vincentarelbundock.github.io/tinytable/>):
279-
> `tinytable` is a small but powerful R package to draw beautiful tables in a variety of formats: HTML, LaTeX, Word1, PDF, PNG, Markdown, and Typst.
357+
> `tinytable` is a small but powerful R package to draw beautiful tables in a variety of formats: HTML, LaTeX, Word, PDF, PNG, Markdown, and Typst.
280358
281-
By default, `tinytable` does deactivate Quarto HTML table processing. It is a design choice so that **tinytable** formatting is not affected by Quarto's HTML table processing. So, our previous table would look like this:
359+
By default, `tinytable` deactivates Quarto HTML table processing. This is a design choice so that **tinytable** formatting is not affected by Quarto's HTML table processing. So, our previous table would look like this:
282360

283361
```{r}
284362
library(tinytable)
285363
286364
tt(complex_table)
287365
```
288366

289-
Note that display value for video shortcode is used, as the shortcode is not processed by Quarto in this case.
367+
Note that the display value for the video shortcode is used, as the shortcode is not processed by Quarto in this case.
290368

291369
Quarto HTML table processing can be re-enabled in **tinytable**, and in that case, they will handle the `data-qmd` attribute internally, and functions `tbl_qmd_span()` and `tbl_qmd_div()` will not be needed.
292370

@@ -295,20 +373,20 @@ options(tinytable_quarto_disable_processing = FALSE)
295373
tt(complex_table)
296374
```
297375

298-
Setting the option will opt-in the Quarto HTML table processing for all tables created with **tinytable**. This allows a table using `tbl_qmd_span()` or `tbl_qmd_div()` to be processed correctly by Quarto.
299-
Let's unset option
376+
Setting the option will opt-in to Quarto HTML table processing for all tables created with **tinytable**. This allows a table using `tbl_qmd_span()` or `tbl_qmd_div()` to be processed correctly by Quarto.
377+
Let's unset the option:
300378

301379
```{r}
302380
options(tinytable_quarto_disable_processing = NULL)
303381
```
304382

305-
Note that **tinytable** does support `data-qmd` attributes internally, so functions `tbl_qmd_span()` and `tbl_qmd_div()` are not needed when using **tinytable**. You can use `tt()` function directly with Markdown content in the table cells, and marking the cells as using Quarto Markdown processing.
383+
Note that **tinytable** supports `data-qmd` attributes internally, so functions `tbl_qmd_span()` and `tbl_qmd_div()` are not needed when using **tinytable**. You can use `tt()` function directly with Markdown content in the table cells, and mark the cells as using Quarto Markdown processing.
306384

307385
```{r}
308386
data.frame(
309387
Feature = c("Formatting", "Math", "References", "Media"),
310388
Example = c(
311-
c("**Bold**, *italic*, and `code`"),
389+
"**Bold**, *italic*, and `code`",
312390
"$\\int_{a}^{b} f(x) \\, dx$",
313391
"See @tbl-kable-equation for example of a table",
314392
"{{< video https://www.youtube.com/embed/wo9vZccmqwc >}}"
@@ -326,6 +404,6 @@ data.frame(
326404

327405
## Conclusion
328406

329-
The table helper functions in this package make it easy to include Markdown content in HTML tables when working with Quarto documents. They will be useful to users to get unblocked when using a package that provide HTML tables, and does already support Quarto processing. Hopefully, developers will also find them useful to simplify the process for users of creating tables with rich content. This is already happening with **gt** and **tinytable** packages, which have built-in support for Markdown content in tables by marking the cells with the `data-qmd` attribute, internally for the user.
407+
The table helper functions in this package make it easy to include Markdown content in HTML tables when working with Quarto documents. They are useful for users to get unblocked when using a package that provides HTML tables but doesn't already support Quarto processing. Hopefully, developers will also find them useful to simplify the process for users of creating tables with rich content. This is already happening with **gt** and **tinytable** packages, which have built-in support for Markdown content in tables by marking the cells with the `data-qmd` attribute internally for the user.
330408

331409
For more information about tables in Quarto, see the [Quarto documentation on tables](https://quarto.org/docs/authoring/tables.html#html-tables).

0 commit comments

Comments
 (0)