| Title: | Glossaries for Markdown and Quarto Documents |
|---|---|
| Description: | Add glossaries to markdown and quarto documents by tagging individual words. Definitions can be provided inline or in a separate file. |
| Authors: | Lisa DeBruine [aut, cre, cph] |
| Maintainer: | Lisa DeBruine <[email protected]> |
| License: | CC BY 4.0 |
| Version: | 1.0.0.9003 |
| Built: | 2025-03-01 03:50:50 UTC |
| Source: | https://github.com/debruine/glossary |
Adds the necessary helper files to an existing quarto book project and gives instructions to edit the _quarto.yml file accordingly.
add_to_quarto( quarto_dir = ".", css_path = "glossary.css", glossary_path = "glossary.yml", script_path = "_setup.R" )add_to_quarto( quarto_dir = ".", css_path = "glossary.css", glossary_path = "glossary.yml", script_path = "_setup.R" )
quarto_dir |
The base directory for your quarto project |
css_path |
The relative path to the css file you want to append the glossary styles to (creates a new file if it doesn't exist), using the quarto_dir as a base directory |
glossary_path |
The relative path to the glossary file, using the quarto_dir as a base directory; if this file does not exist, one will be created |
script_path |
The relative path to a pre-chapter script, using the quarto_dir as a base directory; set to FALSE to omit this step |
The _quarto.yml file is not edited for you because there is currently no way to do this that doesn't remove your formatting and comments from the file.
Since quarto books render each chapter in a separate environment, it is helpful to have a pre-chapter script that does any common setup. The code below will be added to a new or existing pre-chapter script, and this script sourced in the .Rprofile for this project to allow for a persistent glossary (this project .Rprofile will be run instead of your global .Rrofile). Set script_path to FALSE to handle this on your own.
library(glossary)
glossary_path("glossary.yml")
glossary_persistent(TRUE)
No return value, called for side effects.
Display a glossary term with an optional popup of the definition, and add the term to the table created by glossary_table. This function is mainly meant to be used via inline R in R Markdown or quarto documents, e.g.:
`r glossary("Alpha")` does not always have to equal .05.
glossary( term, display = term, def = NULL, add_to_table = TRUE, show = c("term", "def"), popup = glossary_popup(), path = glossary_path() )glossary( term, display = term, def = NULL, add_to_table = TRUE, show = c("term", "def"), popup = glossary_popup(), path = glossary_path() )
term |
The glossary term to link to, can contain spaces |
display |
The text to display (if different than the term) |
def |
The short definition to display on hover and in the glossary table; if NULL, this will be looked up from the file in the |
add_to_table |
whether to add to the table created by |
show |
whether to show the term or just the definition |
popup |
whether to show the popup on "click" or "hover" (or "none"); set default with |
path |
the path to the glossary file, or NULL for local definitions; set default with |
If the path is set to "psyteachr", the glossary term will link to the PsyTeachR glossary. Set show = "def" to just show the definition.
character string
# set glossary path to example file path <- system.file("glossary.yml", package = "glossary") glossary_path(path) glossary("alpha") glossary("alpha", "$\\alpha$") glossary("alpha", def = "The first letter of the Greek alphabet") glossary("alpha", show = "term") glossary("alpha", show = "def")# set glossary path to example file path <- system.file("glossary.yml", package = "glossary") glossary_path(path) glossary("alpha") glossary("alpha", "$\\alpha$") glossary("alpha", def = "The first letter of the Greek alphabet") glossary("alpha", show = "term") glossary("alpha", show = "def")
Write a term and definition to an existing glossary file.
glossary_add(term, def, path = glossary_path(), replace = FALSE)glossary_add(term, def, path = glossary_path(), replace = FALSE)
term |
The term to define |
def |
The definition to add |
path |
The path to the glossary file; set default with |
replace |
Whether to replace an existing definition |
NULL; Called for side effects
# make a new glossary file path <- tempfile("glossary", fileext = ".yml") glossary_path(path, create = TRUE) # add an entry for "joins" glossary_add("joins", "Ways to combine data from two tables") # now you can access the definition glossary("joins")# make a new glossary file path <- tempfile("glossary", fileext = ".yml") glossary_path(path, create = TRUE) # add an entry for "joins" glossary_add("joins", "Ways to combine data from two tables") # now you can access the definition glossary("joins")
Add terms and definitions to table
glossary_add_to_table(gloss)glossary_add_to_table(gloss)
gloss |
a named list(term = def) |
NULL; called for side effects
Load all the definitions in a glossary file, usually for subsequent display using glossary_table
glossary_load_all(path = glossary_path())glossary_load_all(path = glossary_path())
path |
The path to the glossary file; set default with |
NULL; Called for side effects
demo_glossary <- system.file("glossary.yml", package = "glossary") glossary_load_all(demo_glossary) glossary_table(FALSE) # get table as a data framedemo_glossary <- system.file("glossary.yml", package = "glossary") glossary_load_all(demo_glossary) glossary_table(FALSE) # get table as a data frame
Set or get the default glossary path
glossary_path(path, create = FALSE)glossary_path(path, create = FALSE)
path |
the path to the glossary file, or NULL for local definitions |
create |
create a new glossary file if it doesn't exist |
path string if path is NULL
path <- glossary_path() # get current path # create (if doesn't exist) and set path newpath <- tempfile("glossary", fileext = ".yml") glossary_path(newpath, create = TRUE) # set path (assumes file exists) glossary_path(path)path <- glossary_path() # get current path # create (if doesn't exist) and set path newpath <- tempfile("glossary", fileext = ".yml") glossary_path(newpath, create = TRUE) # set path (assumes file exists) glossary_path(path)
Quarto books render each chapter in a separate environment, so you need to set a persistent table if you want to display all glossary items in a table in a separate chapter. Set the persistent table at the top of each chapter, after loading the glossary package, and it will automatically add any glossary entries to the persistent table.
glossary_persistent(path)glossary_persistent(path)
path |
the path to the persistent table, or TRUE for the default table name ("glossary-persistent.yml"), or FALSE for no persistence |
path to persistent table object, or FALSE if not set
p <- glossary_persistent() # get current path # set default persistent table path glossary_persistent(TRUE) # set non-default path glossary_persistent(p)p <- glossary_persistent() # get current path # set default persistent table path glossary_persistent(TRUE) # set non-default path glossary_persistent(p)
Set or get the default popup type
glossary_popup(popup)glossary_popup(popup)
popup |
If NULL, get the current default popup type, or set to one of "click", "hover", or "none" |
string if popup is NULL
# get current popup style popstyle <- glossary_popup() # change popup to click style glossary_popup("click") # change back to original popup style glossary_popup(popstyle)# get current popup style popstyle <- glossary_popup() # change popup to click style glossary_popup("click") # change back to original popup style glossary_popup(popstyle)
Resets the list that collects glossary entries for the table.
glossary_reset()glossary_reset()
NULL; Called for side effects
glossary_reset()glossary_reset()
Set the color and style of the linked in-text terms and pop-up definitions. Colors should be a valid CSS color string, such as "purple" or "#FF0000".
glossary_style( color = "purple", text_decoration = "underline", def_bg = "#333", def_color = "white", inline = TRUE )glossary_style( color = "purple", text_decoration = "underline", def_bg = "#333", def_color = "white", inline = TRUE )
color |
Text color of the linked term |
text_decoration |
Style of the linked term; a valid CSS text-decoration string, such as "none", underline" or "red wavy underline" |
def_bg |
Background color of the definition pop-up |
def_color |
Text color of the definition pop-up |
inline |
If TRUE, includes |
All terms defined with glossary (since the last call to glossary_reset) are added to a list, which this function displays using kable (or outputs as a data frame).
glossary_table(as_kable = TRUE)glossary_table(as_kable = TRUE)
as_kable |
if the output should be a kableExtra table or a data frame |
kable table or data frame
glossary_reset() # add a definition to the table glossary("term", def = "definition", path = NULL) glossary_table() # show table as kable glossary_table(FALSE) # or as a data frameglossary_reset() # add a definition to the table glossary("term", def = "definition", path = NULL) glossary_table() # show table as kable glossary_table(FALSE) # or as a data frame