Update documentation on extends

docs/abbreviations.yml

@@ -0,0 +1,40 @@
+version: 1
+project:
+
+  abbreviations:
+    # Alphabetical order
+    AMS: American Mathematical Society
+    API: Application Programming Interface
+    AST: Abstract Syntax Tree
+    CLI: Command Line Interface
+    CRediT: Contributor Roles Taxonomy
+    CSS: Cascading Style Sheet
+    CSV: comma-separated values
+    DOI: Digital Object Identifier
+    ESM: ECMAScript Modules
+    GPU: Graphics Processing Unit
+    HTML: Hypertext Markup Language
+    ID: Identifier
+    ISNI: International Standard Name Identifier
+    JATS: Journal Article Tag Suite
+    JSON: JavaScript Object Notation
+    LTS: Long Term Support
+    MyST: Markedly Structured Text
+    NISO: National Information Standards Organization
+    OA: Open Access
+    PDF: Portable Document Format
+    PID: Persistent Identifier
+    POSIX: Portable Operating System Interface
+    REES: Reproducible Execution Environment Specification
+    ROR: Research Organization Registry
+    RRID: Research Resource Identifier
+    RST: reStructuredText
+    SPDX: Software Package Data Exchange
+    TLA: Three Letter Acronym
+    TOC: table of contents
+    TPU: Tensor Processing Unit
+    URL: Uniform Resource Locator
+    VoR: Version of Record
+    WASM: WebAssembly
+    YAML: Yet Another Markup Language
+    XML: Extensible Markup Language

docs/admonitions.md

@@ -5,15 +5,12 @@ thumbnail: ./thumbnails/admonitions.png
 ---
 
 Callouts, or "admonitions", highlight a particular block of text that exists slightly apart from the narrative of your page, such as a note or a warning.
-For example, try changing the following example of a `{tip}` admonition to a `{warning}`:
 
-```{myst}
-:::{tip}
-Try changing `tip` to `warning`!
-:::
+```{tip} 
+See the different admonitions below and try it yourself in the next admonition!
 ```
 
-In MyST we call these kinds of directives {myst:directive}`admonitions <admonition>`, however, they are almost always used through their _named_ directives, like {myst:directive}`note` or {myst:directive}`danger`. There are ten kinds[^docutils-admonitions] of admonitions available:
+In MyST we call these kinds of directives {myst:directive}`admonitions <admonition>`, however, they are almost always used through their _named_ directives, like {myst:directive}`note` or {myst:directive}`danger`. There are ten kinds[^docutils-admonitions] of admonitions available by default, and several others by the use of [plugins](./plugins.md):
 
 ```{list-table} Named admonitions that can be used as directives
 :label: admonitions-list
@@ -31,6 +28,16 @@ In MyST we call these kinds of directives {myst:directive}`admonitions <admoniti
 
 [^docutils-admonitions]: These admonitions are the same as those used in [docutils](https://docutils.sourceforge.io/docs/ref/rst/directives.html#specific-admonitions) and Sphinx.
 
+For example, try changing the following example of a `{tip}` admonition to a `{warning}`:
+
+```{myst}
+:::{tip}
+Try changing `tip` to `warning`!
+:::
+```
+
+
+
 See below for a demo of each admonition in the default theme.
 
 `````{tab-set}
@@ -134,7 +141,7 @@ GitHub Markdown transforms blockquotes that start with a bold `Note` or text wit
 
 ::::{tip} Compatibility with Pandoc & Quarto
 :class: dropdown
-In Quarto/Pandoc Markdown admonitions are styled with special classes like `{.callout-note}` or `{.callout-tip}`).
+In Quarto/Pandoc Markdown admonitions are styled with special classes (e.g. `{.callout-note}` or `{.callout-tip}`).
 If you are using Jupyter Book V1 or Sphinx documentation, use an {myst:directive}`admonition` directive with the specific class, for example:
 
 ```{myst}
@@ -197,6 +204,7 @@ Admonitions can additionally be styled as `simple`, and can optionally hide the
 ```{myst}
 :::{important} Magic
 :class: simple
+
 This is a magic cat. It casts a luck spell on you that lasts an hour. \
 **つ( ･ω･｡)つ━☆・*。**
 :::

docs/analytics.md

@@ -5,7 +5,8 @@ description: Add Google Analytics or Plausible to your MyST website with a site
 thumbnail: ./thumbnails/analytics.png
 ---
 
-There are no tracking cookies or analytics added to a MyST site by default, however, you may want to know more about basic analytics for your domain when you deploy it. There are two analytics tracking codes that MyST site templates currently supports:
+There are no tracking cookies or analytics added to a MyST site by default. 
+However, there are two analytics tracking codes that MyST site templates currently supports:
 
 1. [Google Analytics](https://marketingplatform.google.com/about/analytics/); and
 2. [Plausible](https://plausible.io/), which is privacy-friendly alternative to Google.

docs/asides.md

@@ -4,7 +4,8 @@ short_title: Asides & Margins
 description: Asides provide an easy way to represent content that is only indirectly related to the article's main content, such as in the sidebar or margin.
 ---
 
-Asides provide an easy way to represent content that is only indirectly related to the article's main content. Where supported, MyST will attempt to display an {myst:directive}`aside` _as close as possible_ but separately from the main article, such as in the side-margin.
+Asides provide an easy way to represent content that is only indirectly related to the article's main content.
+Where supported, MyST will attempt to display an {myst:directive}`aside` _as close as possible_ but separately from the main article, such as in the side-margin.
 
 ```{aside} Margin Content
 Here’s some margin content! It was created by using the {myst:directive}`margin` directive in a Markdown, we can include images:
@@ -15,8 +16,12 @@ or any other sort of content!
 ```
 
 ```markdown
-:::{aside} An Optional Title
-This is an aside. It is not entirely relevant to the main article.
+:::{aside} Margin Content
+Here’s some margin content! It was created by using the {myst:directive}`margin` directive in a Markdown, we can include images:
+
+![](https://github.com/rowanc1/pics/blob/main/sunset.png)
+
+or any other sort of content!
 :::
 ```
 
@@ -28,6 +33,7 @@ Many of the features on this page are experimental and may change at any time.
 
 These elements can conflict with the document outline when they are both competing for the margin space (see [#170](https://github.com/jupyter-book/myst-theme/issues/170)).
 
+There is, yet, no plugin available transforming this directive into a Typst pdf.
 :::
 
 % Using bold here, until we fix #170

docs/authorship.md

@@ -1,10 +1,12 @@
 # Authorship and attribution
 
-You can bundle information about the authors of each page in a MyST project, as well as metadata about them. For example, their institutional affiliations, funding, etc. 
+You can bundle information about the authors of each page in a MyST project, as well as metadata about them.
+For example, their institutional affiliations, funding, etc. 
 
 ## How to set author information
 
-Author information is set with [MyST frontmatter](./frontmatter.md). You can set this either in **`myst.yml`** (in which case, they will apply to all documents in a MyST project), or in the **page frontmatter** (in which case they'll just apply to that page).
+Author information is set with [MyST frontmatter](./frontmatter.md).
+You can set this either in **`myst.yml`** (in which case, they will apply to all documents in a MyST project), or in the **page frontmatter** (in which case they'll just apply to that page).
 
 For example, the examples below show frontmatter for authors and [author affiliations](#affiliations) in frontmatter of an `article.md` file, and in `myst.yml`:
 
@@ -51,7 +53,8 @@ See [the `authors` frontmatter reference](#frontmatter:authors) for a list of al
 
 ### Re-use author information across repositories and projects
 
-By [extending MyST configuration files](#composing-myst-yml) you can store author information in one place and re-use it across many other locations. This allows you to define a source of truth for authorship and affiliations, and reference that over time. For example:
+By [extending MyST configuration files](#composing-myst-yml) you can store author information in one place and re-use it across many other locations.
+This allows you to define a source of truth for authorship and affiliations, and reference that over time. For example:
 
 In one file, you'd define all the author affiliations that are relevant to your project:
 
@@ -88,7 +91,7 @@ And in each of your project `myst.yml` files, you can extend this authorship fil
 :filename: myst.yml
 version: 1
 extends:
-  - ./authors.yml  # OR, the URL of this file if not hosted locally
+  - ./authors.yml  # Or, the URL of this file if not hosted locally
 project:
   authors:
     - person_a
@@ -108,18 +111,19 @@ Page content...
 ```
 
 (affiliations)=
-
 ## Affiliations
 
-You can create an affiliation directly by adding it to an author.  It can be as simple as a single string.
+You can create an affiliation directly by adding it to an author.
+It can be as simple as a single string.
 
 ```yaml
 authors:
   - name: Marissa Myst
     affiliation: University of British Columbia
 ```
 
-You can also add much more information to any affiliation, such as a ROR, ISNI, or an address. A very complete affiliations list for an author at the University of British Columbia is:
+You can also add much more information to any affiliation, such as a ROR, ISNI, or an address.
+A very complete affiliations list for an author at the University of British Columbia is:
 
 ```yaml
 authors:
@@ -141,7 +145,8 @@ authors:
     affiliation: ubc
 ```
 
-Notice how you can use an `id` to avoid writing this out for every coauthor. Additionally, if the affiliation is a single string and contains a semi-colon `;` it will be treated as a list.
+Notice how you can use an `id` to avoid writing this out for every coauthor.
+Additionally, if the affiliation is a single string and contains a semi-colon `;` it will be treated as a list.
 
 If you use a string that is not recognized as an already defined affiliation in the project or article frontmatter, an affiliation will be created automatically and normalized so that it can be referenced:
 
@@ -192,7 +197,8 @@ To do so, use the following fields in an entry for either `author` or the `affil
 ![](#table-frontmatter-social-links)
 
 (other-contributors)=
-
 ## Reviewers, Editors, Funding Recipients
 
-Other contributors besides authors may be listed elsewhere in the frontmatter. These include `reviewers`, `editors`, and [funding](#frontmatter:funding) award `investigators` and `recipients`. For all of these fields, you may use a full [author object](#frontmatter:authors), or you may use the string `id` from an existing author object defined elsewhere in your frontmatter.
+Other contributors besides authors may be listed elsewhere in the frontmatter.
+These include `reviewers`, `editors`, and [funding](#frontmatter:funding) award `investigators` and `recipients`.
+For all of these fields, you may use a full [author object](#frontmatter:authors), or you may use the string `id` from an existing author object defined elsewhere in your frontmatter.

docs/citations.md

@@ -5,23 +5,31 @@ description: Add academic citations to your documents easily, have hover-referen
 thumbnail: ./thumbnails/citations.png
 ---
 
-Citations automatically show up in your site, including a references section at the bottom of the page. These citations are able to be clicked on to see more information, like the abstract. There are two different ways to add citations to your documents: (1) adding a Markdown link to a [DOI](wiki:Digital_object_identifier); and (2) by adding a BibTeX file, which can be exported from any reference manager, and adding a `cite` role to your content.
+Citations automatically show up in your site, including a references section at the bottom of the page.
+These citations are able to be clicked on to see more information, like the abstract.
+There are two different ways to add citations to your documents: 
+1. adding a Markdown link to a [DOI](wiki:Digital_object_identifier); and 
+2. by adding a BibTeX file, which can be exported from any reference manager, and adding a `cite` role to your content.
 
 (doi-links)=
-
 ## Simple Referencing with a DOI Link
 
-Link to any DOI in your Markdown files or Jupyter Notebooks by including a link to the DOI. Provided the `DOI` is formatted correctly, this will be transformed during the build process to a citation with a pop-up panel on hover like this: [Cockett, 2022](https://doi.org/10.5281/zenodo.6476040), and the reference information will be automatically added to the reference section at the bottom of your notebook (see below👇).
+Link to any DOI in your Markdown files or Jupyter Notebooks by including a link to the DOI.
+Provided the `DOI` is formatted correctly, this will be transformed during the build process to a citation with a pop-up panel on hover like this: [Cockett, 2022](https://doi.org/10.5281/zenodo.6476040), and the reference information will be automatically added to the reference section at the bottom of your notebook (see below 👇).
 
 ```md
 This is a link in Markdown: [Cockett, 2022](https://doi.org/10.5281/zenodo.6476040).
 ```
 
 It is also possible to drop the link text, that is:\
 `<doi:10.5281/zenodo.6476040>` or `[](doi:10.5281/zenodo.6476040)`,\
-which will insert the citation text in the correct format (e.g. adding an italic "_et al._", etc.). If the DOI is present on a citation from a BibTeX file in your project, that citation will be used. Otherwise, the citation data for these DOIs will be downloaded from `https://doi.org` once and cached to a local file in the `_build` directory. This cache may be cleared with `myst clean --cache`.
+which will insert the citation text in the correct format (e.g. adding an italic "_et al._", etc.).
+If the DOI is present on a citation from a BibTeX file in your project, that citation will be used.
+Otherwise, the citation data for these DOIs will be downloaded from `https://doi.org` once and cached to a local file in the `_build` directory.
+This cache may be cleared with `myst clean --cache`.
 
-Providing your DOIs as full links has the advantage that on other rendering platforms (e.g. GitHub), your citation will still be shown as a link. If you have many citations, however, this will slow down the build process as the citation information is fetched dynamically.
+Providing your DOIs as full links has the advantage that on other rendering platforms (e.g. GitHub), your citation will still be shown as a link.
+If you have many citations, however, this will slow down the build process as the citation information is fetched dynamically.
 
 :::{note} Dealing with complex DOIs
 :class: dropdown
@@ -41,19 +49,21 @@ For DOIs with multiple slashes in the identifier you also have to use the full h
 
 ### Writing DOIs to BibTeX
 
-If you encounter problems fetching DOIs from `https://doi.org`, for example the downloaded citation does not include all the data you expect or requests to `https://doi.org` are failing on an automated continuous integration platform, you may write your DOI citations to file using the MyST command
+If you encounter problems fetching DOIs from `https://doi.org`, for example the downloaded citation does not include all the data you expect or requests to `https://doi.org` are failing on an automated continuous integration platform, you may write your DOI citations to file using the MyST command:
 
 ```bash
 myst build --doi-bib
 ```
 
-This will generate a BibTeX file `myst.doi.bib` which you may then rename, edit, and save to your project. On subsequent builds, the DOIs will be loaded from this file rather than fetched remotely.
+This will generate a BibTeX file `myst.doi.bib` which you may then rename, edit, and save to your project.
+On subsequent builds, the DOIs will be loaded from this file rather than fetched remotely.
 
 ## Including BibTeX
 
 A standard way of including references for $\LaTeX$ is using <wiki:BibTeX>, you can include a `*.bib` file or files in the same directory as your content directory for the project. These will provide the reference keys for that project.
 
-If you want to explicitly reference which BibTeX files to use, as well as what order to resolve them in, you can use the `bibliography` field in your frontmatter, which is a string array of local or remote files. This will load the files in order specified.
+If you want to explicitly reference which BibTeX files to use, as well as what order to resolve them in, you can use the `bibliography` field in your frontmatter, which is a string array of local or remote files.
+This will load the files in order specified.
 
 ```yaml
 bibliography:
@@ -66,7 +76,11 @@ The remote BibTeX can be helpful for working with reference managers that suppor
 ## Markdown Citations
 
 You can add citations to any BibTeX entry using the citation key preceded by an `@`, for example, `@author2023`.
-This syntax follows the [pandoc citation syntax](https://pandoc.org/MANUAL.html#citation-syntax). Multiple citations can be grouped together with square brackets, separated with semi-colons. It is also possible to add a prefix or suffix to parenthetical citations, for example, `[e.g. @author2023, chap. 3; @author1995]`. To add a suffix to a narrative citation, follow the citation with the suffix in square brackets, for example, `@author2023 [chap. 3]`. As with a link to a DOI, you can also use the DOI directly instead of the BibTeX key.
+This syntax follows the [pandoc citation syntax](https://pandoc.org/MANUAL.html#citation-syntax).
+Multiple citations can be grouped together with square brackets, separated with semi-colons.
+It is also possible to add a prefix or suffix to parenthetical citations, for example, `[e.g. @author2023, chap. 3; @author1995]`.
+To add a suffix to a narrative citation, follow the citation with the suffix in square brackets, for example, `@author2023 [chap. 3]`.
+As with a link to a DOI, you can also use the DOI directly instead of the BibTeX key.
 
 ```{list-table} Examples of Markdown citations
 :header-rows: 1
@@ -99,7 +113,8 @@ This syntax follows the [pandoc citation syntax](https://pandoc.org/MANUAL.html#
 
 ## Citation Roles
 
-MyST also provides a number of roles for compatibility with Sphinx and Jupyter Book V1. To create a citation role in Markdown, use either a parenthetical or textual citation:
+MyST also provides a number of roles for compatibility with Sphinx and Jupyter Book V1.
+To create a citation role in Markdown, use either a parenthetical or textual citation:
 
 ```md
 This is a parenthetical citation {cite:p}`cockett2015`.