Add class

The following functions do the job of adding class to appropriate tags. Package xml2 should be installed.

Main function arguments are:

• xpath - String containing an xpath (1.0) expression (use "//pre//span" for code highlighting tags).
• pattern - Regular expression for tags’ text of interest.
• new_class - String for class to add.
• path - Path to folder with html files (default to “docs”).

xml_add_class_pattern <- function(xpath, pattern, new_class, path = "docs") {
  # Find HTML pages
  html_files <- list.files(
    path = "docs",
    pattern = "\\.html",
    recursive = TRUE,
    full.names = TRUE
  )

  lapply(html_files, function(file) {
    page <- xml2::read_html(file, encoding = "UTF-8")

    matched_nodes <- xml_find_all_patterns(page, xpath, pattern)
    if (length(matched_nodes) == 0) {
      return(NA)
    }

    xml_add_class(matched_nodes, new_class)

    xml2::write_html(page, file, format = FALSE)
  })

  invisible(html_files)
}

# Add class `new_class` to nodes
xml_add_class <- function(x, new_class) {
  output_class <- paste(xml2::xml_attr(x, "class"), new_class)
  mapply(xml2::xml_set_attr, x, output_class, MoreArgs = list(attr = "class"))

  invisible(x)
}

# Find appropriate tags
# To find <span> inside <pre> use `xpath = "\\pre\\span"`.
xml_find_all_patterns <- function(x, xpath, pattern, ns = xml2::xml_ns(x)) {
  res <- xml2::xml_find_all(x, xpath, ns)
  is_matched <- grepl(pattern, xml2::xml_text(res))

  res[is_matched]
}

For convenience one can define function high_pipe() for adding class pp to all <span> inside <pre> with text containing %>%:

high_pipe <- function(path = "docs", new_class = "pp") {
  xml_add_class_pattern("//pre//span", "%>%", new_class, path)
}

So typical usage is as follows:

• Run pkgdown::build_site().
• Run highdown::high_pipe() (with working directory being package root).

Add custom CSS rules

For adding custom CSS rules in pkgdown site create file pkgdown/extra.css in package root and edit it. For example, to make %>% bold write the following:

.pp {font-weight: bold;}

Add custom JavaScript

To add custom JavaScript code to pkgdown site one should create and modify file pkgdown/extra.js in package root. Go here for code that initializes highlight.js and registers default R language parsing rules.

Tweak reference page

For highlight.js to work, code should be wrapped in <pre><span class="r"> tags. However, reference pages use only <pre>. To tweak these pages use the following function (with working directory being package root):

tweak_ref_pages <- function() {
  # Find all reference pages
  ref_files <- list.files(
    path = "docs/reference/",
    pattern = "\\.html",
    recursive = TRUE,
    full.names = TRUE
  )

  lapply(ref_files, add_code_node)

  invisible(ref_files)
}

add_code_node <- function(x) {
  page <- paste0(readLines(x), collapse = "\n")

  # Regular expression magic for adding <code class = "r"></code>
  page <- gsub('(<pre.*?>)', '\\1<code class = "r">', page)
  page <- gsub('<\\/pre>', '<\\/code><\\/pre>', page)

  invisible(writeLines(page, x))
}

Note that as for 2017-10-27 this still can cause incorrect highlighting if some actual code is placed just after comment.

Add highlight.js CSS rules

Edit pkgdown/extra.css for highlight.js classes. For template with Idea style along with R default classes look here.