start lesson object vignette

_pkgdown.yml

@@ -90,6 +90,7 @@ articles:
  - title: "Developer Guides"
    navbar: ~
    contents:
-     - articles/validation
      - intro-xml
      - intro-episode
+     - intro-lesson
+     - articles/validation

man/rmd-fragments/intro-class.Rmd

@@ -0,0 +1,11 @@
+The {pegboard} package facilitates the analysis and manipulation of Markdown and
+R Markdown files by translating them to XML and back again. This extends the
+{tinkr} package (see `vignette("tinkr", package = "tinkr")`) by providing
+additional methods that are specific for Carpentries-style lessons. There are
+two `R6` classes defined in {pegboard}:
+
+ - `Episode` objects that contain the XML data, YAML metadata and extra fields
+   that define the child and parent files for a particular episode. These
+   inherit from the [tinkr::yarn] R6 class. 
+- `Lesson` objects that contain lists of `Episode` objects categorised as 
+   "episodes", "extra", or "children".

man/rmd-fragments/jekyll-syntax.Rmd

@@ -0,0 +1,43 @@
+The former Jekyll syntax used [kramdown-flavoured
+markdown](https://kramdown.gettalong.org/syntax.html), which evolved separately
+from [commonmark](https://spec.commonmark.org/), the syntax that {pegboard} 
+knows and that Pandoc-flavoured markdown extends. One of the key differences 
+with the kramdown syntax is that it used something known as [Inline Attribute 
+Lists (IAL)](https://kramdown.gettalong.org/syntax.html#inline-attribute-lists) to
+help define classes for markdown elements. These elements were formated as
+`{: <attributes>}` where `<attributes>` is replaced by class definitions and
+key/value pairs. They always appear _after_ the relevant block which lead to
+code blocks that looked like this:
+
+````markdown
+~~~
+ls -larth /path/to/dir
+~~~
+{: .language-bash}
+````
+
+Moreover, to achieve the special callout blocks, we used blockquotes that were
+given special classes (which is an accessbility no-no because those blocks were
+not semantic HTML) and the nesting of these block quotes looked like this:
+
+
+````markdown
+> ## Challenge
+> 
+> How do you list all files in a directory in reverse order by the time it was 
+> last updated?
+> 
+> > ## Solution
+> > 
+> > ~~~
+> > ls -larth /path/to/dir
+> > ~~~
+> > {: .language-bash}
+> {: .solution}
+{: .challenge}
+````
+
+One of the biggest challenges with this for authors was that, unless you used an
+editor like vim or emacs, this was difficult to write with all the prefixed 
+blockquote characters and keeping track of which IALs belonged to which block.
+

vignettes/intro-episode.Rmd

@@ -16,15 +16,8 @@ knitr::opts_chunk$set(
 
 ## Introduction
 
-The {pegboard} package facilitates the analysis and manipulation of Markdown and
-R Markdown files by translating them to XML and back again. This extends the
-{tinkr} package by providing additional methods that are specific for 
-Carpentries-style lessons. There are two `R6` classes defined in {pegboard}:
-
- - `Episode` objects that contain the XML data, YAML metadata and extra fields
-   that define the child and parent files for a particular episode
- - `Lesson` objects that contain lists of `Episode` objects categorised as 
-   "episodes", "extra", or "children"
+```{r child="../man/rmd-fragments/intro-class.Rmd"}
+```
 
 This vignette will be discussing the structure of Episode objects, how to 
 query the contents with the {xml2} package, and how to use the methods and 
@@ -49,8 +42,8 @@ library("fs")
 ```
 
 This is what our lesson fragment looks like. It is a fragment because it's main
-purpose is to be used for examples and tests, but it contains the basic structure
-of a lesson that we want. 
+purpose is to be used for examples and tests, but it contains the basic
+structure of a lesson that we want. 
 
 ```{r intro-read-noshow, echo = FALSE}
 dir_tree(lesson_fragment("sandpaper-fragment"), recurse = 1, regex = "site/[^R].*", invert = TRUE)
@@ -317,48 +310,10 @@ written initially as a way to explore the structure of our lessons.
 
 ### The Syntax of Jekyll Lessons
 
-The former Jekyll syntax used [kramdown-flavoured
-markdown](https://kramdown.gettalong.org/syntax.html), which evolved separately
-from [commonmark](https://spec.commonmark.org/), the syntax that {pegboard} 
-knows and that Pandoc-flavoured markdown extends. One of the key differences 
-with the kramdown syntax is that it used something known as [Inline Attribute 
-Lists (IAL)](https://kramdown.gettalong.org/syntax.html#inline-attribute-lists) to
-help define classes for markdown elements. These elements were formated as
-`{: <attributes>}` where `<attributes>` is replaced by class definitions and
-key/value pairs. They always appear _after_ the relevant block which lead to
-code blocks that looked like this:
-
-````markdown
-~~~
-ls -larth /path/to/dir
-~~~
-{: .language-bash}
-````
-
-Moreover, to achieve the special callout blocks, we used blockquotes that were
-given special classes (which is an accessbility no-no because those blocks were
-not semantic HTML) and the nesting of these block quotes looked like this:
 
+```{r child="../man/rmd-fragments/jekyll-syntax.Rmd"}
+```
 
-````markdown
-> ## Challenge
-> 
-> How do you list all files in a directory in reverse order by the time it was 
-> last updated?
-> 
-> > ## Solution
-> > 
-> > ~~~
-> > ls -larth /path/to/dir
-> > ~~~
-> > {: .language-bash}
-> {: .solution}
-{: .challenge}
-````
-
-One of the biggest challenges with this for authors was that, unless you used an
-editor like vim or emacs, this was difficult to write with all the prefixed 
-blockquote characters and keeping track of which IALs belonged to which block.
 
 ### Special methods and active bindings
 

vignettes/intro-lesson.Rmd

@@ -0,0 +1,99 @@
+---
+title: "Introduction to the Lesson Object"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Introduction to the Lesson Object}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+## Introduction
+
+```{r child="../man/rmd-fragments/intro-class.Rmd"}
+```
+
+If you have a list of `Episode` objects, you can achieve _most_ of what you can
+with the lesson objects, because much of the `Lesson` object's function is to
+provide a methods that map over all of the `Episode` object methods. The key
+difference between `Lesson` objects and a list of `Episode` objects is that
+the `Lesson` object will collapse summaries and to map relations between 
+`Episodes` and their children or parent documents.
+
+**Before you read this vignette, please read the vignette on the `Episode` object
+(`vignette("intro-episode", package = "pegboard")`)** so that you can understand
+the methods that come from the `Episode` objects. In this vignette, we will talk
+about the structure of `Lesson` objects, how to use the basic methods of these
+objects, inspecting summaries of source vs built episodes, and assessing the
+lineage of episodes that have parents and/or children documents. But first,
+because of a default parameter, I need to explain a little bit about Jekyll,
+the former lesson infrastructure. 
+
+### A Brief Word About History and Jekyll
+
+Prior to The Workbench, we had the [styles
+repository](https://github.com/carpentries/styles/), which was an all-in-one
+toolbox that built websites with Jekyll. It was colloquially known as the 
+"Lesson Template." It has two major differences to The Workbench: folder 
+structure and syntax.
+
+#### Folder Structure
+
+The folder structure of lessons built with Jekyll was one where content and
+tooling lived side-by-side. This folder structure looked something like this:
+
+
+```{r, jekyll-folders, echo = FALSE}
+writeLines(c(
+  ".",
+  "\U{251C}\U{2500}\U{2500} Gemfile",
+  "\U{251C}\U{2500}\U{2500} Makefile",
+  "\U{251C}\U{2500}\U{2500} _config.yml",
+  "\U{251C}\U{2500}\U{2500} _episodes/",
+  "\U{251C}\U{2500}\U{2500} _episodes_rmd/",
+  "\U{251C}\U{2500}\U{2500} _extras/",
+  "\U{251C}\U{2500}\U{2500} _includes/",
+  "\U{251C}\U{2500}\U{2500} _layouts/",
+  "\U{251C}\U{2500}\U{2500} aio.md",
+  "\U{251C}\U{2500}\U{2500} assets/",
+  "\U{251C}\U{2500}\U{2500} bin/",
+  "\U{251C}\U{2500}\U{2500} fig/",
+  "\U{251C}\U{2500}\U{2500} index.md",
+  "\U{251C}\U{2500}\U{2500} reference.md",
+  "\U{251C}\U{2500}\U{2500} requirements.txt",
+  "\U{2514}\U{2500}\U{2500} setup.md"
+))
+```
+
+When {pegboard} was first written, we initially assumed this folder structure,
+where R Markdown and regular Markdown episodes lived in different folders (and
+more often than not, the outputs of the R Markdown files lived inside the 
+`_episodes/` folder. The main method of organising episodes was by numbers
+embedded in the name of the files.
+
+As The Workbench developed, it was clear that this folder structure needed to
+change, but we needed to keep compatibility with the old lessons because we
+want to ensure that people can independently convert from the old style lessons
+to the new style, thus we added the `jekyll` parameter to the `Lesson` object
+initializer method, and set `jekyll = TRUE` as the default to keep backwards
+compatibility.
+
+#### Syntax
+
+```{r child="../man/rmd-fragments/jekyll-syntax.Rmd"}
+```
+
+## Creating a New Lesson Object
+
+The `Lesson` object is invoked with the [Lesson] `$new()`, method specifying
+whether or not the lesson is derived from Jekyll. 
+
+```{r setup}
+library(pegboard)
+```