diff --git a/.DS_Store b/.DS_Store
index a36a254f..919e3432 100644
Binary files a/.DS_Store and b/.DS_Store differ
diff --git a/Gemfile b/Gemfile
index c997637a..b4057b67 100644
--- a/Gemfile
+++ b/Gemfile
@@ -1,6 +1,9 @@
source "https://rubygems.org"
gemspec
-gem "jekyll", "~> 4.3"
+gem "jekyll-github-metadata", ">= 2.15"
-# gem "just-the-docs"
+gem "jekyll-include-cache", group: :jekyll_plugins
+gem "jekyll-sitemap", group: :jekyll_plugins
+
+gem "html-proofer", "~> 5.0", :group => :development
diff --git a/MIGRATION.md b/MIGRATION.md
new file mode 100644
index 00000000..134f4624
--- /dev/null
+++ b/MIGRATION.md
@@ -0,0 +1,533 @@
+---
+title: Migration and Upgrading
+layout: default
+---
+
+# Migrating and Upgrading
+
+Summary
+: A site that uses `just-the-docs` (as a theme or as a remote theme) automatically
+ switches to a new release, unless it is pinned to a previous version.
+
+ This migration guide draws attention to:
+
+ - changes that might break your site,
+ - features added in the latest release, and
+ - features that have become deprecated (and are likely to be removed in a future release).
+
+This document contains instructions on how to migrate and upgrade Just the Docs sites from every minor or major version bump, starting from `v0.3.3` to `v0.4.0`.
+
+
+
+ Table of contents
+
+ {: .text-delta }
+- TOC
+{:toc}
+
+
+{::options toc_levels="2..4" /}
+
+{: .warning }
+> If your configuration states `remote_theme: just-the-docs/just-the-docs`, your
+> website is built using the current `main` branch of the theme, which may include
+> changes made after the latest release; see the [CHANGELOG].
+>
+> If your configuration states `theme: just_the_docs` and your `Gemfile` specifies
+> `gem "just-the-docs"`, your website is always built using the latest release.
+
+{: .note }
+> If you have cloned/forked and customised the theme repo,
+> and pull the changes of a new release to your clone,
+> you may need to resolve merge conflicts.
+
+[CHANGELOG]: {% link CHANGELOG.md %}
+
+## v0.9.x - v0.10.0
+
+There are no potentially-breaking changes in v0.10.0.
+
+## v0.8.x - v0.9.0
+
+There are no potentially-breaking changes in v0.9.0.
+
+## v0.7.x - v0.8.0
+
+There are no potentially-breaking changes in v0.8.0.
+
+## v0.6.x - v0.7.0
+
+### POTENTIALLY-BREAKING CHANGES in v0.7.0
+
+There are some *very minor* potentially-breaking changes for users in version `v0.7.0`. **They do not affect the vast majority of users**; however, this may affect users of (undocumented) internal theme structure. They concern:
+
+1. the movement of `_includes/nav.html`, which has moved to `_includes/components/nav.html`
+ - **explicit migration only necessary if users have overridden `_includes/nav.html`**
+2. the addition of `
+
+{% else %}
+
+{% if site.mermaid.path %}
+
+{% else %}
+
+{% endif %}
+
+
+
+{% endif %}
diff --git a/_includes/components/nav/children.html b/_includes/components/nav/children.html
new file mode 100644
index 00000000..b562248c
--- /dev/null
+++ b/_includes/components/nav/children.html
@@ -0,0 +1,48 @@
+{%- comment -%}
+ Include as: {%- include components/nav/children.html node=node ancestors=title_array all=bool -%}
+ Depends on: include.node, include.ancestors, include.all, nav_parenthood, nav_top_node_titles.
+ Includes: components/nav/sorted.html.
+ Assigns to: nav_children.
+ Overwrites:
+ nav_candidates, nav_child, nav_child_ok.
+{%- endcomment -%}
+
+{%- assign nav_children = "" | split: "" -%}
+
+{%- if include.all == true or include.node.has_children != false -%}
+
+ {%- assign nav_candidates = nav_parenthood
+ | where: "name", include.node.title | map: "items" | first -%}
+
+ {%- for nav_child in nav_candidates -%}
+ {%- assign nav_child_ok = true -%}
+
+ {%- if nav_child.grand_parent and nav_child.grand_parent != include.node.parent -%}
+ {%- assign nav_child_ok = false -%}
+ {%- endif -%}
+
+ {%- if nav_child.ancestor and nav_child.ancestor != include.node.title -%}
+ {%- unless include.ancestors contains nav_child.ancestor -%}
+ {%- assign nav_child_ok = false -%}
+ {%- endunless -%}
+ {%- endif -%}
+
+ {%- comment -%}
+ The following check rejects nav_child as 3rd-level when include.node is 2nd-level
+ and nav_child can also be 2nd-level. This is for backwards compatibility with
+ existing 3-level sites.
+ {%- endcomment -%}
+ {%- if nav_child.grand_parent == nil and nav_child.ancestor == nil and
+ nav_top_node_titles contains nav_child.parent and include.ancestors.size >= 1 -%}
+ {%- assign nav_child_ok = false -%}
+ {%- endif -%}
+
+ {%- if nav_child_ok -%}
+ {%- assign nav_children = nav_children | push: nav_child -%}
+ {%- endif -%}
+ {%- endfor -%}
+
+{%- endif -%}
+
+{%- include components/nav/sorted.html pages=nav_children -%}
+{%- assign nav_children = nav_sorted -%}
diff --git a/_includes/components/nav/links.html b/_includes/components/nav/links.html
new file mode 100644
index 00000000..335cdb01
--- /dev/null
+++ b/_includes/components/nav/links.html
@@ -0,0 +1,53 @@
+{%- comment -%}
+ Include as: {%- include components/nav/links.html pages=page_array ancestors=title_array all=bool -%}
+ Depends on: include.pages, include.ancestors, include.all.
+ Results in: HTML for the main navigation when all is nil or false;
+ includes links to pages excluded from the main navigation when all is true.
+ Includes: components/nav/sorted.html, components/nav/children.html, components/nav/links.html.
+ Overwrites:
+ node, nav_children, nav_ancestors.
+{%- endcomment -%}
+
+
+ {%- for node in include.pages -%}
+ {%- if include.all == true or node.nav_exclude != true -%}
+
+ {%- if include.ancestors contains node.title -%}
+
+
+ A page has the same title as its parent page or one of its ancestral pages!
+ This causes an incorrect link in the main navigation panel.
+ Page title: {{ node.title }}, location: {{ node.path }}.
+
+{%- comment -%}{%- endcomment -%}
diff --git a/_includes/components/nav/pages.html b/_includes/components/nav/pages.html
new file mode 100644
index 00000000..86813d60
--- /dev/null
+++ b/_includes/components/nav/pages.html
@@ -0,0 +1,23 @@
+{%- comment -%}
+ Include as: {%- include components/nav/pages.html pages=page_array all=bool -%}
+ Depends on: include.pages.
+ Results in: HTML for the main navigation when all is nil or false;
+ adds links to pages excluded from the main navigation when all is true.
+ Includes: components/nav/links.html
+ Assigns to:
+ nav_parenthood, nav_top_nodes, nav_top_node_titles, nav_ancestors.
+{%- endcomment -%}
+
+{%- assign nav_parenthood = include.pages
+ | where_exp: "item", "item.title != nil" | group_by: "parent" -%}
+
+{%- assign nav_top_nodes = nav_parenthood
+ | where_exp: "item", "item.name == ''" | map: "items" | first -%}
+
+{%- include components/nav/sorted.html pages=nav_top_nodes -%}
+
+{% assign nav_top_node_titles = nav_top_nodes | map: "title" -%}
+
+{%- assign nav_ancestors = "" | split: "" -%}
+
+{%- include components/nav/links.html pages=nav_sorted ancestors=nav_ancestors all=include.all -%}
diff --git a/_includes/components/nav/sorted.html b/_includes/components/nav/sorted.html
new file mode 100644
index 00000000..ebea0fda
--- /dev/null
+++ b/_includes/components/nav/sorted.html
@@ -0,0 +1,109 @@
+{%- comment -%}
+ Include as: {%- include components/nav/sorted.html pages=page_array -%}
+ Depends on: include.pages.
+ Assigns to: nav_sorted.
+ Overwrites:
+ nav_order_pages, title_order_pages, double_quote, empty_array,
+ nav_number_pages, nav_string_pages, nav_order_groups, group,
+ title_number_pages, title_string_pages, title_order_groups.
+{%- endcomment -%}
+
+{%- comment -%}
+ The `nav_order` values of pages affect the order in which they are shown in
+ the navigation panel and in the automatically generated tables of contents.
+ Sibling pages with the same `nav_order` value may be shown in any order.
+ Sibling pages with no `nav_order` value are shown after all pages that have
+ explicit `nav_order` values, ordered by their `title` values.
+
+ The `nav_order` and `title` values can be numbers or strings. To avoid build
+ failures, we sort numbers and strings separately. We sort numbers by their
+ values, and strings lexicographically. The case-sensitivity of string sorting
+ is determined by the configuration setting of `nav_sort`. Pages with no `title`
+ value are excluded from the navigation.
+
+ Note: Numbers used as `title` or `nav_order` values should not be in quotes,
+ unless you intend them to be lexicographically ordered. Numbers are written
+ without spaces or thousands-separators. Negative numbers are preceded by `-`.
+ Floats are written with the integral and fractional parts separated by `.`.
+ (Bounds on the magnitude and precision are presumably the same as in Liquid.)
+{%- endcomment -%}
+
+{%- assign nav_order_pages = include.pages
+ | where_exp: "item", "item.nav_order != nil" -%}
+{%- assign title_order_pages = include.pages
+ | where_exp: "item", "item.nav_order == nil" -%}
+
+{%- comment -%}
+ First, filter `nav_order_pages` and `title_order_pages` according to the type
+ of value to be used for sorting.
+
+ The first character of the result of filtering with `jsonify` is `"` only for
+ strings. Removing `"` from its `slice : 0` has size 0 for strings and 1 for
+ numbers, so grouping the pages gives at most two groups.
+{%- endcomment -%}
+
+{%- assign double_quote = '"' -%}
+{%- assign empty_array = "" | split: "" -%}
+
+{%- assign nav_string_pages = empty_array -%}
+{%- assign nav_number_pages = empty_array -%}
+{%- unless nav_order_pages == empty -%}
+ {%- assign nav_order_groups = nav_order_pages
+ | group_by_exp: "item",
+ "item.nav_order | jsonify | slice: 0 | remove: double_quote | size" -%}
+ {%- for group in nav_order_groups -%}
+ {%- if group.name == 0 -%}
+ {%- assign nav_string_pages = group.items -%}
+ {%- elsif group.name == 1 -%}
+ {%- assign nav_number_pages = group.items -%}
+ {%- endif -%}
+ {%- endfor -%}
+{%- endunless -%}
+
+{%- assign title_string_pages = empty_array -%}
+{%- assign title_number_pages = empty_array -%}
+{%- unless title_order_pages == empty -%}
+ {%- assign title_order_groups = title_order_pages
+ | group_by_exp: "item",
+ "item.title | jsonify | slice: 0 | remove: double_quote | size" -%}
+ {%- for group in title_order_groups -%}
+ {%- if group.name == 0 -%}
+ {%- assign title_string_pages = group.items -%}
+ {%- elsif group.name == 1 -%}
+ {%- assign title_number_pages = group.items -%}
+ {%- endif -%}
+ {%- endfor -%}
+{%- endunless -%}
+
+{%- comment -%}
+ Now sort each array of pages separately, then concatenate the sorted arrays.
+{%- endcomment -%}
+
+{%- unless nav_number_pages == empty -%}
+ {%- assign nav_number_pages = nav_number_pages | sort: "nav_order" -%}
+{%- endunless -%}
+
+{%- unless nav_string_pages == empty -%}
+ {%- if site.nav_sort == 'case_insensitive' -%}
+ {%- assign nav_string_pages = nav_string_pages | sort_natural: "nav_order" -%}
+ {%- else -%}
+ {%- assign nav_string_pages = nav_string_pages | sort: "nav_order" -%}
+ {%- endif -%}
+{%- endunless -%}
+
+{%- unless title_number_pages == empty -%}
+ {%- assign title_number_pages = title_number_pages | sort: "title" -%}
+{%- endunless -%}
+
+{%- unless title_string_pages == empty -%}
+ {%- if site.nav_sort == 'case_insensitive' -%}
+ {%- assign title_string_pages = title_string_pages | sort_natural: "title" -%}
+ {%- else -%}
+ {%- assign title_string_pages = title_string_pages | sort: "title" -%}
+ {%- endif -%}
+{%- endunless -%}
+
+{%- assign nav_sorted = nav_number_pages
+ | concat: nav_string_pages
+ | concat: title_number_pages
+ | concat: title_string_pages -%}
diff --git a/_includes/components/search_footer.html b/_includes/components/search_footer.html
new file mode 100644
index 00000000..d448fdb2
--- /dev/null
+++ b/_includes/components/search_footer.html
@@ -0,0 +1,7 @@
+{% if site.search.button %}
+
+{% endif %}
+
+
diff --git a/_includes/components/search_header.html b/_includes/components/search_header.html
new file mode 100644
index 00000000..35621241
--- /dev/null
+++ b/_includes/components/search_header.html
@@ -0,0 +1,9 @@
+{% capture search_placeholder %}{% include search_placeholder_custom.html %}{% endcapture %}
+
+
+
+
+
+
+
+
diff --git a/_includes/components/sidebar.html b/_includes/components/sidebar.html
new file mode 100644
index 00000000..13c755bd
--- /dev/null
+++ b/_includes/components/sidebar.html
@@ -0,0 +1,32 @@
+{%- comment -%}
+ Include as: {%- include components/sidebar.html -%}
+ Depends on: page(?), site.
+ Results in: HTML for the side bar.
+ Includes:
+ title.html, components/site_nav.html, nav_footer_custom.html
+ Overwrites:
+ nav_footer_custom.
+ Should not be cached, because nav_footer_custom.html might depend on page.
+{%- endcomment -%}
+
+