-
-
Notifications
You must be signed in to change notification settings - Fork 7
/
reference.qmd
114 lines (88 loc) · 5.23 KB
/
reference.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
---
title: Reference
---
## Glossary
Below are terms used in association with The Carpentries Workbench.
[workbench]{#workbench .anchored}
: the collection of three packages used to build Carpentries lessons. NOTE: this
is no longer called the “template”.
[lesson source]{#lesson-source .anchored}
: a collection of standard files and folders generated from a [lesson
template])#template) that [The Workbench](#workbench) uses to build a lesson
website
[lesson website]{#lesson-website .anchored}
: An HTML website built by [The Workbench](#workbench).
[{sandpaper}](https://carpentries.github.io/sandpaper){#sandpaper .anchored}
: the package that lesson contributors interact with. This orchestrates the
building of lessons from markdown/rmarkdown to html
[{pegboard}](https://carpentries.github.io/pegboard){#pegboard .anchored}
: the validator for our lesson content.
[{varnish}](https://carpentries.github.io/varnish){#varnish .anchored}
: html, css, and javascript styling for our lessons.
[carpentries/actions](https://github.com/carpentries/actions){#actions .anchored}
: Automation for deploying and updating our lessons on GitHub
[template]{#template}
: A standard set of files that are used to create a Carpentries lesson. The
lesson author is expected to customise and modify these files with their own
custom lesson content.
[Markdown Lesson Template]{#markdown-lesson-template .anchored}
: <https://bit.ly/new-lesson-md> a GitHub repository template to create a new
lesson written in markdown using The Workbench
[R Markdown Lesson Template]{#r-markdown-lesson-template .anchored}
: <https://bit.ly/new-lesson-rmd> a GitHub repository template to create a new
lesson written in R Markdown using The Workbench
[Official Lessons]{#official-lessons .anchored}
: Lessons within our Official Curriculum that are offered in
Centrally-Organised or Self-Organised workshops. Community Lessons Lessons
that are developed by community members, but are not offered in
centrally-organised workshops
[Toolchain]{#toolchain .anchored}
: A series of software tools that work together to accomplish a specific task.
E.g. The Carpentries Workbench is a toolchain built with R and pandoc to
publish accessible lesson websites from markdown or R Markdown content.
[Styles (aka lesson template)]{#styles .anchored}
: This is the lesson infrastructure established in 2016 and can be found at
<https://github.com/carpentries/styles>. It uses Jekyll for rendering markdown
to HTML with a Make-based workflow. The Carpentries Workbench supersedes this
infrastructure. This particular infrastructure required that the tools and
templates were embedded within the lesson itself, meaning that updates were
often cumbersome.
[Lesson infrastructure]{#lesson-infrastructure .anchored}
: The collection tools and templates required to build Carpentries-style lessons.
[Lesson-transition tool]{#lesson-transition-tool .anchored}
: A custom toolchain that prepared existing lessons to use The Carpentries
Workbench: <https://github.com/carpentries/lesson-transition>. This would
transform markdown syntax from [Kramdown](#kramdown) to [Pandoc-flavoured
markdown](#pandoc-flavoured-markdown) and it would remove commits unrelated
to the lesson content.
[Jekyll](https://jekyllrb.com/){#jekyll .anchored}
: A static site generator that is used by default to build websites on GitHub
from markdown.
[Kramdown]{#kramdown .anchored}
: The default flavour of markdown used by
[Jekyll](#jekyll). It is originally based off of a PHP variant of the
original markdown syntax that is not widely used.
[Pandoc-flavoured markdown]{#pandoc-flavoured-markdown .anchored}
: A style of markdown that is derived from CommonMark and is the basis for the
pandoc document converter <https://pandoc.org/MANUAL.html#pandocs-markdown>.
[Fishtree Attempt](https://github.com/fishtree-attempt){#fishtree-attempt .anchored}
: GitHub organisation to host testing repositories of the transformed lessons.
[Beta Phase](beta-phase.html){#beta-phase .anchored}
: This is the phase in which lessons are tested with maintainers, instructors,
and learners to evaluate any potential snags in the websites that should be
fixed before converting all of our lessons. This is divided into three stages
for each lesson.
[Pre-beta stage (8 weeks)](beta-phase.html#pre-beta){#pre-beta-stage .anchored}
: a snapshot of a lesson is converted to the workbench in a separate github
organisation and hosted on a temporary url
(`preview.carpentries.org/<lesson>`). A banner is hosted on the github URL
indicating a beta test with a link to the new url.
[Beta stage (8 weeks)](beta-phase.html#beta){#beta-stage .anchored}
: a lesson release and archive is created. The lesson is converted to the
workbench and hosted on (preview.carpentries.org/<lesson>). The github URL
hosts the snapshot of the lesson at the given release and has a link to the
new URL, indicating that it is the up-to-date version.
[Release Candidate (24 weeks)](beta-phase.html#pre-release){#release-candidate .anchored}
: The default URL will now show the Workbench version of the lesson and the
styles version of the lesson will be archived. During this time, any
imperfections in the transition are to be addressed by the maintainers.