Combination (#578)

This PR combines (and resolves conflicts between) #448, #463, #466, #494, #495, #496, #498, and #572. 

The main aim is to facilitate use of several of the implemented features _together_, when using the fork as a remote theme. It should also simplify merging the included PRs into a future release.

The branch [combination-rec-nav](https://github.com/pdmosses/just-the-docs/tree/combination-rec-nav) adds [multi-level navigation](https://github.com/pmarsceill/just-the-docs/pull/462) and (NEW:) [sibling links](https://github.com/pmarsceill/just-the-docs/pull/394) to the branch used for this PR. It includes updated [documentation for the navigation structure](https://pdmosses.github.io/just-the-docs/docs/navigation-structure/), and reorganised and extended [navigation tests](https://pdmosses.github.io/just-the-docs/tests/navigation/). The documentation and the tests can be browsed at the (temporary) [website published from the combination-rec-nav branch](https://pdmosses.github.io/just-the-docs/).

_Caveat:_ The changes to v0.3.3 in this PR and #462 have not yet been reviewed or approved, and may need updating before merging into a release of the theme. If you use a branch from a PR as a remote theme, there is a risk of such updates affecting your website. Moreover, these branches are likely to be deleted after they have been merged. To avoid  such problems, you could copy the branch that you want to use to your own fork of the theme.

Co-authored-by: Matt Wang <matt@matthewwang.me>

docs/configuration.md

@@ -137,6 +137,59 @@ jtd.addEvent(toggleDarkMode, 'click', function(){
 
 See [Customization]({{ site.baseurl }}{% link docs/customization.md %}) for more information.
 
+## Callouts
+
+To use this feature, you need to configure a `color` and (optionally) `title` for each kind of callout you want to use, e.g.:
+
+```yaml
+callouts:
+  warning:
+    title: Warning
+    color: red
+```
+
+This uses the color `$red-000` for the background of the callout, and `$red-300` for the title and box decoration.[^dark] You can then style a paragraph as a `warning` callout like this:
+
+```markdown
+{: .warning }
+A paragraph...
+```
+
+[^dark]:
+    If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title. 
+
+The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/custom.scss` file:
+
+```scss
+$pink-000: #f77ef1;
+$pink-100: #f967f1;
+$pink-200: #e94ee1;
+$pink-300: #dd2cd4;
+```
+
+You can override the default `opacity` of the background for a particular callout, e.g.:
+
+```yaml
+callouts:
+  custom:
+    color: pink
+    opacity: 0.3
+```
+
+You can change the default opacity (`0.2`) for all callouts, e.g.:
+
+```yaml
+callouts_opacity: 0.3
+```
+
+You can also adjust the overall level of callouts.
+The value of `callouts_level` is either `quiet` or `loud`;
+`loud` increases the saturation and lightness of the backgrounds.
+The default level is `quiet` when using the `light` or custom color schemes,
+and `loud` when using the `dark color scheme.`
+
+See [Callouts]({{ site.baseurl }}{% link docs/ui-components/callouts.md %}) for more information.
+
 ## Google Analytics
 
 ```yaml
@@ -149,39 +202,43 @@ ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (t
 ## Document collections
 
 By default, the navigation and search include normal [pages](https://jekyllrb.com/docs/pages/).
-Instead, you can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together.
+You can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together.
 
-For example, put all your documentation files in the `_docs` folder and create the `docs` collection:
+For example, put all your test files in the `_tests` folder and create the `tests` collection:
 
 ```yaml
 # Define Jekyll collections
 collections:
-  # Define a collection named "docs", its documents reside in the "_docs" directory
-  docs:
+  # Define a collection named "tests", its documents reside in the "_tests" directory
+  tests:
     permalink: "/:collection/:path/"
     output: true
 
 just_the_docs:
   # Define which collections are used in just-the-docs
   collections:
-    # Reference the "docs" collection
-    docs:
+    # Reference the "tests" collection
+    tests:
       # Give the collection a name
-      name: Documentation
+      name: Tests
       # Exclude the collection from the navigation
       # Supports true or false (default)
-      nav_exclude: false
+      # nav_exclude: true
+      # Fold the collection in the navigation
+      # Supports true or false (default)
+      # nav_fold: true
       # Exclude the collection from the search
       # Supports true or false (default)
-      search_exclude: false
+      # search_exclude: true
 ```
+The navigation for all your normal pages (if any) is displayed before those in collections.
 
 You can reference multiple collections.
 This creates categories in the navigation with the configured names.
 
 ```yaml
 collections:
-  docs:
+  tests:
     permalink: "/:collection/:path/"
     output: true
   tutorials:
@@ -190,8 +247,11 @@ collections:
 
 just_the_docs:
   collections:
-    docs:
-      name: Documentation
+    tests:
+      name: Tests
     tutorials:
       name: Tutorials
 ```
+When *all* your pages are in a single collection, its name is not displayed.
+
+The navigation for each collection is a separate name space for page titles: a page in one collection cannot be a child of a page in a different collection, or of a normal page.