Merge branch 'main' into jo-docs-thanks-pagejo-docs-thanks-page

1 files changed, 41 insertions, 3 deletions

diff --git a/site/content/docs/5.0/getting-started/rtl.md b/site/content/docs/5.0/getting-started/rtl.md
index 62287a341..3e1f7a207 100644
--- a/site/content/docs/5.0/getting-started/rtl.md
+++ b/site/content/docs/5.0/getting-started/rtl.md
@@ -53,10 +53,10 @@ You can see the above requirements reflected in this modified RTL starter templa
 
     <!-- Optional JavaScript; choose one of the two! -->
 
-    <!-- Option 1: Bootstrap Bundle with Popper.js -->
+    <!-- Option 1: Bootstrap Bundle with Popper -->
     <script src="{{< param "cdn.js_bundle" >}}" integrity="{{< param "cdn.js_bundle_hash" >}}" crossorigin="anonymous"></script>
 
-    <!-- Option 2: Separate Popper.js and Bootstrap JS -->
+    <!-- Option 2: Separate Popper and Bootstrap JS -->
     <!--
     <script src="{{< param "cdn.popper" >}}" integrity="{{< param "cdn.popper_hash" >}}" crossorigin="anonymous"></script>
     <script src="{{< param "cdn.js" >}}" integrity="{{< param "cdn.js_hash" >}}" crossorigin="anonymous"></script>
@@ -93,7 +93,7 @@ Using [RTLCSS value directives](https://rtlcss.com/learn/usage-guide/value-direc
 $font-weight-bold: 700 #{/* rtl:600 */} !default;
 ```
 
-Which would ouput to the following for our default CSS and RTL CSS:
+Which would output to the following for our default CSS and RTL CSS:
 
 ```css
 /* bootstrap.css */
@@ -116,6 +116,8 @@ For example, to switch from `Helvetica Neue Webfont` for LTR to `Helvetica Neue
 ```scss
 $font-family-sans-serif:
   Helvetica Neue #{"/* rtl:insert:Arabic */"},
+  // Cross-platform generic font family (default user interface font)
+  system-ui,
   // Safari for macOS and iOS (San Francisco)
   -apple-system,
   // Chrome < 56 for macOS (San Francisco)
@@ -134,6 +136,42 @@ $font-family-sans-serif:
   "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji" !default;
 ```
 
+### LTR and RTL at the same time
+
+Need both LTR and RTL on the same page? Thanks to [RTLCSS String Maps](https://rtlcss.com/learn/usage-guide/string-map/), this is pretty straightforward. Wrap your `@import`s with a class, and set a custom rename rule for RTLCSS:
+
+```scss
+/* rtl:begin:options: {
+  "autoRename": true,
+  "stringMap":[
+    "name": "ltr-rtl",
+    "priority": 100,
+    "search": ["ltr"],
+    "replace": ["rtl"],
+    "options": {
+      "scope": "*",
+      "ignoreCase": false
+    }
+  ]
+} */
+.ltr {
+  @import "../node_modules/bootstrap/scss/bootstrap";
+}
+/*rtl:end:options*/
+```
+
+After running Sass then RTLCSS, each selector in your CSS files will be prepended by `.ltr`, and `.rtl` for RTL files. Now you're able to use both files on the same page, and simply use `.ltr` or `.rtl` on your components wrappers to use one or the other direction.
+
+{{< callout warning >}}
+#### Edge cases and known limitations
+
+While this approach is understandable, please pay attention to the following:
+
+1. When switching `.ltr` and `.rtl`, make sure you add `dir` and `lang` attributes accordingly.
+2. Loading both files can be a real performance bottleneck: consider some [optimization]({{< docsref "/customize/optimize" >}}), and maybe try to [load one of those files asynchronously](https://www.filamentgroup.com/lab/load-css-simpler/).
+3. Nesting styles this way will prevent our `form-validation-state()` mixin from working as intended, thus require you tweak it a bit by yourself. [See #31223](https://github.com/twbs/bootstrap/issues/31223).
+{{< /callout >}}
+
 ## The breadcrumb case
 
 The [breadcrumb separator]({{< docsref "/components/breadcrumb" >}}/#changing-the-separator) is the only case requiring its own brand new variable— namely `$breadcrumb-divider-flipped` —defaulting to `$breadcrumb-divider`.