markdown source builds

Auto-generated via `{sandpaper}`
Source  : 806faa9
Branch  : main
Author  : Robert Davey <robertdavey@carpentries.org>
Time    : 2025-08-08 12:52:11 +0000
Message : Merge pull request #243 from carpentries/frog-glosario-docs-1

Update docs with glosario usage

Author: actions-user

config.yaml

@@ -0,0 +1,92 @@
+#------------------------------------------------------------
+# Values for this lesson.
+#------------------------------------------------------------
+
+# Which carpentry is this (swc, dc, lc, or cp)?
+# swc: Software Carpentry
+# dc: Data Carpentry
+# lc: Library Carpentry
+# cp: Carpentries (to use for instructor traning for instance)
+carpentry: 'cp'
+
+# Overall title for pages.
+title: 'Introduction to The Carpentries Workbench'
+
+# Date the lesson was created (this is empty by default)
+created: ~
+
+# Comma-separated list of keywords for the lesson
+keywords: 'static site, lesson template, markdown, R, software'
+
+# Life cycle stage of the lesson
+# possible values: pre-alpha, alpha, beta, stable
+life_cycle: 'beta'
+
+# License of the lesson
+license: 'CC-BY 4.0'
+
+# Link to the source repository for this lesson
+source: 'https://github.com/carpentries/sandpaper-docs/'
+
+# Default branch of your lesson
+branch: 'main'
+
+# Who to contact if there are any issues
+contact: 'tobyhodges@carpentries.org'
+
+# Navigation ------------------------------------------------
+#
+# Use the following menu items to specify the order of
+# individual pages in each dropdown section. Leave blank to
+# include all pages in the folder.
+#
+# Example -------------
+#
+# episodes:
+# - introduction.md
+# - first-steps.md
+#
+# learners:
+# - setup.md
+#
+# instructors:
+# - instructor-notes.md
+#
+# profiles:
+# - one-learner.md
+# - another-learner.md
+
+# Order of episodes in your lesson
+episodes:
+- introduction.md
+- episodes.Rmd
+- editing.md
+- example.Rmd
+- deployment.md
+- update.md
+- pull-request.md
+
+# Information for Learners
+learners:
+- reference.md
+- setup.md
+- github-pat.md
+- component-guide.md
+- migrating-from-styles.md
+- style.md
+
+# Information for Instructors
+instructors:
+- instructor-notes.md
+
+# Learner Profiles
+profiles:
+- maintainer.md
+- instructor.md
+
+# Customisation ---------------------------------------------
+#
+# This space below is where custom yaml items (e.g. pinning
+# sandpaper and varnish versions) should live
+
+

episodes.md

@@ -14,6 +14,7 @@ exercises: 2
 - What syntax do you use to write links?
 - How do you include images?
 - How do you include math?
+- How do you include Glosario terms?
 
 ::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -1082,13 +1083,110 @@ pie(
 
 ## Math
 
-One of our episodes contains $\LaTeX$ equations when describing how to create
-dynamic reports with {knitr}, so we now use mathjax to describe this:
+One of our episodes contains $\LaTeX$ equations when describing how to create dynamic reports with {knitr}, so we now use mathjax to describe this:
 
 `$\alpha = \dfrac{1}{(1 - \beta)^2}$` becomes: $\alpha = \dfrac{1}{(1 - \beta)^2}$
 
 Cool, right?
 
+
+## Glosario Terms
+
+[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.
+
+{sandpaper} can automatically generate glossary links in lessons from links to Glosario terms in lesson content markdown.
+
+### Configuration
+
+Firstly, to enable this behaviour, the `glosario` key needs to be added to a lesson's `config.yaml`.
+
+For automatic retrieval of the latest `glossary.yml` from Glosario's GitHub repository, set:
+
+```yaml
+glosario: true
+```
+
+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:
+
+```yaml
+# load a glossary from a local file using an absolute path
+glosario: "/path/to/your/glossary.yml"
+
+# load a glossary from a local file using path relative to the lesson
+glosario: "../glossary.yml"
+
+# load a glossary from a remote location
+glosario: "https://foo.com/glossary.yml"
+```
+
+### Lesson content
+
+A lesson maintainer/contributor can add placeholders into the main content of lessons that sandpaper will subsequently process.
+
+Sandpaper understands links to Glosario terms in two ways, either a template-style term, or a hard link to the term page, i.e.:
+
+- `{{ glosario.<term> }}`
+- `[<term>](https://glosario.carpentries.org/en/#<term>)`
+
+:::::::::::::: callout
+
+## Automatic language selection
+
+When using the template-style term, sandpaper will automatically generate the URL link using the language specified in the `config.yaml` `lang` setting.
+
+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.
+
+For example, if the `config.yaml` language is set to `lang: de`:
+
+`[data_structure](https://glosario.carpentries.org/en/#data_structure)`
+
+will be replaced with:
+
+`[data_structure](https://glosario.carpentries.org/de/#data_structure)`
+
+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.
+
+::::::::::::::::::::::
+
+### Example output
+
+To look at a specific example, the [datacarpentry/spreadsheet-ecology-lesson](https://github.com/datacarpentry/spreadsheet-ecology-lesson/blob/main/episodes/01-format-data.md) can be edited to include Glosario links.
+
+To add a glosario link to the term `data structure` at the URL `https://glosario.carpentries.org/en/#data_structure`, the markdown becomes:
+
+```
+The most common mistake made is treating spreadsheet programs like lab notebooks, that is, relying on context,
+notes in the margin, spatial layout of data and fields to convey information. As humans, we can (usually) interpret
+these things, but computers don't view information the same way, and unless we explain to the computer what
+every single thing means (and that can be hard!), it will not be able to see how our data fits together. This is called
+the data structure {{ glosario.data_structure }}.
+```
+
+Similarly, to add a link using the inline markdown link syntax, the markdown becomes:
+
+```
+Using the power of computers, we can manage and analyze data in much more effective and faster ways, but to
+use that power, we have to set up our data for the computer to be able to understand it
+(and computers are very [literal](https://glosario.carpentries.org/en/#literal)).
+```
+
+Once the lesson is built, this will produce the following output:
+
+![Example of superscript and inline Glosario link generation](fig/glosario-link-example.png){alt='Screenshot of a lesson with a Glosario link as a superscript and an inline link.'}
+
+In the first example, `{{ glosario.data_structure }}` adds a `data_structure` link as a superscript inline.
+
+In the second example, a typical markdown link will be inserted.
+
+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`:
+
+![Example of automatic inclusion of Glosario links in the Glossary page](fig/glosario-glossary-page.png){alt='Screenshot of a lesson with Glosario links in the Glossary reference page.'}
+
+### Unavailable terms
+
+Users will receive a warning when using terms that are not in the currently selected config.yaml language for the lesson:
+
+
 :::::::::::::::: keypoints :::::::::::::::::::::
 
 - Use `.Rmd` files for lessons even if you don't need to generate any code
@@ -1104,4 +1202,3 @@ Cool, right?
   current working proposal is to call these "chapters".
 [^worry]: Do not worry if you aren't comfortable yet, that's what we will show
   you in this episode!
-

fig/glosario-glossary-page.png

@@ -5,7 +5,7 @@
 "index.md" "4d117199b579f6901292749f1a414a00" "site/built/index.md" "2025-08-08"
 "links.md" "a7ea11385a9d821b8f57edb0951c83ca" "site/built/links.md" "2025-08-08"
 "episodes/introduction.md" "b1ca0d51bfee1538beabc08f46b389cf" "site/built/introduction.md" "2025-08-08"
-"episodes/episodes.Rmd" "4f9401544dcfcd6d0ba5b61dca806f04" "site/built/episodes.md" "2025-08-08"
+"episodes/episodes.Rmd" "58f17a3eb4fd778714d9ed0487ed71f7" "site/built/episodes.md" "2025-08-08"
 "episodes/editing.md" "8c96f675957e4af4f62aea13fb1d799e" "site/built/editing.md" "2025-08-08"
 "episodes/example.Rmd" "215e3c4ed500fef3410f040349fb0a73" "site/built/example.md" "2025-08-08"
 "episodes/deployment.md" "f15377cac190ef5435a60d074aa8aeb3" "site/built/deployment.md" "2025-08-08"