rmarkdown breaks heading anchors for Pandoc > 2.8

[maelle]

For Pandoc > 2.8 rmarkdown adds a HTML dependency on a script that removes all attributes from headings. https://github.com/rstudio/rmarkdown/blob/9c1498806fef286f3891238a8298e064969c8aec/R/html_dependencies.R#L423

Therefore it removes the "hasAnchor" class that's needed to have working heading anchors. 😢

I noticed the missing anchors in articles as I was working on #1536 but it's unrelated. Locally I use Pandoc 2.11.12. The preview of that PR doesn't show the problem, nor the pkgdown dev/production websites, as the GHA workflow uses an older Pandoc version.

cc @cderv

We could remove the dependency in one of the HTML tweaks, if a fix doesn't happen upstream (and if a fix happens upstream, we'll have to increase the rmarkdown minimal version in DESCRIPTION so this issue is useful here).

[cderv]

I think we need to revise this tweak that was included for a fix because of Pandoc change in 2.8 that may have been fix in later version. I'll look at that.

[hadley]

@cderv did this behaviour change in rmarkdown?

[cderv]

No, not yet. We did not focus on rmarkdown work for a long time now, and I still need to have a look. I can't remember exactly why this fix is needed for Pandoc 2.9 (meaning what would break if we remove it)

[hadley]

To fix this, maybe build_rmarkdown_format() should override the pre_processor() from html_document_base() to do its own thing. Maybe something like this:

  pre_processor <- function(metadata, input_file, runtime, knit_meta,
                            files_dir, output_dir) {

    args <- c()

    # use files_dir as lib_dir if not explicitly specified
    if (is.null(lib_dir))
      lib_dir <<- files_dir

    # copy supplied output_dir (for use in post-processor)
    output_dir <<- output_dir

    # resolve and inject extras, including dependencies specified by the format
    # and dependencies specified by the user (via extra_dependencies)
    format_deps <- list()
    format_deps <- append(format_deps, html_dependency_header_attrs())
    format_deps <- append(format_deps, extra_dependencies)

    extras <- html_extras_for_document(knit_meta, runtime, dependency_resolver, format_deps)
    args <- c(args, pandoc_html_extras_args(extras, self_contained, lib_dir, output_dir))

    preserved_chunks <<- extract_preserve_chunks(input_file)

    # a lua filters added if pandoc2.0
    args <- c(args, pandoc_lua_filters(c("pagebreak.lua", "latex-div.lua")))

    args
  }

It would be pretty hacky though, because we'd have to get all the environments right and then do some tricks to stop R CMD check complaining. Maybe a better approach would be to surgically remove the call to html_dependency_header_attrs()?

Ooooh, actually we could probably just tweak the environment of the preprocessor so it finds a html_dependency_header_attrs() that returns NULL.

We should also bump the version of pandoc installed on GHA so we're more likely to spot these problems in the future.

[cderv]

FWIW, we have also merge the PR in rmarkdown mentioned in #1798.

Setting

options(rmarkdown.html_dependency.header_attr = FALSE)

will now be a way to prevent adding the HTML dependency with the JS script that remove class from headers for Pandoc 2.9+.

[salim-b]

Setting

options(rmarkdown.html_dependency.header_attr = FALSE)

will now be a way to prevent adding the HTML dependency with the JS script that remove class from headers for Pandoc 2.9+.

This option could simply be set right before calling rmarkdown::render() here:

pkgdown/R/rmarkdown.R

Line 29 in e72fc30

function(...) rmarkdown::render(...),

i.e. replacing L29 with:

      function(...) {
        options(rmarkdown.html_dependency.header_attr = FALSE)
        rmarkdown::render(...)
      },