DOCS: Improving citations and panels (#1085)

docs/content/citations.md

@@ -13,12 +13,11 @@ kernelspec:
 # References and citations
 
 Because `jupyter-book` is built on top of {term}`Sphinx`,
-there are many ways to reference content, including the excellent
-[sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/)
-extension that allows you to include citations and a bibliography with your book.
+there are many ways to reference content within your book (or even across other books, or Sphinx websites). This page has several examples of what you can reference and how to accomplish it.
 
 :::{tip}
-When debugging your book build, the following options can be helpful:
+You can check for missing references when building a Jupyter Book.
+To do so, use the following options:
 
 ```bash
 jupyter-book build -W -n --keep-going docs/
@@ -29,60 +28,42 @@ but will still attempt to run the full build (`--keep-going`),
 so that you can see all errors in one run.
 :::
 
-(content:references)=
-## Cross-references and labels
-
-Labels are a way to add tags to parts of your content so that you can reference them
-later on. This is helpful if you want to quickly insert links to other
-parts of your book. Labels can be added before major elements of a page,
-such as titles or figures.
-
-To add a label, use the following pattern **before** the element you wish
-to label:
-
-```md
-(my-label)=
-# The thing to label
-```
-
-For example, we've added the following label above the header for this section with:
-
-```md
-(content:references)=
-## Cross-references and labels
-```
-
-You can insert cross-references to labels in your content with the following syntax: `` {ref}`label-text` ``.
-For example, the syntax `` {ref}`content:references` `` results in a link to this section like so: {ref}`content:references`.
+## Referencing overview
 
-### Referencing content from your book
-
-There are a few ways to reference content from your book, depending on what kind of
-content you'd like to reference. Here is a quick overview of some common options:
+Referencing is accomplished with **roles** or with **markdown link syntax**, depending on your use-case.
+There are a few ways to reference content from your book, depending on what kind of content you'd like to reference.
+Here is a quick overview of some common roles for referencing:
 
 * `{ref}` is used to reference section labels that you define or figures with a `name` value
-* `{numref}` is used to provide *numbered* references to figures or headers
+* `{numref}` is used to provide *numbered* references to figures, tables, or headers
 * `{doc}` is used to reference other files in your book
 * `{eq}` is used to reference equations that have been given a `label` value
 
-:::{tip}
+:::{admonition,tip} Choosing your own link text
 You can reference a section label through ``{ref}`label` `` or ``{ref}`some text <label>` ``.
 Documents can be referenced through ``{doc}`path/to/document` `` or ``{doc}`some text <path/to/document>` ``
 :::
 
+### Numbered references
+
+To add a **numbered reference** to a table, use the `{numref}` role. If you wish to use custom text, add `%s` as a placeholder for the number.
+See the examples in each section below for usage.
+
+### Referencing with markdown link syntax
+
 If you wish to use Markdown style syntax, then MyST Markdown will try to find a reference,
 from any of the above reference types (and more!).
-This actually has an advantage, in that you can used nested syntax, for example:
+This has an advantage, in that you can used nested markdown syntax in your text, for example:
 
 ```md
-[A **_reference_** to a page](./myst.md)
+[A **bolded _reference_** to a page](./myst.md)
 
 [A reference to a header](content:references)
 ```
 
 produces
 
-[A **_reference_** to a page](./myst.md)
+[A **bolded _reference_** to a page](./myst.md)
 
 [A reference to a header](content:references)
 
@@ -96,7 +77,7 @@ will link to a section and use its header text as the link text itself:
 
 [](./myst.md)
 
-:::{tip}
+:::{admonition,tip} Internval vs. External URLs
 You can control how MyST Markdown distinguishes between internal references and external URLs in your `_config.yml`.
 For example,
 
@@ -112,11 +93,149 @@ means that `[Jupyter Book](https://jupyterbook.org)` will be recognised as a URL
 
 :::
 
+(content:references)=
+## Reference section labels
+
+Labels are a way to add tags to parts of your content so that you can reference them
+later on. This is helpful if you want to quickly insert links to other
+parts of your book. Labels can be added before major elements of a page,
+such as titles or figures.
+
+To add a label, use the following pattern **before** the element you wish
+to label:
+
+```md
+(my-label)=
+# The thing to label
+```
+
+For example, we've added the following label above the header for this section with:
+
+```md
+(content:references)=
+## Cross-references and labels
+```
+
+You can insert cross-references to labels in your content with two kinds of syntax:
+
+- `` {ref}`label-text` ``
+- `[](label-text)`
+
+For example, the syntax `` {ref}`content:references` `` or `[](content:references)` results in a link to this section like so: {ref}`content:references`.
+
+## Referencing figures
+
+To reference a figure in your book, first add a figure and ensure that it has both a `name` as well as a caption associated with it:
+
+`````{panels}
+source
+^^^
+````md
+```{figure} ../images/cool.jpg
+:name: my-fig-ref
+
+My figure title.
+```
+````
+---
+result
+^^^
+```{figure} ../images/cool.jpg
+:name: my-fig-ref
+
+My figure title.
+```
+`````
+
+Then, reference the figure by its `:name:` value. For example:
+
+| source                                         | result                                   |
+|------------------------------------------------|------------------------------------------|
+| `` Here is {ref}`my-fig-ref` ``               | Here is {ref}`my-fig-ref`               |
+| `` Here is {ref}`My cool fig <my-fig-ref>` `` | Here is {ref}`My cool fig <my-fig-ref>`              |
+| `` Here is [](my-fig-ref) ``               | Here is [](my-fig-ref)               |
+| `` Here is [My cool fig](my-fig-ref) `` | Here is [My cool fig](my-fig-ref)              |
+| `` Here is {numref}`my-fig-ref` ``            | Here is {numref}`my-fig-ref`            |
+| `` Here is {numref}`Custom Figure %s text ` `` | Here is {numref}`Custom Figure %s text <my-fig-ref>` |
+
+## Reference tables
+
+To reference a table, first create a table and ensure that it has a `:name:` and a title:
+
+`````{panels}
+source
+^^^
+````md
+```{table} My table title
+:name: my-table-ref
+
+| header 1 | header 2 |
+|---|---|
+| 3 | 4 |
+```
+````
+---
+result
+^^^
+```{table} My table title
+:name: my-table-ref
+
+| header 1 | header 2 |
+|---|---|
+| 3 | 4 |
+```
+`````
+
+Here are several ways to reference this content:
+
+| source                                         | result                                   |
+|------------------------------------------------|------------------------------------------|
+| `` Here is {ref}`my-table-ref` ``               | Here is {ref}`my-table-ref`               |
+| `` Here is {ref}`My cool table <my-table-ref>` `` | Here is {ref}`My cool table <my-table-ref>`              |
+| `` Here is [](my-table-ref) ``               | Here is [](my-table-ref)               |
+| `` Here is [My cool table](my-table-ref) `` | Here is [My cool table](my-table-ref)              |
+| `` Here is {numref}`my-table-ref` ``            | Here is {numref}`my-table-ref`            |
+| `` Here is {numref}`Custom Table %s text ` `` | Here is {numref}`Custom Table %s text <my-table-ref>` |
+
+
+## Reference content files
+
+To reference other files of book content, use the `{doc}` role, or link directly to another file with Markdown link syntax. For exmaple:
+
+| source                                         | result                                   |
+|------------------------------------------------|------------------------------------------|
+| `` Here is {doc}`../file-types/myst-notebooks` ``               | Here is {doc}`../file-types/myst-notebooks`               |
+| `` Here is {doc}`A different page <../file-types/myst-notebooks>` `` | Here is {doc}`A different page <../file-types/myst-notebooks>`              |
+| `` Here is [](../file-types/myst-notebooks.md) ``               | Here is [](../file-types/myst-notebooks.md)               |
+| `` Here is [A different page](../file-types/myst-notebooks.md) `` | Here is [A different page](../file-types/myst-notebooks.md)              |
+
+## Reference equations
+
+To reference equations, first insert an equation with a label like so:
+
+```{math}
+:label: my-math-ref
+w_{t+1} = (1 + r_{t+1}) s(w_t) + y_{t+1}
+```
+
+To reference equations, use the `{eq}` role. It will automatically insert the number of the equation.
+Note that you cannot modify the text of equation links.
+
+For example:
+
+- `` See Equation `{eq}`my-math-ref` `` results in: See Equation {eq}`my-math-ref`
+- `` See Equation [](my-math-ref) `` results in: See Equation [](my-math-ref).
+
+
 (content:citations)=
 ## Citations and bibliographies
 
 You can add citations and bibliographies using references that are stored in a `bibtex` file that is in your book's folder. You can then add a citation in-line in your Markdown with the `{cite}` role, and include the bibliography from your bibtex file with the `{bibliography}` directive.
 
+```{seealso}
+This functionality uses the excellent [sphinxcontrib-bibtex](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/) extension.
+```
+
 **To add citations to your book**, take the following steps:
 
 1. **Create a references bibtex file**.
@@ -229,7 +348,7 @@ A common fix is to add a filter to the bibliography directives:
 See `sphinxcontrib-bibtex` documentation on [local bibliographies](https://sphinxcontrib-bibtex.readthedocs.io/en/latest/usage.html#section-local-bibliographies).
 
 (citations/bibliography)=
-## Bibliography
+### Bibliography
 
 ```{bibliography} ../references.bib
 ```

docs/content/content-blocks.md

@@ -4,6 +4,7 @@ A common use of directives and roles is to designate "special blocks" of your co
 This allows your to include more complex information such as warnings and notes, citations, and figures.
 This section covers a few common ones.
 
+(content:admonitions)=
 ## Notes, warnings, and other admonitions
 
 Let's say you wish to highlight a particular block of text that exists slightly apart from the narrative of your page.
@@ -143,48 +144,6 @@ This text is **standard** _Markdown_
 This text is **standard** _Markdown_
 :::
 
-(content/toggle-admonitions)=
-### Hiding the content of admonitions
-
-You can also hide the body of your admonition blocks so that users must click
-a button to reveal their content. This is helpful if you'd like to include some text
-that isn't immediately visible to the user.
-
-To hide the body of admonition blocks, add the `dropdown` class to them, like so:
-
-````md
-```{note}
-:class: dropdown
-The note body will be hidden!
-```
-````
-
-results in:
-
-```{note}
-:class: dropdown
-The note body will be hidden!
-```
-
-You can use this in conjunction with `{admonition}` directives to include your
-own titles and stylings. For example:
-
-````md
-:::{admonition,dropdown,tip} Click the + sign to see what's inside
-Here's what's inside!
-:::
-````
-
-results in:
-
-:::{admonition,dropdown,tip} Click the + sign to see what's inside
-Here's what's inside!
-:::
-
-:::{important}
-Admonition dropdowns require JavaScript to be enabled on the browser which they are viewed.
-By contrast, the [dropdown directive](content/panels) below works purely *via* HTML+CSS.
-:::
 
 ### Insert code cell outputs into admonitions
 
@@ -216,10 +175,41 @@ See [](../interactive/hiding.md) for more information and other tag options.
 :::
 
 (content/panels)=
-## Panels and dropdowns
+## Panels
+
+Panels provide an easy fay for you to organize chunks of content into flexible containers on your page.
+They are useful for creating card-like layouts, flexible columns, and grids.
+Panels are based off of [Bootstrap CSS](https://getbootstrap.com/docs/4.5/components/card/), and utilize Bootstrap's classes to control the look and feel of panels.
+
+Here is an example that creates two panels:
+
+`````
+````{panels}
+Panel header 1
+^^^
+Panel body 1
++++
+Panel footer 1
+---
+
+Panel header 2
+^^^
+Panel body 2
++++
+Panel footer 2
+````
+`````
 
-Jupyter Book now also integrates the [sphinx-panels](https://sphinx-panels.readthedocs.io) extension.
-This allows you to add special blocks to your online content, for example
+- `---` separates each panel
+- `^^^` defines the panel header
+- `+++` defines the panel footer
+
+```{note}
+Panel headers and footers are optional.
+If you don't include `^^^` or `+++` in your panel, they will not show up.
+```
+
+You can embed all kinds of content inside of panels. For example, the following panels:
 
 ````{panels}
 Content of the left panel.
@@ -233,10 +223,10 @@ Content of the left panel.
 :type: ref
 :classes: stretched-link
 ```
-
 ````
 
-was created with
+were created with:
+
 
 `````md
 ````{panels}
@@ -255,28 +245,137 @@ Content of the left panel.
 ````
 `````
 
-Another example making use of dropdowns is given below:
+```{seealso}
+See the [Sphinx Panels card layout documentaiton](https://sphinx-panels.readthedocs.io/en/latest/#card-layout) for more information.
+```
 
-```{dropdown} Click on me to see my content!
-I'm the content which can be **anything** {fa}`check,text-success ml-1`
+### Controlling the look and feel of panels
 
-:::{note}
-Even other blocks.
-:::
+You can control the look and feel of panels by passing attaching bootstrap classes to panel headers/body/footers.
+You do this by passing configuration options to your  `{panels}` directive.
+
+For example:
+
+
+```{seealso}
+See the [Panels card styling documentation](https://sphinx-panels.readthedocs.io/en/latest/#card-styling) for more information.
+```
+
+For example, you can control how many columns are in your panels by using [Bootstrap column classes](https://getbootstrap.com/docs/4.0/layout/grid/). These panels:
+
+````{panels}
+:column: col-4
+:card: border-2
+Header A
+^^^
+Body A
+---
+Header B
+^^^
+Body B
+---
+Header C
+^^^
+Body C
+````
+
+Were created by this code:
+
+`````
+````{panels}
+:column: col-4
+:card: border-2
+Header A
+^^^
+Body A
+---
+Header B
+^^^
+Body B
+---
+Header C
+^^^
+Body C
+````
+`````
+
+## Dropdowns
+
+Dropdowns allows you to hide content behind a title and a button.
+There are two kinds of dropdowns in Jupyter Book:
+
+### The `{dropdown}` directive
+
+Use the `{dropdown}` directive to create a clickable dropdown with a title.
+
+For example:
+
+`````{panels}
+source
+^^^
+````
+```{dropdown} Here's my dropdown
+And here's my dropdown content
+```
+````
+---
+result
+^^^
+```{dropdown} Here's my dropdown
+And here's my dropdown content
 ```
+`````
+
+(content/toggle-admonitions)=
+### Dropdown admonitions
 
-which was created from:
+You can also hide the body of your admonition blocks so that users must click a button to reveal their content.
+This is helpful if you'd like to include some text that isn't immediately visible to the user.
 
+To turn an admonition into a dropdown, add the `dropdown` class to them. For example:
+
+`````{panels}
+source
+^^^
 ````md
+```{note}
+:class: dropdown
+The note body will be hidden!
+```
+````
+---
+result
+^^^
+```{note}
+:class: dropdown
+The note body will be hidden!
+```
+`````
 
-```{dropdown} Click on me to see my content!
-I'm the content which can be **anything** {fa}`check,text-success ml-1`
+You can use this in conjunction with `{admonition}` directives to include your
+own titles and stylings. For example:
 
-:::{note}
-Even other blocks.
+`````{panels}
+source
+^^^
+````md
+:::{admonition,dropdown,tip} Click here!
+Here's what's inside!
 :::
-```
 ````
+---
+result
+^^^
+:::{admonition,dropdown,tip} Click here!
+Here's what's inside!
+:::
+`````
+
+:::{important}
+Admonition dropdowns require JavaScript to be enabled on the browser which they are viewed.
+By contrast, the [dropdown directive](content/panels) below works purely *via* HTML+CSS.
+:::
+
 
 (content/definition-lists)=
 
@@ -291,15 +390,11 @@ parse:
 
 Definition lists utilise the [markdown-it-py deflist plugin](https://markdown-it-py.readthedocs.io/en/latest/plugins.html), which itself is based on the [Pandoc definition list specification](http://johnmacfarlane.net/pandoc/README.html#definition-lists).
 
-This syntax can be useful, for example, as an alternative to nested bullet lists:
-
-- Term 1
-  - Definition
-- Term 2
-  - Definition
-
-Using instead:
+Here's an example:
 
+````{panels}
+source
+^^^
 ```md
 Term 1
 : Definition
@@ -307,20 +402,21 @@ Term 1
 Term 2
 : Definition
 ```
-
-gives
-
+---
+result
+^^^
 Term 1
 : Definition
 
 Term 2
 : Definition
+````
 
 From the [Pandoc documentation](https://pandoc.org/MANUAL.html#definition-lists):
 
 > Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions.
 > A definition begins with a colon or tilde, which may be indented one or two spaces.
-
+>
 > A term may have multiple definitions, and each definition may consist of one or more block elements (paragraphs, code blocks, lists, etc.)
 
 Here is a more complex example, demonstrating some of these features:
@@ -367,62 +463,75 @@ Term 3
 ## Quotations and epigraphs
 
 Quotations and epigraphs provide ways to highlight information given by others.
-They behave slightly differently.
+
+### Quotations
 
 **Regular quotations** are controlled with standard Markdown syntax, i.e., by
-inserting a caret (`>`) symbol in front of one or more lines of text. For example,
-the following quotation:
+inserting a caret (`>`) symbol in front of one or more lines of text. For example:
 
+````{panels}
+source
+^^^
+```md
 > Here is a cool quotation.
 >
 > From me, Jo the Jovyan
-
-Was created with this Markdown:
-
-```md
+```
+---
+result
+^^^
 > Here is a cool quotation.
 >
 > From me, Jo the Jovyan
-```
+````
+
+### Epigraphs
 
 **Epigraphs** draw more attention to a quote and highlight its author. You should
 keep these relatively short so that they don't take up too much vertical space. Here's
 how an epigraph looks:
 
+`````{panels}
+source
+^^^
+````md
 ```{epigraph}
 Here is a cool quotation.
 
 From me, Jo the Jovyan
 ```
-
-This was generated with this Markdown:
-
-````md
+````
+---
+result
+^^^
 ```{epigraph}
 Here is a cool quotation.
 
 From me, Jo the Jovyan
 ```
-````
+`````
 
-You can provide an **attribution** to an epigraph by adding `--` to the final line, followed
-by the quote author. For example, the epigraph
+You can provide an **attribution** to an epigraph by adding `--` to the final line, followed by the quote author. For example:
 
+`````{panels}
+source
+^^^
+````md
 ```{epigraph}
 Here is a cool quotation.
 
 -- Jo the Jovyan
 ```
-
-was generated with this Markdown:
-
-````md
+````
+---
+result
+^^^
 ```{epigraph}
 Here is a cool quotation.
 
 -- Jo the Jovyan
 ```
-````
+`````
 
 ## Glossaries