Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] Automated processing and page generation of glosario links in lessons #612

Open
wants to merge 9 commits into
base: main
Choose a base branch
from

Conversation

froggleston
Copy link
Contributor

@froggleston froggleston commented Oct 17, 2024

Implementation description

This PR is a work in progress to implement a core part of the Mellon Foundation grant to the Carpentries to automatically generate glossary pages in lessons from links to Glosario terms.

Configuration

Firstly, to enable this behaviour, the following line needs to be added to a lesson's config.yaml:

glosario: true

Lesson content

For example, the spreadsheet-ecology-lesson contains the following markdown:

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.

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).

Secondly, a lesson maintainer/contributor will 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>)

Example output

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:

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 second example:

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 with sandpaper::serve(), this will produce the following output:

{7E3AE97A-968F-4F1B-B17E-14D265F322FF}

In the first example, {{ glosario.data_structure }} adds a data_structure link as a superscript inline. In the second example, it looks more like a typical markdown link.

In either case, sandpaper will find these links and add them to a global page in your lesson called glossary.html:
{F167F923-1821-4F1A-844F-0A86D1553F77}

Things left to do

  • Replace the current reference.md#glossary implementation, or add the glosario links to the same page?
  • What to do with terms that are included as links but are not in the Glosario glossary itself, e.g. literal in the example above
  • Tests!

@froggleston froggleston self-assigned this Nov 21, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant