Merge branch 'Freek' into 'main'

Edits reference

See merge request interactivetextbooks-citg/jupyter-book-manual!87

book/basic-features/References.md

@@ -2,6 +2,24 @@
 
 To make references to figures, equations et cetera, use the following syntax:
 
-- For figures, use: ``{numref}`<name of the figure>` ``
+- For figures, use: ``{numref}`Figure {number} <name of the figure>` ``
 - For equations, use: ``{eq}`<equation label>` ``
 - For citations, use: ``{cite:p}`<bibtex_entry>` `` for a citation between parenthesis, or ``{cite:t}`<bibtex_entry>` `` for an inline citation.
+
+**Examples**
+
+Using ``{numref}`Figure {number} <fig-gitpush>` `` produces the output: {numref}`Figure {number} <fig-gitpush>`. 
+```{figure} ../images/git-push.png
+---
+width: 50%
+name: fig-gitpush
+---
+Some caption here
+```
+
+Or, the derivation results in equation {eq}`<eq:Newton>`.
+
+$$ F = m\cdot a $$(eq:Newton)
+
+
+

book/basic-features/equations.md

@@ -14,6 +14,12 @@ $$
     F = m \cdot a
 $$
 
+```{tip}
+The scientific rules dictate that quantities ($F$, $m$, $a$ etc.) should be printed in italics. Units, however, should not! One can use `\text{m}` in an equation to comply to this rule:
+
+$$ F = m \cdot a = 10 \cdot 9.81 = 98 \text{N}
+```
+
 > **Warning**
 > 
 > Make sure there is a blank line *before* the display mode equations, otherwise it will render as inline and display the outer set of $$$ symbols. Also, the Euro symbol is not included in MathJax (see note below) and must be specified using `\unicode{0x20AC}` (note that it displays incorrectly in some Markdown renderers like VS Code).
@@ -24,6 +30,12 @@ To number the equations and refer in text, you need to provide a label to the eq
         F = m \cdot a
     $$ (newtons_second_law)
 
+Resulting in:
+
+$$
+    F = m \cdot a
+$$ (newtons_second_law)
+
 > **Note**
 > 
 > The Jupyter Book uses MathJax to display equations, which provides some LaTeX-like functionality, but not all! For example, the Euro symbol is missing, and packages like `siunitx` are not available (hint, use `\textrm{}` and `\textrm{}`). When something is not working, it's useful to search for MathJax-specific solutions (hint, include "mathjax" in your Google search).

book/basic-features/jupyterbook.md

@@ -7,7 +7,7 @@ To build a Jupyter Book, you need three things:
 3. Content
 
 ## The configuration file
-The configuration file of Jupyter Books is named `_config.yml`. It mainly contains settings that apply when building the book.  Here is a basic example of a configuration file, taken from this book:
+The configuration file of Jupyter Books is named `_config.yml`. It mainly contains settings that apply when building the book. Here is a basic example of a configuration file, taken from this book:
 
 ```yml
 title: Jupyter Book Manual
@@ -83,4 +83,32 @@ parts:
     - file: section_3_1
 
 et cetera...
+```
+
+## The structure of a chapter
+The 'nested' structure in the TOC is one way to organize your book. Another way to do so is in the file itself. The structure is defined by the number of `#`:
+
+```
+# Chapter 1 title
+
+## Section 1.1 
+
+### Subsection 1.1.1 
+
+## Section 1.2 
+
+### Subsection 1.2.1
+```
+
+The depth for numbered subsection can be set in the TOC file: 
+
+```
+parts:
+- caption: Part 1
+  numbered: 2
+  chapters:
+  - file: chapter_1
+    sections:
+    - file: section_1_1
+    - file: section_1_2
 ```