vignette("intro-lesson", package = "pegboard")
provides information
about working with pegboard::Lesson
objects.Episode
and Lesson
objects have been updated to be
a bit more descriptive and point to the vignettes.Episode$unblock()
method gains the force
argument which will allow the
method to run even if it has previously been run.validate_links()
now differentiates between links and images in reporting
(reported: @joelnitta, #143; fixed: @zkamvar, #144)This release introduces automated processing of {knitr} child files, which enables them to be automatically available for validation and processing.
Episode
class objects gain the children
, parents
, and build_parents
fields which will contain the known relationships between files. Both
children
and parents
represent immediate relationships while
build_parents
represent the most distant ancestor of the object that would
trigger it to build. Note that the parents
fields are only populated for
an Episode
in the context of a Lesson
object.Lesson
class objects gain the children
field which is a list that stores
Episode
objects derived from child files.Episode
objects gain the $has_parents
active binding reporting if the
object has a parent object. This is only used in the context of a Lesson
.Episode
and Lesson
objects gain the $has_children
active binding,
reporting if there are any child episodes in the lesson or episode.Lesson
objects gain the $trace_lineage()
method to return the absolute
paths to all child files from the source path of a given episode if they
exist.make_link_table()
now has a new column called parents
which contains a
list column of the parents (if any) of the files checked$validate_links()
, $validate_divs()
, and $validate_headings()
will now
all process child files by default. Note that $validate_links()
will
report missing files relative to the build parents.$load_built()
method will now load all built markdown content, not just
the episodes.$validate_divs()
method now recognises the spoiler
class of fenced divs
which allow optional/expandable items that are not automatically shown to the
learner (implemented: @tobyhodges, #134)Lesson
objects.
For Jekyll- based lessons, the directory name must end with -workshop
(as
is the standard for workshop overview lessons without episodes), for
sandpaper- based lessons, the config.yaml
file must contain the overview: true
tag (reported: @zkamvar, #118; fixed: @zkamvar, #132, reviewed by
@klbarnes20). These pages are indicated by the $overview
field in the
Lesson
object. For lessons that are not workshop overview lessons, nothing
will change.$validate_links()
no longer throws an error when there are HTML images
embedded in comments (reported: @beastyblacksmith, #130; fixed: @zkamvar,
#131, reviewed by @ErinBecker)$move_objectives()
and $move_questions()
methods no longer
place these blocks as the second element in the markdown. This was
originally implemented when we thought {dovetail} would be our solution to
the lesson infrastructure (and thus needed a setup chunk before any blocks).Lesson
object validators now validate non-episode files
(reported: @zkamvar #110; fixed: @zkamvar #113).$validate_links()
will now respect links to anchors in spans.{tinkr}
's minimum version has been set to 0.2.0 to recognise the release to
CRAN and bring in new bugfixes.$validate_links()
now checks if the URL protocol in an external link matches
a known list of protocols. Those that do not match (e.g. javascript:
and
bitcoin:
) will be flagged. (@zkamvar #109)find_between_nodes()
will get all nodes between two
sibling nodes.fix_links()
function has improved documentation.In preparation for {tinkr} 0.1.0, which changes the path of the default
stylesheet, we are using the tinkr::stylesheet()
convenience function to
access it.
$summary()
method which can summarise counts of elements in the episode.$error
and $output
active bindings$warning
active binding that will show code blocks with the warning
class.$load_built()
method will load the built files if they exist in a
sandpaper lesson.$get()
method which will get any element from any Episode class object
contained within.$summary()
method which will call the $summary()
method for any
Episode class object.muffle_messages()
is an internal function that will muffle any messages
that originate from the {cli} or {pegboard} packages.pbMessage
, which will allow end users/package authors to catch and
manipulate any messages that originate from {pegboard}make_pandoc_alt()
(an internal converter function) will no longer create alt
text from a caption if it contains a URL. This messes with the downstream
validation of image links.fix_sandpaper_links()
now also fixes links that use {{ site.baseurl }}
.fix_links()
now processes links in headers and links with unescaped ampersands
text_to_links()
now processes unescaped ampersandsfind_lesson_links()
no longer expects links to be
strictly in paragraph elements.validate_links()
will no longer flag alt=""
as errors. These indicate
decorative images. That being said, these should be rare in our lessons, but
this is here just in case it's needed.
Source: https://webaim.org/techniques/alttext/#decorativegetOption('sandpaper.links')
is not NULL.getOption("sandpaper.links")
is not NULL (in the context of a {sandpaper}
lesson) and is a valid file, it will be appended to any file read in via
Episode$new()
$validate_links()
no longer throws warnings about short or uninformative
text for link anchors (@zkamvar, #81)validate_divs()
will validate that the divs in an Episode are ones we
expect.This is a soft release of {pegboard} to coincide with the first announcement of The Carpentries Workbench.
get_list_block()
will now select the last block if there are multiple
"keypoints" blocks (@zkamvar, #75)get_list_block()
will now throw a warning if a block does not contain any
list elements (@zkamvar, #74)get_stylesheet()
now escapes spaces and normalizes the windows path to the
tinkr stylesheet before embedding it (@zkamvar, #72)$use_sandpaper()
method for Episode objects will now remove "root" and
"layout" yaml directives (@zkamvar, #68)Images that had attributes added are now post-processed in use_sandpaper()
and
will retain their original attributes.
relative_root_path
with nothing instead on .
, which fixes a bug
introduced with 0.0.0.9028.base_path.html
to define
relative_root_path
are now corrected to no longer include those directives
for links.rmd
flag for the Lesson initializer now does nothing._config.yml
file to parse site-specific liquid template links
to fix #60includes
are
now considered to have valid setup chunks and can have those chunks converted.Episode$handout()
will create trimmed-down R Markdown document with only
challenge blocks and code chunks with purl = TRUE
, that can be passed to
knitr::purl()
for processing into an R code handout.Lesson$handout()
will create a concatenated version of Episode$handout()
.Episode
and Lesson
now return data frames that
contain detailed information for each element and what tests were passed and
what were failed for downstream analysis. Importantly, they all will contain
a column called "node", which points to the exact XML node containing the
link/image/heading for inspection/manipulation.Episode
class now gains the $confirm_sandpaper()
method to bypass the
assumption that all Episodes start as kramdown-formatted documents and will
attempt to label divs in the episode (with a warning if there is no success).Lesson
class will now run the $confirm_sandpaper()
method for all
markdown files if jekyll = FALSE
.Lesson$new()
will now default to the current working directory.get_list_block()
will no longer auto-label divs.make_link_table()
will treat linebreaks in link text as a space character.NOTE: All of these are from (@zkamvar, #44)
$links
and $images
active bindings that
extracts the links and images (markdown and HTML) from the document.make_link_table()
creates a table of links parsed via xml2::url_parse()
with additional information about caption and alternative text (for images).$validate_links()
method, which will validate
links and images for common errors such as not using https and unresolved
relative links.Episode$use_sandpaper()
now converts images to use alt text over captions.
Images that had ![alt](link)
are converted to ![](link){alt='alt'}
because
pandoc uses everything in square brackets to be caption text. NOTE: this now
makes a copy of the XML document.Episode$new()
gains the argument fix_liquid
, which fixes liquid variables
in relative links before they are passed to {tinkr}
(https://github.com/carpentries/pegboard/issues/46)fix_links()
retains their sourcepos
attribute
(fixed in e5508cc9c9a3821381293bdac12647edfbc0608e).Episode$lesson
no longer assumes that the episode is inside a sub-folder
(fixed in 63432ef83ecc41a6aab53fe768e8eaec107278d5).$headings
active binding and the
$validate_headings()
method to validate headings (#23 via #41)show()
, head()
, tail()
, and protect_math()
methods.$unblock()
conversion.{% include links.md %}
is now removed on sandpaper
conversion.jekyll
extras
to handle the sandpaper
non-episodic thingsEpisode$label_divs()
.$label_divs()
no longer modifies the fenced divs.@dtag
labels attached to html_block
and paragraph
elements are now
replaced by <dtag>
elements that live within a custom namespace called
"pegboard". This allows us to avoid manipulating the document paragraph
structure in the case of fenced divs.$get_divs()
now includes the div tags/fences in the output.md:
.expect_moved_yaml()
tests that a yaml element
was successfully moved to the body of the document.$keypoints
and $objectives
now are available and act like $questions
$move_*()
methods will now add an h2 header to the block$move_*()
methods will use pandoc syntax instead of html div blocks.$label_divs()
method now will label any div tags in the episode$move_*
methods will now auto-label div tags$questions
field now returns the questions block or yaml header as a
character vector.@dtag
labels are now in the format div-{n}-{class}
where {n} is the
sequential number in the document and {class} is the type of div.@dtags
is more straightforward and will label the tags
sequentially.The changes in this version largely are enhancements for handling div tags and conversion. See #9 for details
$unblock()
defaults to converting to div tags unless $use_sandpaper()
has been called.$unblock()
will auto-name ALL the divs with {class}-div-{number}$move_*
functions will now name the html_blocks$get_divs()
returns div tags in a named list$challenges
will now find either blocks, divs or code, depending on
the mutations$soltuions
same as challenges (see above)$use_dovetail()
will warn the user if the body is empty$use_sandpaper()
will do the sameJekyll-specific and relative links are now converted as part of use_sandpaper()
.
fix_sandpaper_links()
will fix relative paths and jekyll-specific links
inside of lessons that have not yet otherwise been converted.This version introduces conversions that work together and can be chained to convert an episode from the old Jekyll style to the new {sandpaper} style. Things are still very much in development though.
use_dovetail()
inserts a setup chunk at the top of the fileuse_sandpaper()
converts chunks from their liquid/kramdown syntax to the
commonmark or RMD syntaxmove_*()
will generate a dovetail block or just a plain div block depending
on whether or not use_dovetail()
has been called.remove_output()
does what it says on the tinremove_error()
removes error code blocks$output
and $error
can now grab output and error chunks that were converted
via use_sandpaper()
NEWS.md
file to track changes to the package.