Skip to content

Commit

Permalink
Merge pull request #574 from carpentries/frog-callouts-pandoc3
Browse files Browse the repository at this point in the history 
Fix callout block CSS classes
  • Loading branch information
@froggleston
froggleston authored Mar 5, 2024
2 parents eb009fa + 3d6d487 commit 0deb88a
Show file tree
Hide file tree
Showing 4 changed files with 56 additions and 45 deletions.
9 changes: 9 additions & 0 deletions NEWS.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,12 @@
# sandpaper 0.16.3.9000 (2024-03-05)

## BUG FIX

* Hotfix for pandoc2-to-pandoc3 bump that resulted in CSS deduplication
of section classes for callout blocks
(reported: @bencomp, #470; @ndporter https://github.com/carpentries/workbench/issues/81;
fixed: @froggleston, #574)

# sandpaper 0.16.2 (2023-12-19)

## MISC
Expand Down
3 changes: 2 additions & 1 deletion R/utils-xml.R
View file
Original file line number Diff line number Diff line change
Expand Up @@ -197,7 +197,8 @@ fix_accordions <- function(nodes = NULL) {

fix_callouts <- function(nodes = NULL) {
if (length(nodes) == 0) return(nodes)
callouts <- xml2::xml_find_all(nodes, ".//div[starts-with(@class, 'callout ')]")
# fix for https://github.com/carpentries/sandpaper/issues/470
callouts <- xml2::xml_find_all(nodes, ".//div[starts-with(@class, 'callout ')] | .//div[@class='callout']")
h3 <- xml2::xml_find_all(callouts, "./div/h3")
translations <- get_callout_translations()
# https://github.com/carpentries/sandpaper/issues/556
Expand Down
52 changes: 26 additions & 26 deletions vignettes/data-flow.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,18 +8,18 @@ vignette: >
%\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "##"
collapse = TRUE,
comment = "##"
)
```

## Introduction

This is a vignette that is designed for R package developers who are looking to
understand how the data flows between the lesson source and the final website.
I am assuming that the person reading this has familiarity with
I am assuming that the person reading this has familiarity with
[R packaging](https://r-pkgs.org/) and [R
environments](https://r-pkgs.org/data.html#sec-data-state).

Expand All @@ -38,12 +38,12 @@ knew at the time. I now know that it might be better to use global environments
instead. The implementation of this was originally done in [pull request
#248](https://github.com/carpentries/sandpaper/pull/248), which was trying to
deduplicate code after the release of version 0.1.0, which was a massive push
after finally getting the new website layout.
after finally getting the new website layout.

The flow of data I lay out here could all live in the same package-level
environment (or even a package-level R6 object) instead of being implemented as
function factories, but that's a refactor for another day and another
maintainer.
maintainer.

### Two Sources of Metadata

Expand Down Expand Up @@ -111,7 +111,7 @@ writeLines("```")
You can see that it contains `{{{ head }}}`, `{{{ header }}}`, `{{{ navbar }}}`,
`{{{ content }}}` and `{{{ footer }}}`. These are all the results of the other
rendered templates. For example, here's the `head.html` template, which defines
the content that goes in the HTML `<head>` tag (defining titles, metadata,
the content that goes in the HTML `<head>` tag (defining titles, metadata,
stylesheets, and JavaScript):

````{r varnish-template-head, echo = FALSE, results = "asis"}
Expand All @@ -126,7 +126,7 @@ The templates used by {varnish} will take metadata from one of two sources:
1. a `_pkgdown.yaml` file that defines global metadata like language (see the
[pkgdown metadata section](#pkgdown-metadata) for details.
2. a list of values passed to the `pkgdown::render_page()` function. These
values can be both global and local.
values can be both global and local.

These get inserted into the template via the `pkgdown::render_page()` function
where the contents of the `_pkgdown.yaml` file are inserted into the data list
Expand Down Expand Up @@ -198,7 +198,7 @@ It is a special object because when a lesson is set with this object, it will
additionally set the _other_ global data.

When {sandpaper} is loaded, the List Store and Lesson Store objects are created
and live in the {sandpaper} namespace as long as the session is active.
and live in the {sandpaper} namespace as long as the session is active.

```{r lesson-store}
snd <- asNamespace("sandpaper")
Expand All @@ -211,7 +211,7 @@ names(some_lesson)
All of these metadata are collected and stored in memory before the lesson is
built (triggered during `validate_lesson()`), which are accessible via the
objects defined by the internal `sandpaper:::set_globals()`. Here I will set
up an example lesson that I will use to demonstrate these global variables.
up an example lesson that I will use to demonstrate these global variables.
Please note that I will be using internal functions in this demonstration. These
internal functions are not guaranteed to be stable outside of the context of
{sandpaper}. Using the `asNamespace("sandpaper")` function allows me to create
Expand All @@ -224,7 +224,7 @@ snd <- asNamespace("sandpaper")

```{r, create-example, message = FALSE}
# create a new lesson
lsn <- create_lesson(tempfile(), name = "An Example Lesson",
lsn <- create_lesson(tempfile(), name = "An Example Lesson",
rstudio = TRUE, open = FALSE, rmd = FALSE)
# add a new episode
create_episode_md(title = "First Example", add = TRUE, path = lsn, open = FALSE)
Expand Down Expand Up @@ -280,14 +280,14 @@ cascade:

```{r vl-tree, echo = FALSE, eval = getRversion() >= "4.0"}
funs <- c(
vl = "validate_lesson()",
tl = "this_lesson()",
vl = "validate_lesson()",
tl = "this_lesson()",
sv = ".store$valid()",
ggd = "gert::git_diff()",
ggs = "gert::git_status()",
ggl = "gert::git_log()",
ggs = "gert::git_status()",
ggl = "gert::git_log()",
pl = "pegboard::Lesson$new()",
ss = ".store$set()",
ss = ".store$set()",
sg = "set_globals()",
srl = "set_resource_list()",
res = ".resources$set()",
Expand All @@ -311,16 +311,16 @@ labels[to_lab] <- cli::col_cyan(cli::style_bold(labels[to_lab]))
vltree <- data.frame(
fn = funs,
calls = I(list(
vl = funs["tl"],
tl = list(funs["sv"], funs["pl"], funs["ss"]),
vl = funs["tl"],
tl = list(funs["sv"], funs["pl"], funs["ss"]),
sv = list(funs["ggd"], funs["ggs"], funs["ggl"]),
ggd = character(0),
ggs = character(0),
ggl = character(0),
ggl = character(0),
pl = character(0),
ss = list(funs["sg"]),
ss = list(funs["sg"]),
sg = list(funs["im"], funs["sl"], funs["srl"], funs["cs"], funs["crd"], funs["lgs"],
funs["igs"]),
funs["igs"]),
srl = list(funs["grl"], funs["res"]),
res = character(0),
grl = list(funs["gc"]),
Expand Down Expand Up @@ -349,7 +349,7 @@ them.
## Lesson Storage

This function stores the `pegboard::Lesson` object and is responsible for
initialising and resetting the variable cache.
initialising and resetting the variable cache.

```{r store-get}
snd <- asNamespace("sandpaper")
Expand Down Expand Up @@ -380,7 +380,7 @@ snd$.store$valid(lsn)
The metadata is used to store the content of `config.yaml` and to provide
computed metadata for a lesson that is included in the footer as a JSON-LD
object, which is useful for indexing. Note that this metadata must be
duplicated for each page to give the correct URL and identifiers.
duplicated for each page to give the correct URL and identifiers.

```{r metadata}
snd <- asNamespace("sandpaper")
Expand Down Expand Up @@ -409,7 +409,7 @@ snd$.resources$get()
The rest are global and local variables that are recorded in the
`instructor_globals` and `learner_globals`. These are copied for each page and
updated with local data (e.g. the sidebar needs to include headings for the
current page).
current page).

```{r globals}
snd <- asNamespace("sandpaper")
Expand Down Expand Up @@ -447,7 +447,7 @@ whisker::whisker.render("Edit this page: {{ translate.EditThisPage }}",
This is key to building lessons in other languages, regardless of your default
language. The lesson author sets the `lang:` config key to the two-letter
language code that the lesson is written in. This gets passed to the
`set_language()` function, which modifies the translations inside the global
`set_language()` function, which modifies the translations inside the global
data, but it does not modify the language of the user session:

```{r set-language-es}
Expand Down Expand Up @@ -478,7 +478,7 @@ whisker::whisker.render("Edit this page: {{ translate.EditThisPage }}",
## pkgdown metadata

Another source of metadata is that created for the pkgdown in a file called
`site/_pkgdown.yaml`.
`site/_pkgdown.yaml`.

```{r yaml, results="asis", echo = FALSE, comment = ""}
writeLines("```yaml")
Expand Down
37 changes: 19 additions & 18 deletions vignettes/include-child-documents.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,12 @@ vignette: >
%\VignetteEncoding{UTF-8}
---

```{r, setup, include = FALSE}
```{r setup, include = FALSE}
# comment to fix https://github.com/r-lib/pkgdown/issues/1843
knitr::opts_chunk$set(
collapse = TRUE,
compact = TRUE, # https://github.com/r-lib/pkgdown/issues/1843
comment = "#>"
collapse = TRUE,
compact = TRUE,
comment = "#>"
)
# setup the lesson to include a child document
Expand Down Expand Up @@ -70,7 +71,7 @@ as you wish, but when you create child files, be sure the following two rules
apply:

1. The child documents live in the `files/` folder under their parent folders
2. The reference to child files is _relative_ to the parent file.
2. The reference to child files is _relative_ to the parent file.

For example, you have a file structure like this:

Expand Down Expand Up @@ -113,8 +114,8 @@ lsn_obj$children[[1]]$show()

````

This means that when `episodes/introduction.Rmd` is built,
`episodes/files/child.Rmd` will also be built, evaulating the `sessionInfo()`.
This means that when `episodes/introduction.Rmd` is built,
`episodes/files/child.Rmd` will also be built, evaulating the `sessionInfo()`.
So the resulting markdown document will look like this:

````markdown
Expand All @@ -136,13 +137,13 @@ and `data/`) are copied over from their source folders to `site/built/`. This
allows us to build the R Markdown files using `site/built/` as the working
directory which accomplishes two things:

1. The default sandpaper folder structure is flattened for the website.
1. The default sandpaper folder structure is flattened for the website.
2. any files the R Markdown document creates or deletes will not affect the
source files of the project

For example, let's say we added a chunk to our source R Markdown folder that
will create a file in the `data/` directory called "time.txt" and then reads in
the contents of that file.
the contents of that file.


````markdown
Expand All @@ -151,7 +152,7 @@ the contents of that file.
ep <- lsn_obj$episodes[[1]]
txt <- c(
"```{r setup, echo = FALSE}",
"writeLines(format(Sys.time()), 'data/time.txt')",
"writeLines(format(Sys.time()), 'data/time.txt')",
"cat(paste0('The time is: ', readLines('data/time.txt')))",
"```"
)
Expand Down Expand Up @@ -202,15 +203,15 @@ final parent of the child document where the output will eventually end up.
Let's say you wanted to refererence a figure `episodes/fig/one.png` and a link
to a document for learners `learners/info.md` from the child document, but
instead it's located at `episodes/files/children/child.Rmd`, which is built by
`episodes/introduction.Rmd`.
`episodes/introduction.Rmd`.

```{r setup-new-child, echo = FALSE, comment = "#"}
lsn_obj <- snd$this_lesson(lsn)
withr::with_dir(fs::path(lsn, "episodes", "files"), {
fs::dir_create("children")
fs::file_touch("../fig/one.png")
writeLines(c(
"---",
"---",
"title: info",
"---",
"\nthis is a test file\n"
Expand All @@ -223,7 +224,7 @@ withr::with_dir(fs::path(lsn, "episodes", "files"), {
withr::with_dir(lsn, fs::dir_tree("./episodes/"))
ep <- lsn_obj$episodes[[1]]
code <- ep$code
xml2::xml_set_attr(code[[5]], "child",
xml2::xml_set_attr(code[[5]], "child",
sQuote("files/children/child.Rmd", q = 2)
)
ep$write(fs::path(lsn, "episodes"), format = "Rmd")
Expand All @@ -233,7 +234,7 @@ Here is a link to [the info document](../learners/info.md)
![example](fig/one.png){alt='example figure'}
")
lsn_obj$children[[1]]$write(fs::path(lsn, "episodes/files/children"),
lsn_obj$children[[1]]$write(fs::path(lsn, "episodes/files/children"),
format = "Rmd"
)
```
Expand All @@ -252,8 +253,8 @@ lsn_obj$episodes[[1]]$tail(15)
In `episodes/files/children/child.Rmd`, under [internal link
rules][internal-link-ref], you you should reference these
resources with `fig/one.png` and `../learners/info.md`, which are _in the
context of the build parent directory (in this case, `episodes/`)_, as
demonstrated here:
context of the build parent directory (in this case, `episodes/`)_, as
demonstrated here:

[internal-link-ref]: https://carpentries.github.io/sandpaper-docs/episodes.html#internal-links)

Expand All @@ -269,9 +270,9 @@ lsn_obj$children[[1]]$show()
Again, the reason for this is because when the document gets built, the result
is all in the context of the parent document in the `site/built` directory[^1]\:

[^1]: there is a caveat to this paradigm, on translation to HTML, all links
[^1]: there is a caveat to this paradigm, on translation to HTML, all links
that begin with `../[folder]/` prefixes have those stripped in the final
version of the site.
version of the site.


```{r show-built-assets, echo = FALSE, comment = "#"}
Expand Down

0 comments on commit 0deb88a

Please sign in to comment.