You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[Glosario](https://glosario.carpentries.org) is the Carpentries data science glossary that is developed by the international community, providing terms, definitions and translations to make lessons more accessible.
1096
+
1097
+
{sandpaper} can automatically generate glossary links in lessons from links to Glosario terms in lesson content markdown.
1098
+
1099
+
### Configuration
1100
+
1101
+
Firstly, to enable this behaviour, the `glosario` key needs to be added to a lesson's `config.yaml`.
1102
+
1103
+
For automatic retrieval of the latest `glossary.yml` from Glosario's GitHub repository, set:
1104
+
1105
+
```yaml
1106
+
glosario: true
1107
+
```
1108
+
1109
+
For manual retrieval from a local (e.g. working on your lesson offline) or remote location (e.g. providing a specific Glosario version), supply a string relative/absolute path or URL to the config:
1110
+
1111
+
```yaml
1112
+
# load a glossary from a local file using an absolute path
1113
+
glosario: "/path/to/your/glossary.yml"
1114
+
1115
+
# load a glossary from a local file using path relative to the lesson
1116
+
glosario: "../glossary.yml"
1117
+
1118
+
# load a glossary from a remote location
1119
+
glosario: "https://foo.com/glossary.yml"
1120
+
```
1121
+
1122
+
### Lesson content
1123
+
1124
+
For example, the [datacarpentry/spreadsheet-ecology-lesson](https://github.com/datacarpentry/spreadsheet-ecology-lesson/blob/main/episodes/01-format-data.md) contains the following markdown:
1125
+
1126
+
```
1127
+
The most common mistake made is treating spreadsheet programs like lab notebooks, that is, relying on context,
1128
+
notes in the margin, spatial layout of data and fields to convey information. As humans, we can (usually) interpret
1129
+
these things, but computers don't view information the same way, and unless we explain to the computer what
1130
+
every single thing means (and that can be hard!), it will not be able to see how our data fits together.
1131
+
1132
+
Using the power of computers, we can manage and analyze data in much more effective and faster ways, but to
1133
+
use that power, we have to set up our data for the computer to be able to understand it (and computers are very literal).
1134
+
```
1135
+
1136
+
A lesson maintainer/contributor can add placeholders into the main content of lessons that sandpaper will subsequently process.
1137
+
1138
+
Sandpaper understands links to Glosario terms in two ways, either a template-style term, or a hard link to the term page, i.e.:
When using the template-style term, sandpaper will automatically generate the URL link using the language specified in the `config.yaml``lang` setting.
1148
+
1149
+
When using the markdown link style, sandpaper will automatically replace the `en/` in the link with the language specified in the `config.yaml``lang` setting.
1150
+
1151
+
For example, if the `config.yaml` language is set to `lang: de`:
If the term is not available in that language, a warning will be printed when the lesson builds, and it will default back to English.
1160
+
1161
+
::::::::::::::::::::::
1162
+
1163
+
### Example output
1164
+
1165
+
In the first example, to add a glosario link to the term `data structure` at the URL `https://glosario.carpentries.org/en/#data_structure`, the markdown becomes:
1166
+
1167
+
```
1168
+
The most common mistake made is treating spreadsheet programs like lab notebooks, that is, relying on context,
1169
+
notes in the margin, spatial layout of data and fields to convey information. As humans, we can (usually) interpret
1170
+
these things, but computers don't view information the same way, and unless we explain to the computer what
1171
+
every single thing means (and that can be hard!), it will not be able to see how our data fits together. This is called
1172
+
the data structure {{ glosario.data_structure }}.
1173
+
```
1174
+
1175
+
Similarly, to add a link using the inline markdown link syntax, the markdown becomes:
1176
+
1177
+
```
1178
+
Using the power of computers, we can manage and analyze data in much more effective and faster ways, but to
1179
+
use that power, we have to set up our data for the computer to be able to understand it
1180
+
(and computers are very [literal](https://glosario.carpentries.org/en/#literal)).
1181
+
```
1182
+
1183
+
Once the lesson is built, this will produce the following output:
1184
+
1185
+
{alt='Screenshot of a lesson with a Glosario link as a superscript and an inline link.'}
1186
+
1187
+
In the first example, `{{ glosario.data_structure }}` adds a `data_structure` link as a superscript inline.
1188
+
1189
+
In the second example, a typical markdown link will be inserted.
1190
+
1191
+
In either case, sandpaper will find these links and add them to the global `reference.md` page in your lesson, built as `reference.html`, and linked in the top lesson menu as `Glossary`:
1192
+
1193
+
{alt='Screenshot of a lesson with Glosario links in the Glossary reference page.'}
1194
+
1195
+
### Unavailable terms
1196
+
1197
+
Users will receive a warning when using terms that are not in the currently selected config.yaml language for the lesson:
1198
+
1199
+
1092
1200
:::::::::::::::: keypoints :::::::::::::::::::::
1093
1201
1094
1202
- Use `.Rmd` files for lessons even if you don't need to generate any code
@@ -1104,4 +1212,3 @@ Cool, right?
1104
1212
current working proposal is to call these "chapters".
1105
1213
[^worry]: Do not worry if you aren't comfortable yet, that's what we will show
0 commit comments