Prep v0.6.0

CHANGELOG.md

@@ -17,9 +17,49 @@ This website is built from the `HEAD` of the `main` branch of the theme reposito
 
 Code changes to `main` that are *not* in the latest release:
 
-- Fixed: build times for large sites by [@pdmosses] in [#1244]
+- N/A
+
+## Release v0.6.0
+
+Hi all, this is a minor release that introduces performance improvements for build times on large sites, correctly sets the `color-scheme` property, and fixes invalid HTML. However, it introduces some potentially-breaking *internal* changes to undocumented features of the theme.
+
+### Migrating to `v0.6.0`
+
+**Migration**: users will need to migrate if:
+
+- they have an existing `_includes` file named `favicon.html`, `head_nav.html`, or `css/activation.scss.liquid`
+- they have code that refers to `#main-content-wrap`
+- they override the default `light` theme's code, or the theme-loading logic
+- they have different favicons for different pages
+
+For more, refer to the [migration guide](https://just-the-docs.com/MIGRATION/).
+
+### Using Release `v0.6.0`
+
+Users who have not pinned the theme version will be **automatically upgraded to `v0.6.0` the next time they build their site**.
+
+To use this release explicitly as a remote theme:
+
+```yml
+remote_theme: just-the-docs/just-the-docs@v0.6.0
+```
+
+To use this version 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.6.0"
+```
+
+To use and pin a previous version of the theme, replace the `0.6.0` with the desired release tag.
+
+### New Features and Bugfixes
+
 - Added: `$color-scheme` theme variable to specify `color-scheme` for `:root` by [@sigv] in [#1280]
+- Fixed: build times for large sites by [@pdmosses] in [#1244]
 - Fixed: missing closing `</button>` tag in `sidebar.html` by [@mattxwang] in [#1304]
+- Fixed: removed duplicate `#main-content-wrap` minimal and default layouts by [@mattxwang] in [#1305]
+
+### Documentation
 
 {: .warning }
 The theme docs are unversioned, and already reflect the above changes.
@@ -27,11 +67,17 @@ The theme docs are unversioned, and already reflect the above changes.
 Docs changes:
 
 - A [footnote]({% link docs/configuration.md %}#fn:js-disabled) in the configuration docs explains how disabling JavaScript affects the display of navigation links when browsing folded collections.
+- Invalid HTML has been removed from most documentation examples.
+
+### New Contributors
+
+- [@sigv] made their first contribution in [#1280]
 
 [@sigv]: https://github.com/sigv
 [#1244]: https://github.com/just-the-docs/just-the-docs/pull/1244
 [#1280]: https://github.com/just-the-docs/just-the-docs/pull/1280
 [#1304]: https://github.com/just-the-docs/just-the-docs/pull/1304
+[#1305]: https://github.com/just-the-docs/just-the-docs/pull/1305
 
 ## Release v0.5.4
 

MIGRATION.md

@@ -43,6 +43,78 @@ This document contains instructions on how to migrate and upgrade Just the Docs
 
 [CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
 
+## v0.5.x - v0.6.0
+
+### POTENTIALLY-BREAKING CHANGES in v0.6.0
+
+There are some *very minor* potentially-breaking changes for users in version `v0.6.0`. **They do not affect the vast majority of users**; however, this may affect users of (undocumented) internal theme structure. They concern:
+
+1. the addition of new `_includes/favicon.html`, `_includes/head_nav.html`, and `_includes/css/activation.scss.liquid`
+  - **explicit migration only necessary if users have defined a custom file with the same name**
+2. removing `id="main-content-wrap` from wrapper `div` elements in default layouts
+  - **explicit migration only necessary if users have written code that depends on `#main-content-wrap`**
+3. loading the new `$color-scheme` variable (from the light scheme by default)
+  - **explicit migration only necessary if users have overridden the base light theme**
+4. caching the favicon for the entire site
+  - **explicit migration only necessary if users have different favicons for different pages**
+
+#### New Includes
+
+Version `v0.6.0` introduces three new `_includes` files:
+
+- `_includes/favicon.html`, which now contains logic previously in `_includes/head.html`: loading `favicon.ico` if no favicon is specified
+- `_includes/head_nav.html`, which generates CSS used for the new efficient navigation implementation
+- `_includes/css/activation.scss.liquid`, which is used by `head_nav` for navigation implementation
+
+If users have existing `_includes` files with this name, they should be renamed (and imported with their new name) prior to upgrading to `0.6.0`. No other change is necessary.
+
+#### Removed `#main-content-wrap`
+
+In `_layouts/default.html` and `_layouts/minimal.html`, the `id="main-content-wrap"` has been removed from the wrapper div (in part due to a bug with multiple `id`s on one element). Internally, our theme *does not use* these `id`s; for most users, this does not require any action.
+
+However, code that relies on this `id` must be changed. Each of the related elements still has the unique class `.main-content-wrap`, and can be selected with this class. For example, in CSS:
+
+```css
+/* OLD */
+#main-content-wrap { /* ... */ }
+
+/* NEW */
+.main-content-wrap { /* ... */ }
+```
+
+Or in JS:
+
+```js
+// OLD
+document.getElementById("main-content-wrap");
+
+// NEW
+document.getElementsByClassName("main-content-wrap")[0];
+```
+
+#### New `$color-scheme` variable
+
+The theme now properly sets the `color-scheme` property. To do so, the new `$color-scheme` SCSS variable has been created. The variable has been added to the default `light` scheme, which is *always* loaded by Just the Docs.
+
+Migration is only needed if:
+
+- the packaged `light` scheme has been *overridden* (this is *not* the same as using a custom scheme)
+- or, the scheme logic to always load `light` has been changed
+
+(neither of these behaviours are recommended by Just the Docs)
+
+In either of these cases, users should add a `$color-scheme` SCSS variable to their active scheme with the appropriate value (see: [MDN docs on `color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme)).
+
+```scss
+$color-scheme: light !default;
+```
+
+#### Cached favicon
+
+Version `v0.6.0` adds a new `_include` that caches the favicon for the entire site. This significantly improves page build times for large sites.
+
+However, some users may load different favicons for each page (and/or dynamically change the first favicon load). In this case, they should override the logic in `_includes/favicon.html` by **replacing** it with an empty file (this is *different* from deleting it). No further migration is necessary.
+
 ## v0.4.x - v0.5.0
 
 ### POTENTIALLY-BREAKING CHANGES in v0.5.0