Merge pull request #30354 from twbs/grid-xxl-and-sidebar-toc

v5: Add new `xxl` grid tier and move ToC to a sidebar

site/content/docs/4.3/layout/z-index.md

+---
+layout: docs
+title: Z-index
+description: While not a part of Bootstrap's grid system, z-indexes play an important part in how our components overlay and interact with one another.
+group: layout
+---
+
+Several Bootstrap components utilize `z-index`, the CSS property that helps control layout by providing a third axis to arrange content. We utilize a default z-index scale in Bootstrap that's been designed to properly layer navigation, tooltips and popovers, modals, and more.
+
+These higher values start at an arbitrary number, high and specific enough to ideally avoid conflicts. We need a standard set of these across our layered components—tooltips, popovers, navbars, dropdowns, modals—so we can be reasonably consistent in the behaviors. There's no reason we couldn't have used `100`+ or `500`+.
+
+We don't encourage customization of these individual values; should you change one, you likely need to change them all.
+
+{{< scss-docs name="zindex-stack" file="scss/_variables.scss" >}}
+
+To handle overlapping borders within components (e.g., buttons and inputs in input groups), we use low single digit `z-index` values of `1`, `2`, and `3` for default, hover, and active states. On hover/focus/active, we bring a particular element to the forefront with a higher `z-index` value to show their border over the sibling elements.

site/content/docs/4.3/utilities/display.md

@@ -12,12 +12,12 @@ Change the value of the [`display` property](https://developer.mozilla.org/en-US
 
 ## Notation
 
-Display utility classes that apply to all [breakpoints]({{< docsref "/layout/overview#responsive-breakpoints" >}}), from `xs` to `xl`, have no breakpoint abbreviation in them. This is because those classes are applied from `min-width: 0;` and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint abbreviation.
+Display utility classes that apply to all [breakpoints]({{< docsref "/layout/breakpoints" >}}), from `xs` to `xxl`, have no breakpoint abbreviation in them. This is because those classes are applied from `min-width: 0;` and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint abbreviation.
 
 As such, the classes are named using the format:
 
 * `.d-{value}` for `xs`
-* `.d-{breakpoint}-{value}` for `sm`, `md`, `lg`, and `xl`.
+* `.d-{breakpoint}-{value}` for `sm`, `md`, `lg`, `xl`, and `xxl`.
 
 Where *value* is one of:
 
@@ -33,7 +33,7 @@ Where *value* is one of:
 
 The display values can be altered by changing the `$displays` variable and recompiling the SCSS.
 
-The media queries effect screen widths with the given breakpoint *or larger*. For example, `.d-lg-none` sets `display: none;` on both `lg` and `xl` screens.
+The media queries effect screen widths with the given breakpoint *or larger*. For example, `.d-lg-none` sets `display: none;` on both `lg`, `xl`, and `xxl` screens.
 
 ## Examples
 
@@ -51,9 +51,9 @@ The media queries effect screen widths with the given breakpoint *or larger*. Fo
 
 For faster mobile-friendly development, use responsive display classes for showing and hiding elements by device. Avoid creating entirely different versions of the same site, instead hide elements responsively for each screen size.
 
-To hide elements simply use the `.d-none` class or one of the `.d-{sm,md,lg,xl}-none` classes for any responsive screen variation.
+To hide elements simply use the `.d-none` class or one of the `.d-{sm,md,lg,xl,xxl}-none` classes for any responsive screen variation.
 
-To show an element only on a given interval of screen sizes you can combine one `.d-*-none` class with a `.d-*-*` class, for example `.d-none .d-md-block .d-xl-none` will hide the element for all screen sizes except on medium and large devices.
+To show an element only on a given interval of screen sizes you can combine one `.d-*-none` class with a `.d-*-*` class, for example `.d-none .d-md-block .d-xl-none .d-xxl-none` will hide the element for all screen sizes except on medium and large devices.
 
 <table class="table">
   <thead>
@@ -87,6 +87,10 @@ To show an element only on a given interval of screen sizes you can combine one
       <td>Hidden only on xl</td>
       <td><code>.d-xl-none</code></td>
     </tr>
+    <tr>
+      <td>Hidden only on xxl</td>
+      <td><code>.d-xxl-none</code></td>
+    </tr>
     <tr>
       <td>Visible on all</td>
       <td><code>.d-block</code></td>
@@ -109,7 +113,11 @@ To show an element only on a given interval of screen sizes you can combine one
     </tr>
     <tr>
       <td>Visible only on xl</td>
-      <td><code>.d-none .d-xl-block</code></td>
+      <td><code>.d-none .d-xl-block .d-xxl-none</code></td>
+    </tr>
+    <tr>
+      <td>Visible only on xxl</td>
+      <td><code>.d-none .d-xxl-block</code></td>
     </tr>
   </tbody>
 </table>

site/content/docs/4.3/utilities/spacing.md

@@ -12,9 +12,9 @@ Assign responsive-friendly `margin` or `padding` values to an element or a subse
 
 ## Notation
 
-Spacing utilities that apply to all breakpoints, from `xs` to `xl`, have no breakpoint abbreviation in them. This is because those classes are applied from `min-width: 0` and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint abbreviation.
+Spacing utilities that apply to all breakpoints, from `xs` to `xxl`, have no breakpoint abbreviation in them. This is because those classes are applied from `min-width: 0` and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint abbreviation.
 
-The classes are named using the format `{property}{sides}-{size}` for `xs` and `{property}{sides}-{breakpoint}-{size}` for `sm`, `md`, `lg`, and `xl`.
+The classes are named using the format `{property}{sides}-{size}` for `xs` and `{property}{sides}-{breakpoint}-{size}` for `sm`, `md`, `lg`, `xl`, and `xxl`.
 
 Where *property* is one of:
 

site/data/breakpoints.yml

 - breakpoint: xs
   abbr: ""
-  name: Extra small
+  name: X-Small
   min-width: 0px
   container: ""
 
@@ -24,6 +24,12 @@
 
 - breakpoint: xl
   abbr: -xl
-  name: Extra large
+  name: X-Large
   min-width: 1200px
   container: 1140px
+
+- breakpoint: xxl
+  abbr: -xxl
+  name: XX-Large
+  min-width: 1400px
+  container: 1320px

site/data/sidebar.yml

@@ -14,9 +14,14 @@
 
 - title: Layout
   pages:
-    - title: Overview
+    - title: Breakpoints
+    - title: Containers
     - title: Grid
-    - title: Utilities for layout
+    # - title: Rows
+    - title: Columns
+    - title: Gutters
+    - title: Utilities
+    - title: Z-index
 
 - title: Content
   pages:

site/layouts/_default/docs.html

@@ -9,40 +9,40 @@
     {{ partial "docs-navbar" . }}
     {{ partial "docs-subnav" . }}
 
-    <div class="container-xl my-4">
-      <div class="row flex-xl-nowrap">
-        <div class="col-md-3">
-          {{ partial "docs-sidebar" . }}
-        </div>
+    <div class="container-xxl my-4 bd-layout">
+      <div class="bd-sidebar">
+        {{ partial "docs-sidebar" . }}
+      </div>
 
-        <main class="col-md-9 py-md-3 pl-md-5 bd-content">
-          <h1 class="bd-title" id="content">{{ .Title | markdownify }}</h1>
-          <p class="bd-lead">{{ .Page.Params.Description | markdownify }}</p>
-          {{ partial "ads" . }}
+      <div class="bd-intro pt-md-3 pl-lg-4">
+        <h1 class="bd-title" id="content">{{ .Title | markdownify }}</h1>
+        <p class="bd-lead">{{ .Page.Params.Description | markdownify }}</p>
+        {{ partial "ads" . }}
+      </div>
 
-          {{ if .Page.Params.sections }}
-            <div class="row my-5">
-              {{ range .Page.Params.sections }}
-                <div class="col-md-6 mb-4">
-                  <a class="d-block text-decoration-none" href="../{{ urlize .title }}/">
-                    <strong class="d-block h5 mb-0">{{ .title }}</strong>
-                    <span class="text-secondary">{{ .description }}</span>
-                  </a>
-                </div>
-              {{ end }}
-            </div>
-          {{ end }}
+      {{ if (eq .Page.Params.toc true) }}
+        <div class="bd-toc pl-xl-3 text-muted mb-lg-5">
+          <strong class="d-block h6 my-2 pb-2 border-bottom">On this page</strong>
+          {{ .TableOfContents }}
+        </div>
+      {{ end }}
 
-          {{ if (eq .Page.Params.toc true) }}
-            <strong class="d-block h3 mt-5 mb-3">On this page</strong>
-            <nav class="bd-toc mb-5 text-muted" aria-label="Secondary navigation">
-              {{ .TableOfContents }}
-            </nav>
-          {{ end }}
+      <main class="bd-content pl-lg-4">
+        {{ if .Page.Params.sections }}
+          <div class="row g-3">
+            {{ range .Page.Params.sections }}
+            <div class="col-md-6">
+              <a class="d-block text-decoration-none" href="../{{ urlize .title }}/">
+                <strong class="d-block h5 mb-0">{{ .title }}</strong>
+                <span class="text-secondary">{{ .description }}</span>
+              </a>
+            </div>
+            {{ end }}
+          </div>
+        {{ end }}
 
-          {{ .Content }}
-        </main>
-      </div>
+        {{ .Content }}
+      </main>
     </div>
 
     {{ partial "footer" . }}

site/layouts/partials/callout-info-mediaqueries-breakpoints.md

-Note that since browsers do not currently support [range context queries](https://www.w3.org/TR/mediaqueries-4/#range-context), we work around the limitations of [`min-` and `max-` prefixes](https://www.w3.org/TR/mediaqueries-4/#mq-min-max) and viewports with fractional widths (which can occur under certain conditions on high-dpi devices, for instance) by using values with higher precision for these comparisons.
+**Why subtract .02px?** Browsers don't currently support [range context queries](https://www.w3.org/TR/mediaqueries-4/#range-context), so we work around the limitations of [`min-` and `max-` prefixes](https://www.w3.org/TR/mediaqueries-4/#mq-min-max) and viewports with fractional widths (which can occur under certain conditions on high-dpi devices, for instance) by using values with higher precision.

site/layouts/partials/home/masthead-followup.html

@@ -23,7 +23,7 @@
   <p class="lead lead-lg mw-md-75 mx-auto">
     Use the <a href="https://www.bootstrapcdn.com/">BootstrapCDN</a> to deliver fast, cached, and compiled versions of Bootstrap’s CSS and JavaScript. No jQuery is required, but don't forget to include Popper.js for some components.
   </p>
-  <a class="btn btn-lg btn-outline-primary mb-4" href="/docs/{{ .Site.Params.docs_version }}/layout/overview/">Explore the docs</a>
+  <a class="btn btn-lg btn-outline-primary mb-4" href="/docs/{{ .Site.Params.docs_version }}/getting-started/introduction">Explore the docs</a>
   <div class="text-left mx-md-5 px-md-5">
     <h5>CSS only</h5>
     {{ highlight (printf (`<link rel="stylesheet" href="%s" integrity="%s" crossorigin="anonymous">`) .Site.Params.cdn.css .Site.Params.cdn.css_hash) "html" "" }}