Skip to content

Commit

Permalink
Add PostCSS-RTLCSS approach to the documentation (#39863)
Browse files Browse the repository at this point in the history
* Add PostCSS-RTLCSS approach to the documentation

* Format 'PostCSS RTLCSS' without '-' and backticks

* Some formatting for consistency in the entire doc

* Minor rewording

---------

Co-authored-by: Julien Déramond <juderamond@gmail.com>
  • Loading branch information
elchininet and julien-deramond committed Apr 5, 2024
1 parent f68a47c commit f0252f5
Showing 1 changed file with 10 additions and 0 deletions.
10 changes: 10 additions & 0 deletions site/content/docs/5.3/getting-started/rtl.md
Original file line number Diff line number Diff line change
Expand Up @@ -168,6 +168,16 @@ After running Sass then RTLCSS, each selector in your CSS files will be prepende
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 >}}

Do you want to automate this process and address several edge cases involving both directions within a single stylesheet? Then, consider using [PostCSS RTLCSS](https://github.com/elchininet/postcss-rtlcss) as a [PostCSS](https://github.com/postcss/postcss) plugin to process your source files. PostCSS RTLCSS uses [RTLCSS](https://rtlcss.com) behind the scenes to manage the direction flipping process, but it separates the flipped declarations into rules with a different prefix for LTR and RTL, something that allows you to have both directions within the same stylesheet file. By doing this, you can switch between LTR and RTL orientations by simply changing the `dir` of the page (or even by modifying a specific class if you configure the plugin accordingly).

{{< callout warning >}}
**Important things to take into account** when using PostCSS RTLCSS to build a combined LTR and RTL implementation:

1. It is recommended that you add the `dir` attribute to the `html` element. This way, the entire page will be affected when you change the direction. Also, make sure you add the `lang` attribute accordingly.
2. Having a single bundle with both directions will increase the size of the final stylesheet (on average, by 20%-30%): consider some [optimization]({{< docsref "/customize/optimize" >}}).
3. Take into account that PostCSS RTLCSS is not compatible with `/* rtl:remove */` directives because it doesn't remove any CSS rule. You should replace your `/* rtl:remove */`, `/* rtl:begin:remove */` and `/* rtl:end:remove */` directives with `/* rtl:ignore */`, `/* rtl:begin:ignore */` and `/* rtl:end:ignore */` directives respectively. These directives will ignore the rule and will not create an RTL counterpart (same result as the `remove` ones in RTLCSS).
{{< /callout >}}

## The breadcrumb case

The [breadcrumb separator]({{< docsref "/components/breadcrumb#dividers" >}}) is the only case requiring its own brand-new variable— namely `$breadcrumb-divider-flipped` —defaulting to `$breadcrumb-divider`.
Expand Down

0 comments on commit f0252f5

Please sign in to comment.