Skip to content

Commit

Permalink
📚 Improve glossary documentation (#619)
Browse files Browse the repository at this point in the history
This now points to RST and gives an example to Sphinx users.

See executablebooks/MyST-NB#544 and #618
  • Loading branch information
rowanc1 authored Sep 26, 2023
1 parent b74fb3c commit 1b97a2e
Showing 1 changed file with 15 additions and 3 deletions.
18 changes: 15 additions & 3 deletions docs/glossaries-and-terms.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,22 @@ You can use {term}`MyST` to create glossaries.

The glossary can be in a different page, as long as it is parsed by your project. See an [example glossary](./glossary.md).

:::{warning} Compatibility with {term}`Sphinx`
The glossary is very similar to {term}`reStructuredText` glossary, but uses [definition lists](#definition-lists) instead of indentation to indicate the terms.
:::{warning} Compatibility with {term}`Sphinx` and {term}`reStructuredText`
:class: dropdown
The glossary is very similar to the [reStructuredText glossary](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#glossary), but uses [definition lists](#definition-lists) instead of indentation to indicate the terms[^drawback]. For working with glossaries in Sphinx, you can use the following syntax:

````markdown
```{glossary}
Term one
An indented explanation of term 1

A second term
An indented explanation of term 2
```
````

[^drawback]: Note that this has a challenge of not being able to have two terms for the same definition.

Note that this has a challenge of not being able to have two terms for the same definition.
:::

## Referencing a Term
Expand Down

0 comments on commit 1b97a2e

Please sign in to comment.