Better support of YAML 1.2 for written YAML by this package using yaml R package following 1.1 spec (#272)

* use yaml::verbatim_logical directly

* Handle string with leading 0 parsed as octal in Quarto's YAML 1.2

- Add function to quote strings following yaml R package pattern
- Automatically quote the string that could be considered as octal in YAML 1.2
- Add tests for the function

* Add to NEWS and bump version

* Add to pkgdown

* Use yaml package in example

* Adapt snapshot test for width in CLI

Author: cderv

DESCRIPTION

@@ -31,7 +31,7 @@ Imports:
     tools,
     utils,
     xfun,
-    yaml
+    yaml (>= 2.3.10)
 Suggests: 
     bslib,
     callr,

NAMESPACE

@@ -45,6 +45,7 @@ export(theme_colors_gt)
 export(theme_colors_plotly)
 export(theme_colors_thematic)
 export(write_yaml_metadata_block)
+export(yaml_quote_string)
 import(rlang)
 importFrom(cli,cli_abort)
 importFrom(cli,cli_inform)

NEWS.md

@@ -1,5 +1,10 @@
 # quarto (development version)
 
+- Improved YAML 1.2 compatibility features to ensure proper parsing by Quarto's js-yaml parser. 
+  - The `yaml_quote_string()` function allows explicit control over string quoting in YAML output.
+  - `write_yaml_metadata_block()` automatically handles data corruption prevention from leading zero strings like `"029"` that would be misinterpreted as octal numbers (becoming `29`) (thanks, @Mosk915, quarto-dev/quarto-cli#12736, #242). Boolean values are also correctly formatted as lowercase (`true`/`false`) instead of YAML 1.1 variants like `yes`/`no`. 
+  - This change also benefits other functions writing YAML like `quarto_render()` when using `metadata=` or `execute_params=` arguments.
+
 - Package is now licenced MIT like Quarto CLI.
 
 - Added `has_parameters()` function to detect whether Quarto documents use parameters. The function works with both knitr and Jupyter engines: for knitr documents (.qmd), it checks for a "params" field in the document metadata; for Jupyter notebooks (.ipynb), it detects cells tagged with "parameters" using papermill convention. This enables programmatic identification of parameterized documents for automated workflows and document processing (#245).

R/metadata.R

@@ -27,13 +27,44 @@
 #' If no metadata is provided (empty `...` and `NULL` or empty `.list`),
 #' the function returns `NULL` without generating any output.
 #'
-#' **Important**: When using this function in Quarto documents, you must set
-#' the chunk option `output: asis` (or `#| output: asis`) for the metadata
-#' block to be properly processed by Quarto.
-#'
 #' This addresses the limitation where Quarto metadata must be static and
 #' cannot be set dynamically from R code during document rendering.
 #'
+#' ## YAML 1.2 Compatibility:
+#' To ensure compatibility with Quarto's YAML 1.2 parser (js-yaml), the function
+#' automatically handles two key differences between R's yaml package (YAML 1.1)
+#' and YAML 1.2:
+#'
+#' ### Boolean values:
+#' R logical values (`TRUE`/`FALSE`) are converted to lowercase
+#' YAML 1.2 format (`true`/`false`) using [yaml::verbatim_logical()]. This prevents
+#' YAML 1.1 boolean representations like `yes`/`no` from being used.
+#'
+#' ### String quoting:
+#' Strings with leading zeros that contain digits 8 or 9 (like `"029"`, `"089"`)
+#' are automatically quoted to prevent them from being parsed as octal numbers,
+#' which would result in data corruption (e.g., `"029"` becoming `29`).
+#' Valid octal numbers containing only digits 0-7 (like `"0123"`) are handled
+#' by the underlying \pkg{yaml} package.
+#'
+#' For manual control over string quoting behavior, use [yaml_quote_string()].
+#'
+#' ## Quarto Usage:
+#' To use this function in a Quarto document, create an R code chunk with
+#' the `output: asis` option:
+#'
+#' ```
+#' ```{r}
+#' #| output: asis
+#' write_yaml_metadata_block(admin = TRUE, version = "1.0")
+#' ```
+#' ```
+#'
+#' Without the `output: asis` option, the YAML metadata block will be
+#' displayed as text rather than processed as metadata by Quarto.
+#'
+#' @inherit yaml_character_handler seealso
+#'
 #' @examples
 #' \dontrun{
 #' # In a Quarto document R chunk with `#| output: asis`:
@@ -47,6 +78,12 @@
 #'   timestamp = Sys.Date()
 #' )
 #'
+#' # Strings with leading zeros are automatically quoted for YAML 1.2 compatibility
+#' write_yaml_metadata_block(
+#'   zip_code = "029",    # Automatically quoted as "029"
+#'   build_id = "0123"    # Quoted by yaml package (valid octal)
+#' )
+#'
 #' # Use with .list parameter
 #' metadata_list <- list(version = "1.0", debug = FALSE)
 #' write_yaml_metadata_block(.list = metadata_list)
@@ -65,20 +102,8 @@
 #' # :::
 #' }
 #'
-#' @section Quarto Usage:
-#' To use this function in a Quarto document, create an R code chunk with
-#' the `output: asis` option:
-#'
-#' ```
-#' ```{r}
-#' #| output: asis
-#' write_yaml_metadata_block(admin = TRUE, version = "1.0")
-#' ```
-#' ```
-#'
-#' Without the `output: asis` option, the YAML metadata block will be
-#' displayed as text rather than processed as metadata by Quarto.
-#'
+#' @seealso [yaml_quote_string()] for explicitly controlling which strings are quoted
+#'   in YAML output when you encounter edge cases that need manual handling.
 #'
 #' @export
 write_yaml_metadata_block <- function(..., .list = NULL) {

R/utils.R

@@ -3,15 +3,103 @@ relative_to_wd <- function(path) {
   rmarkdown::relative_to(getwd(), path)
 }
 
+#' Add quoted attribute to strings for YAML output
+#'
+#' This function allows users to explicitly mark strings that should be quoted
+#' in YAML output, giving full control over quoting behavior.
+#'
+#' This is particularly useful for special values that might be misinterpreted
+#' as \pkg{yaml} uses YAML 1.1 and Quarto expects YAML 1.2.
+#'
+#' The `quoted` attribute is a convention used by [yaml::as.yaml()]
+#'
+#' @param x A character vector or single string
+#' @return The input with quoted attributes applied
+#' @examples
+#' yaml::as.yaml(list(id = yaml_quote_string("1.0")))
+#' yaml::as.yaml(list(id = "1.0"))
+#'
+#' @export
+yaml_quote_string <- function(x) {
+  if (!is.character(x)) {
+    cli::cli_abort("yaml_quote_string() only works with character vectors")
+  }
+
+  result <- vector("list", length(x))
+  for (i in seq_along(x)) {
+    val <- x[i]
+    attr(val, "quoted") <- TRUE
+    result[[i]] <- val
+  }
+
+  if (length(result) == 1) {
+    return(result[[1]])
+  }
+
+  result
+}
+
+is_valid_yaml11_octal <- function(val) {
+  # Check if the value is a valid YAML 1.1 octal number
+  # Valid octals are 0o[0-7]+, but we only quote those with leading zeros
+  # that contain digits 8 or 9, which are invalid in octal, as they
+  # would not be quoted already by the R yaml package.
+  # YAML 1.1 spec for int: https://yaml.org/type/int.html
+  invalid <- !is.na(val) &&
+    val != "" &&
+    val != "0" &&
+    grepl("^0[0-9]+$", val) &&
+    grepl("[89]", val)
+  !invalid
+}
+
+#' YAML character handler for YAML 1.1 to 1.2 compatibility
+#'
+#' This handler bridges the gap between R's yaml package (YAML 1.1) and
+#' js-yaml (YAML 1.2) by quoting strings with leading zeros that would be
+#' misinterpreted as octal numbers.
+#'
+#' According to YAML 1.1 spec, octal integers are `0o[0-7]+`. The R yaml
+#' package only quotes valid octals (containing only digits 0-7), but js-yaml
+#' attempts to parse ANY leading zero string as octal, causing data corruption
+#' for invalid octals like "029" → 29.
+#'
+#' @seealso [YAML 1.1 int spec](https://yaml.org/type/int.html)
+#'
+#' @param x A character vector
+#' @return The input with quoted attributes applied where needed
+#' @keywords internal
+yaml_character_handler <- function(x) {
+  apply_quote <- function(x) {
+    # Skip if already has quoted attribute (user control via yaml_quote_string())
+    if (!is.null(attr(x, "quoted")) && attr(x, "quoted")) {
+      return(x)
+    }
+    # Quote leading zero strings that are NOT valid octals (YAML 1.1 vs 1.2 gap)
+    # Valid octals contain only digits 0-7, invalid ones contain 8 or 9
+    if (!(is_valid_yaml11_octal(x))) {
+      attr(x, "quoted") <- TRUE
+    }
+    return(x)
+  }
+  # For single elements, process directly
+  if (length(x) == 1) {
+    return(apply_quote(x))
+  } else {
+    # For vectors, process each element and return as list to preserve attributes
+    result <- vector("list", length(x))
+    for (i in seq_along(x)) {
+      result[[i]] <- apply_quote(x[i])
+    }
+    return(result)
+  }
+}
+
 # Specific YAML handlers
 # as quarto expects YAML 1.2 and yaml R package supports 1.1
 yaml_handlers <- list(
-  # Handle yes/no from 1.1 to 1.2
-  # https://github.com/vubiostat/r-yaml/issues/131
-  logical = function(x) {
-    value <- ifelse(x, "true", "false")
-    structure(value, class = "verbatim")
-  }
+  logical = yaml::verbatim_logical,
+  character = yaml_character_handler
 )
 
 #' @importFrom yaml as.yaml

_pkgdown.yml

@@ -67,11 +67,17 @@ reference:
   contents:
   - starts_with("tbl_qmd_")
 
+- title: "YAML Helpers"
+  desc: >
+    These functions are used to help with YAML metadata in Quarto documents:
+  contents:
+  - write_yaml_metadata_block
+  - yaml_quote_string  
+
 - title: "Miscellaneous"
   desc: >
     These functions are used to help with Quarto documents and projects:
   contents:
-  - write_yaml_metadata_block
   - add_spin_preamble
   - qmd_to_r_script
   - detect_bookdown_crossrefs

man/write_yaml_metadata_block.Rd

@@ -486,17 +486,16 @@
       -- File: '<test_file_basename>' --
       
       -- Theorem Block Unlabeled references: 
-      * Line 2 ('<test_file_basename>:2'): `` ```{theorem name="Pythagorean theorem"}
-      `` -> `Manual conversion required: Use ::: {#thm-<id>} syntax. See
+      * Line 2 ('<test_file_basename>:2'): `` ```{theorem name="Pythagorean theorem"} `` -> `Manual
+      conversion required: Use ::: {#thm-<id>} syntax. See
       https://quarto.org/docs/authoring/cross-references.html#theorems-and-proofs`
       
       i Summary of conversion requirements:
       * 1 Theorem Block Unlabeled reference
       ! Theorem environments require manual restructuring
       Bookdown old syntax WITHOUT label: ```{theorem chunk_name}
       Quarto syntax: :::{#thm-label}
-      See:
-      <https://quarto.org/docs/authoring/cross-references.html#theorems-and-proofs>
+      See: <https://quarto.org/docs/authoring/cross-references.html#theorems-and-proofs>
       
 
 # detects theorem div syntax correctly