docs(examples): new cheatsheet and RTL examples

2026-06-11 18:02:28 +03:00 · 2020-06-09 16:44:20 +03:00
parent 9488978fb5
commit aaff11a0b3
95 changed files with 5206 additions and 298 deletions
@@ -71,6 +71,10 @@ Bootstrap uses [Autoprefixer][autoprefixer] (included in our build process) to a

 We maintain the list of browsers supported through Autoprefixer in a separate file within our GitHub repository. See [.browserslistrc]({{< param repo >}}/blob/v{{< param current_version >}}/.browserslistrc) for details.

+## RTLCSS
+
+Bootstrap uses [RTLCSS](https://rtlcss.com/) to process compiled CSS and convert them to RTL – basically replacing horizontal direction aware properties (eg. `padding-left`) with their opposite. It allows us only write our CSS a single time and make minor tweaks using RTLCSS [control](https://rtlcss.com/learn/usage-guide/control-directives/) and [value](https://rtlcss.com/learn/usage-guide/value-directives/) directives.
+
 ## Local documentation

 Running our documentation locally requires the use of Hugo, which gets installed via the [hugo-bin](https://www.npmjs.com/package/hugo-bin) npm package. Hugo is a blazingly fast and quite extensible static site generator that provides us: basic includes, Markdown-based files, templates, and more. Here's how to get it started:
@@ -19,18 +19,34 @@ bootstrap/
 │   ├── bootstrap-grid.css.map
 │   ├── bootstrap-grid.min.css
 │   ├── bootstrap-grid.min.css.map
+│   ├── bootstrap-grid.rtl.css
+│   ├── bootstrap-grid.rtl.css.map
+│   ├── bootstrap-grid.rtl.min.css
+│   ├── bootstrap-grid.rtl.min.css.map
 │   ├── bootstrap-reboot.css
 │   ├── bootstrap-reboot.css.map
 │   ├── bootstrap-reboot.min.css
 │   ├── bootstrap-reboot.min.css.map
+│   ├── bootstrap-reboot.rtl.css
+│   ├── bootstrap-reboot.rtl.css.map
+│   ├── bootstrap-reboot.rtl.min.css
+│   ├── bootstrap-reboot.rtl.min.css.map
 │   ├── bootstrap-utilities.css
 │   ├── bootstrap-utilities.css.map
 │   ├── bootstrap-utilities.min.css
 │   ├── bootstrap-utilities.min.css.map
+│   ├── bootstrap-utilities.rtl.css
+│   ├── bootstrap-utilities.rtl.css.map
+│   ├── bootstrap-utilities.rtl.min.css
+│   ├── bootstrap-utilities.rtl.min.css.map
 │   ├── bootstrap.css
 │   ├── bootstrap.css.map
 │   ├── bootstrap.min.css
-│   └── bootstrap.min.css.map
+│   ├── bootstrap.min.css.map
+│   ├── bootstrap.rtl.css
+│   ├── bootstrap.rtl.css.map
+│   ├── bootstrap.rtl.min.css
+│   └── bootstrap.rtl.min.css.map
 └── js/
    ├── bootstrap.bundle.js
    ├── bootstrap.bundle.js.map
@@ -66,7 +82,9 @@ Bootstrap includes a handful of options for including some or all of our compile
    <tr>
      <th scope="row">
        <div><code class="fw-normal text-nowrap">bootstrap.css</code></div>
+        <div><code class="fw-normal text-nowrap">bootstrap.rtl.css</code></div>
        <div><code class="fw-normal text-nowrap">bootstrap.min.css</code></div>
+        <div><code class="fw-normal text-nowrap">bootstrap.rtl.min.css</code></div>
      </th>
      <td>Included</td>
      <td>Included</td>
@@ -76,7 +94,9 @@ Bootstrap includes a handful of options for including some or all of our compile
    <tr>
      <th scope="row">
        <div><code class="fw-normal text-nowrap">bootstrap-grid.css</code></div>
+        <div><code class="fw-normal text-nowrap">bootstrap-grid.rtl.css</code></div>
        <div><code class="fw-normal text-nowrap">bootstrap-grid.min.css</code></div>
+        <div><code class="fw-normal text-nowrap">bootstrap-grid.rtl.min.css</code></div>
      </th>
      <td><a class="link-secondary" href="{{< docsref "/layout/grid" >}}">Only grid system</a></td>
      <td class="text-muted">&mdash;</td>
@@ -86,7 +106,9 @@ Bootstrap includes a handful of options for including some or all of our compile
    <tr>
      <th scope="row">
        <div><code class="fw-normal text-nowrap">bootstrap-utilities.css</code></div>
+        <div><code class="fw-normal text-nowrap">bootstrap-utilities.rtl.css</code></div>
        <div><code class="fw-normal text-nowrap">bootstrap-utilities.min.css</code></div>
+        <div><code class="fw-normal text-nowrap">bootstrap-utilities.rtl.min.css</code></div>
      </th>
      <td class="text-muted">&mdash;</td>
      <td class="text-muted">&mdash;</td>
@@ -96,7 +118,9 @@ Bootstrap includes a handful of options for including some or all of our compile
    <tr>
      <th scope="row">
        <div><code class="fw-normal text-nowrap">bootstrap-reboot.css</code></div>
+        <div><code class="fw-normal text-nowrap">bootstrap-reboot.rtl.css</code></div>
        <div><code class="fw-normal text-nowrap">bootstrap-reboot.min.css</code></div>
+        <div><code class="fw-normal text-nowrap">bootstrap-reboot.rtl.min.css</code></div>
      </th>
      <td class="text-muted">&mdash;</td>
      <td><a class="link-secondary" href="{{< docsref "/content/reboot" >}}">Only Reboot</a></td>
@@ -0,0 +1,138 @@
+---
+layout: docs
+title: RTL
+description: Learn how to enable support for right-to-left text in Bootstrap across our layout, components, and utilities.
+group: getting-started
+toc: true
+---
+
+## Get familiar
+
+We recommend getting familiar with Bootstrap first by reading through our [Getting Started Introduction page]({{< docsref "/getting-started/introduction" >}}). Once you've run through it, continue reading here for how to enable RTL.
+
+You may also want to read up on [the RTLCSS project](https://rtlcss.com/), as it powers our approach to RTL.
+
+{{< callout warning >}}
+### Experimental feature
+
+The RTL feature is still **experimental** and will probably evolve according to user feedback. Spotted something or have an improvement to suggest? [Open an issue]({{< param repo >}}/issues/new), we'd love to get your insights.
+{{< /callout >}}
+
+## Required HTML
+
+There are two strict requirements for enabling RTL in Bootstrap-powered pages.
+
+1. Set `dir="rtl"` on the `<html>` element.
+2. Add an appropriate `lang` attribute, like `lang="ar"`, on the `<html>` element.
+
+From there, you'll need to include an RTL version of our CSS. For example, here's the stylesheet for our compiled and minified CSS with RTL enabled:
+
+{{< highlight html >}}
+<link rel="stylesheet" href="{{< param "cdn.css_rtl" >}}" integrity="{{< param "cdn.css_rtl_hash" >}}" crossorigin="anonymous">
+{{< /highlight >}}
+
+### Starter template
+
+You can see the above requirements reflected in this modified RTL starter template.
+
+{{< highlight html >}}
+<!doctype html>
+<html lang="ar" dir="rtl">
+  <head>
+    <!-- Required meta tags -->
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    <!-- Bootstrap CSS -->
+    <link rel="stylesheet" href="{{< param "cdn.css_rtl" >}}" integrity="{{< param "cdn.css_rtl_hash" >}}" crossorigin="anonymous">
+
+    <title>مرحبا بالعالم!</title>
+  </head>
+  <body>
+    <h1>مرحبا بالعالم!</h1>
+
+    <!-- Optional JavaScript -->
+    <!-- Popper.js first, then 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>
+  </body>
+</html>
+{{< /highlight >}}
+
+### RTL examples
+
+Get started with one of our several [RTL examples]({{< docsref "/examples/#rtl" >}}).
+
+## Approach
+
+Our approach to building RTL support into Bootstrap comes with two important decisions that impact how we write and use our CSS:
+
+1. **First, we decided to build it with the [RTLCSS](https://rtlcss.com/) project.** This gives us some powerful features for managing changes and overrides when moving from LTR to RTL. It also allows us to build two versions of Bootstrap from one codebase.
+
+2. **Second, we've renamed a handful of directional classes to adopt a logical properties approach.** Most of you have already interacted with logical properties thanks to our flex utilities—they replace direction properties like `left` and `right` in favor `start` and `end`. That makes the class names and values appropriate for LTR and RTL without any overhead.
+
+  For example, instead of `.ml-3` for `margin-left`, use `.ms-3`.
+
+Working with RTL, through our source Sass or compiled CSS, shouldn't be much different from our default LTR though.
+
+## Customize from source
+
+When it comes to [customization]({{< docsref "/customize/sass" >}}), the preferred way is to take advantage of variables, maps, and mixins. This approach works the same for RTL, even if it's post-processed from the compiled files, thanks to [how RTLCSS works](https://rtlcss.com/learn/getting-started/why-rtlcss/).
+
+### Custom RTL values
+
+Using [RTLCSS value directives](https://rtlcss.com/learn/usage-guide/value-directives/), you can make a variable output a different value for RTL. For example, to decrease the weight for `$font-weight-bold` throughout the codebase, you may use the `/*rtl: {value}*/` syntax:
+
+{{< highlight scss >}}
+$font-weight-bold: 700 #{/* rtl:600 */} !default;
+{{< /highlight >}}
+
+Which would ouput to the following for our default CSS and RTL CSS:
+
+{{< highlight css >}}
+/* bootstrap.css */
+dt {
+  font-weight: 700 /* rtl:600 */;
+}
+
+/* bootstrap.rtl.css */
+dt {
+  font-weight: 600;
+}
+{{< /highlight >}}
+
+### Alternative font stack
+
+In the case you're using a custom font, be aware that not all fonts support the non-Latin alphabet. To switch from Pan-European to Arabic family, you may need to use `/*rtl:insert: {value}*/` in your font stack to modify the names of font families.
+
+For example, to switch from `Helvetica Neue Webfont` for LTR to `Helvetica Neue Arabic` for RTL, your Sass code look like this:
+
+{{< highlight scss >}}
+$font-family-sans-serif:
+  Helvetica Neue #{"/* rtl:insert:Arabic */"},
+  // Safari for macOS and iOS (San Francisco)
+  -apple-system,
+  // Chrome < 56 for macOS (San Francisco)
+  BlinkMacSystemFont,
+  // Windows
+  "Segoe UI",
+  // Android
+  Roboto,
+  // Basic web fallback
+  Arial,
+  // Linux
+  "Noto Sans",
+  // Sans serif fallback
+  sans-serif,
+  // Emoji fonts
+  "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji" !default;
+{{< /highlight >}}
+
+## 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`.
+
+## Additional resources
+
+- [RTLCSS](https://rtlcss.com/)
+- [RTL Styling 101](https://rtlstyling.com/posts/rtl-styling)