From bd2af37865232a28d493aef29f30a006e5b6f24e Mon Sep 17 00:00:00 2001
From: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
Date: Sun, 11 Sep 2022 01:44:27 +0200
Subject: [PATCH] Clarify version docs (#955)

This PR updates the home page and the CHANGELOG to refer to  v0.4.0.rc1 as a pre-release or release candidate, rather than a release. See [this comment](https://github.com/just-the-docs/just-the-docs/pull/613#issuecomment-1240442518) for motivation.

It also adds the versioned docs issue (#728) to the roadmap in the CHANGELOG.

As the config for the theme docs now needs to declare callouts, the [callouts docs](https://just-the-docs.github.io/just-the-docs/docs/ui-components/callouts/) can now illustrate the rendered appearance. (These callouts are merely examples: the names and colors should eventually be replaced by a principled collection, taking account of WCAG.)
---
 CHANGELOG.md                   | 23 +++++++------
 _config.yml                    | 17 ++++++++++
 docs/ui-components/callouts.md | 59 ++++++++++++++++++++++++++++++++--
 index.md                       | 15 ++++++++-
 4 files changed, 100 insertions(+), 14 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 91463ca1..5226156e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,10 +1,12 @@
-# Changelog
+# CHANGELOG
 
 All notable changes to this project are documented in this file.
 
-*Note:* the project underwent a maintenance shift in the creation of v0.4.0.
+*Note:* The project underwent a major maintenance shift in March 2022.
 
-## Head
+## HEAD
+
+*Note:* This website is built from the `HEAD` of the `main` branch of the theme repository. It includes docs for the following changes, which are *not* in the latest pre-release!
 
 ### Changes
 
@@ -17,26 +19,26 @@ All notable changes to this project are documented in this file.
 - Fixed: exclude `vendor/` in Jekyll config by @manuelhenke in https://github.com/just-the-docs/just-the-docs/pull/941
 - Deleted: unused script directory by @mattxwang in https://github.com/just-the-docs/just-the-docs/pull/937
 
-## v0.4.0.rc1
+## Pre-release v0.4.0.rc1
 
 ### We're back!
 
-Hi all! The Just the Docs team is excited to have our first release in over two years! This release is jam-packed with features and bugfixes that have been requested by the community since 2020. They include:
+Hi all! The Just the Docs team is excited to have our first pre-release in over two years! It is jam-packed with features and bugfixes that have been requested by the community since 2020. They include:
 
 - The new callouts component
 - Allowing pages and collections to coexist on the navigation pane
 - New styling: dark syntax highlighting, support for jekyll-asciidoc, word-wrapping instead of overflow for various elements
 - More customization: external nav links, custom nav footers, favicon includes, search color and placeholder configuration, mermaid.js support, and nav sorting
 - Over 20 bugfixes! Big ones include fixing the `rake` command, using `relative_url`, and search input color
-- More documentation, especially on using custom includes.
+- More documentation, especially on using custom includes
 - Updating core dependencies to stable Ruby versions
 - A WIP [template repository](https://github.com/just-the-docs/just-the-docs-template) that allows you to setup your own repository using Just the Docs and GitHub Pages with one click - give it a shot! More documentation, etc. is on the way!
 
 We want your feedback! Are these changes helpful? Are our docs easy to understand? Should new features like `mermaid` be opt-in or opt-out? Please [open an issue](https://github.com/just-the-docs/just-the-docs/issues) or [start a discussion](https://github.com/just-the-docs/just-the-docs/discussions) and let us know!
 
-### Trying out `v0.4.0.rc1`
+### Trying out pre-release `v0.4.0.rc1`
 
-Due to the massive scope of these changes, we're releasing `v0.4.0.rc1` as a **release candidate** for the theme, with `v0.4.0` coming soon. We want your help in testing the theme! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1` - if your version of Just the Docs is not pinned, you'll see the changes the next time you build / run `bundle install` (if you don't use a `Gemfile.lock`) or `bundle update just-the-docs` (if you do).
+Due to the massive scope of these changes, we're making `v0.4.0.rc1` avaialble as a **release candidate** for the theme (i.e., a pre-release) with release `v0.4.0` coming soon. We want your help in testing the changes! As of now, the gem on RubyGems and the repository are updated to `v0.4.0.rc1` - if your version of Just the Docs is not pinned, you'll see the changes the next time you run `bundle install` (if you don't have a `Gemfile.lock`) or `bundle update just-the-docs` (if you do).
 
 To use this RC explicitly as a remote theme:
 
@@ -44,7 +46,7 @@ To use this RC explicitly as a remote theme:
 remote_theme: just-the-docs/just-the-docs@v0.4.0.rc1
 ```
 
-To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install`:
+To use this RC explicitly as a gem-based theme, pin the version in your `Gemfile` and re-run `bundle install` or `bundle update just-the-docs`:
 
 ```Ruby
 gem "just-the-docs", "0.4.0.rc1"
@@ -75,11 +77,12 @@ The new core team currently consists of @mattxwang, @pdmosses, @skullface, @doug
 
 ### Roadmap
 
-In the short-term, we're committed to tidying up everything for a `v0.4.0` release. This involves fixing bugs reported from the community in this release, as well as continually merging in minor PRs.
+In the short-term, we're committed to tidying up everything for a `v0.4.0` release. This involves fixing bugs reported from the community in this pre-release, as well as continually merging in minor PRs.
 
 We're also scoping out medium and long-term projects, and want to keep you in the loop. These include:
 
 - upgrading to Jekyll 4, and stopping support for Jekyll 3
+- versioned docs - issue [#728](https://github.com/just-the-docs/just-the-docs/issues/728)
 - improved accessibility - issues [#566](https://github.com/just-the-docs/just-the-docs/issues/566), [#870](https://github.com/just-the-docs/just-the-docs/issues/870)
 - internationalization (i18n) - issue [#59](https://github.com/just-the-docs/just-the-docs/issues/59)
 - recursive/multi-level navigation - PR [#462](https://github.com/just-the-docs/just-the-docs/pull/462)
diff --git a/_config.yml b/_config.yml
index c9cd27ad..9502ddfd 100644
--- a/_config.yml
+++ b/_config.yml
@@ -107,6 +107,23 @@ gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into t
 # Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
 color_scheme: nil
 
+callouts_level: quiet # or loud
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
 # Google Analytics Tracking (optional)
 # e.g, UA-1234567-89
 ga_tracking: UA-2709176-10
diff --git a/docs/ui-components/callouts.md b/docs/ui-components/callouts.md
index 0a5684b8..753ac927 100644
--- a/docs/ui-components/callouts.md
+++ b/docs/ui-components/callouts.md
@@ -9,7 +9,10 @@ nav_order: 7
 
 Markdown does not include support for callouts. However, you can style text as a callout using a Markdown extension supported by kramdown: [*block IALs*](https://kramdown.gettalong.org/quickref.html#block-attributes). 
 
-Common kinds of callouts include `admonition`, `attention`, `caution`, `danger`, `error`, `hint`, `important`, `note`, `tip`, and `warning`.
+Common kinds of callouts include `highlight`, `important`, `new`, `note`, and `warning`.
+
+{: .warning }
+These callout names are *not* pre-defined by the theme: you need to define your own names.
 
 When you have [configured]({{ site.baseurl }}{% link docs/configuration.md %}#callouts) the  `color` and (optional) `title` for a callout, you can apply it to a paragraph, or to a block quote with several paragraphs, as illustrated below.[^postfix]
 
@@ -24,6 +27,10 @@ When you have [configured]({{ site.baseurl }}{% link docs/configuration.md %}#ca
 A paragraph
 ```
 
+{: .highlight }
+A paragraph
+
+
 #### A single paragraph callout
 {: .no_toc }
 
@@ -32,6 +39,9 @@ A paragraph
 A paragraph
 ```
 
+{: .note }
+A paragraph
+
 ```markdown
 {: .note-title }
 > My note title
@@ -39,6 +49,11 @@ A paragraph
 > A paragraph with a custom title callout
 ```
 
+{: .note-title }
+> My note title
+>
+> A paragraph with a custom title callout
+
 #### A multi-paragraph callout
 {: .no_toc }
 
@@ -51,6 +66,13 @@ A paragraph
 > The last paragraph
 ```
 
+{: .important }
+> A paragraph
+>
+> Another paragraph
+>
+> The last paragraph
+
 ```markdown
 {: .important-title }
 > My important title
@@ -62,19 +84,31 @@ A paragraph
 > The last paragraph
 ```
 
+{: .important-title }
+> My important title
+>
+> A paragraph
+>
+> Another paragraph
+>
+> The last paragraph
+
 #### An indented callout
 {: .no_toc }
 
 ```markdown
-> {: .hint }
+> {: .highlight }
   A paragraph
 ```
 
+> {: .highlight }
+  A paragraph
+
 #### Indented multi-paragraph callouts
 {: .no_toc }
 
 ```markdown
-> {: .attention }
+> {: .new }
 > > A paragraph
 > >
 > > Another paragraph
@@ -82,6 +116,14 @@ A paragraph
 > > The last paragraph
 ```
 
+> {: .new }
+> > A paragraph
+> >
+> > Another paragraph
+> >
+> > The last paragraph
+
+
 #### Nested callouts
 {: .no_toc }
 
@@ -91,6 +133,10 @@ A paragraph
 > A paragraph
 ```
 
+{: .important }
+> {: .warning }
+> A paragraph
+
 #### Opaque background
 {: .no_toc }
 
@@ -102,3 +148,10 @@ A paragraph
 > A paragraph
 > </div>
 ```
+
+{: .important }
+> {: .opaque }
+> <div markdown="block">
+> {: .warning }
+> A paragraph
+> </div>
diff --git a/index.md b/index.md
index 6a0d38e4..084df73b 100644
--- a/index.md
+++ b/index.md
@@ -16,7 +16,20 @@ Just the Docs gives your documentation a jumpstart with a responsive Jekyll them
 
 ---
 
-**New: version `0.4.0.rc1` has just been released! See [the changelog](https://github.com/just-the-docs/just-the-docs/blob/main/CHANGELOG.md) for a detailed breakdown!**
+{: .new }
+> **Pre-release version `0.4.0.rc1` is available!**
+> See [the CHANGELOG](https://github.com/just-the-docs/just-the-docs/blob/main/CHANGELOG.md) for a detailed breakdown.
+
+{: .warning }
+> Specifying `gem "just-the-docs"` in your `Gemfile` uses the latest ***release*** (`v0.3.3`), ignoring all pre-releases!
+> To use this pre-release, pin it: 
+> ```ruby
+> gem "just-the-docs", "0.4.0.rc1"
+> ```
+> and/or
+> ```yaml
+> remote_theme: just-the-docs/just-the-docs@v0.4.0.rc1
+> ```
 
 ## Getting started
 
-- 
GitLab