Merge branch 'main' into main-xmr-docs-render-headingmain-xmr-docs-render-heading

1 files changed, 13 insertions, 9 deletions

diff --git a/site/content/docs/5.1/components/buttons.md b/site/content/docs/5.1/components/buttons.md
index d62d6e2b6..1f279ffd7 100644
--- a/site/content/docs/5.1/components/buttons.md
+++ b/site/content/docs/5.1/components/buttons.md
@@ -85,18 +85,22 @@ Disabled buttons using the `<a>` element behave a bit different:
 
 - `<a>`s don't support the `disabled` attribute, so you must add the `.disabled` class to make it visually appear disabled.
 - Some future-friendly styles are included to disable all `pointer-events` on anchor buttons.
-- Disabled buttons should include the `aria-disabled="true"` attribute to indicate the state of the element to assistive technologies.
+- Disabled buttons using `<a>` should include the `aria-disabled="true"` attribute to indicate the state of the element to assistive technologies.
+- Disabled buttons using `<a>` *should not* include the `href` attribute.
 
 {{< example >}}
-<a href="#" class="btn btn-primary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Primary link</a>
-<a href="#" class="btn btn-secondary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Link</a>
+<a class="btn btn-primary btn-lg disabled" role="button" aria-disabled="true">Primary link</a>
+<a class="btn btn-secondary btn-lg disabled" role="button" aria-disabled="true">Link</a>
 {{< /example >}}
 
-{{< callout warning >}}
-##### Link functionality caveat
+### Link functionality caveat
 
-The `.disabled` class uses `pointer-events: none` to try to disable the link functionality of `<a>`s, but that CSS property is not yet standardized. In addition, even in browsers that do support `pointer-events: none`, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, in addition to `aria-disabled="true"`, also include a `tabindex="-1"` attribute on these links to prevent them from receiving keyboard focus, and use custom JavaScript to disable their functionality altogether.
-{{< /callout >}}
+To cover cases where you have to keep the `href` attribute on a disabled link, the `.disabled` class uses `pointer-events: none` to try to disable the link functionality of `<a>`s. Note that this CSS property is not yet standardized for HTML, but all modern browsers support it. In addition, even in browsers that do support `pointer-events: none`, keyboard navigation remains unaffected, meaning that sighted keyboard users and users of assistive technologies will still be able to activate these links. So to be safe, in addition to `aria-disabled="true"`, also include a `tabindex="-1"` attribute on these links to prevent them from receiving keyboard focus, and use custom JavaScript to disable their functionality altogether.
+
+{{< example >}}
+<a href="#" class="btn btn-primary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Primary link</a>
+<a href="#" class="btn btn-secondary btn-lg disabled" tabindex="-1" role="button" aria-disabled="true">Link</a>
+{{< /example >}}
 
 ## Block buttons
 
@@ -157,7 +161,7 @@ Add `data-bs-toggle="button"` to toggle a button's `active` state. If you're pre
 {{< example >}}
 <a href="#" class="btn btn-primary" role="button" data-bs-toggle="button">Toggle link</a>
 <a href="#" class="btn btn-primary active" role="button" data-bs-toggle="button" aria-pressed="true">Active toggle link</a>
-<a href="#" class="btn btn-primary disabled" tabindex="-1" aria-disabled="true" role="button" data-bs-toggle="button">Disabled toggle link</a>
+<a class="btn btn-primary disabled" aria-disabled="true" role="button" data-bs-toggle="button">Disabled toggle link</a>
 {{< /example >}}
 
 ### Methods
@@ -206,7 +210,7 @@ var bsButton = new bootstrap.Button(button)
         <code>getOrCreateInstance</code>
       </td>
       <td>
-        Static method which returns a button instance associated to a DOM element or create a new one in case it wasn't initialised.
+        Static method which returns a button instance associated to a DOM element or create a new one in case it wasn't initialized.
         You can use it like this: <code>bootstrap.Button.getOrCreateInstance(element)</code>
       </td>
     </tr>