RTL support via a single main style file (google#2093)

.vscode/cspell.json

@@ -2,5 +2,13 @@
 {
   "version": "0.2",
   "caseSensitive": true,
-  "words": ["Docsy", "hugo", "shortcode", "shortcodes", "upvote", "warnf"]
+  "words": [
+    "Docsy",
+    "hugo",
+    "shortcode",
+    "shortcodes",
+    "tabpane",
+    "upvote",
+    "warnf"
+  ]
 }

assets/scss/support/_rtl.scss

@@ -1,7 +0,0 @@
-@each $breakpoint, $_ in $container-max-widths {
-  @include media-breakpoint-up($breakpoint) {
-    html[dir="rtl"] .ms-#{$breakpoint}-auto {
-      margin-left: initial !important;
-    }
-  }
-}

layouts/partials/head-css.html

@@ -1,39 +1,30 @@
 {{ $scssMain := "scss/main.scss" -}}
 {{ $css := resources.Get $scssMain
       | toCSS (dict "enableSourceMap" (not hugo.IsProduction)) -}}
-{{ $bsRtlCss := "vendor/bootstrap/dist/css/bootstrap.rtl.css" -}}
-{{ $rtlCSS := "" -}}
+
+{{/* NOTE: we only apply `postCSS` in production or for RTL languages. This
+makes it snappier to develop in Chrome, but it may look sub-optimal in other
+browsers. */ -}}
 
 {{ if eq .Site.Language.LanguageDirection "rtl" -}}
-  {{ with resources.Get $bsRtlCss -}}
-    {{ $rtlCSS = . -}}
-  {{ else -}}
-    {{ $msg := printf "Resource not found: %s" $bsRtlCss -}}
-    {{ warnf $msg -}}
-    <meta name="docsy-info" content="{{ $msg }}">
-  {{ end -}}
+  {{ $css = $css
+      | postCSS (dict "use" "autoprefixer rtlcss" "noMap" true)
+      | resources.Copy (replace $scssMain "." ".rtl.") -}}
+{{ else if hugo.IsProduction -}}
+  {{ $css = $css | postCSS -}}
 {{ end -}}
 
 {{ if hugo.IsProduction -}}
-  {{ with $rtlCSS -}}
-    {{ $rtlCSS = . | postCSS | minify | fingerprint -}}
-  {{ end -}}
-  {{ $css = $css | postCSS | minify | fingerprint -}}
-  <link rel="preload" href="{{ $css.RelPermalink }}" as="style">
-{{- end -}}
-
-{{/* NOTE: when not in production, we don't apply `postCSS`. This makes it
-snappier to develop in Chrome, but makes it look sub-optimal in other browsers.
-*/ -}}
+  {{ $css = $css | minify | fingerprint -}}
+  <link rel="preload" href="{{ $css.RelPermalink }}" as="style" integrity="{{ $css.Data.Integrity }}" crossorigin="anonymous">
+{{ end -}}
 
 {{ with $css -}}
-  <link href="{{ .RelPermalink }}" rel="stylesheet">
+  <link href="{{ .RelPermalink }}" rel="stylesheet"
+  {{- with .Data.Integrity }} integrity="{{ . }}" crossorigin="anonymous"{{ end -}}
+  >
 {{ else -}}
-  {{ errorf "Resource not found: %s" $scssMain -}}
-{{ end -}}
-
-{{ with $rtlCSS -}}
-  <link href="{{ $rtlCSS.RelPermalink }}" rel="stylesheet">
+  {{ errorf "Resource not found or error building CSS: %s" $scssMain -}}
 {{ end -}}
 
 {{- /**/ -}}

userguide/content/en/docs/language/_index.md

@@ -1,17 +1,22 @@
 ---
-title: "Multi-language Support"
-linkTitle: "Multi-language Support"
+title: Multi-language Support
 weight: 7
-description: >
-  Support multiple languages in your site.
+description: Support multiple languages in your site.
 ---
 
-If you'd like to provide site content in multiple languages, the Docsy theme and Hugo make it easy to both add your translated content and for your users to navigate between language versions.
+If you'd like to provide site content in multiple languages, the Docsy theme and
+Hugo make it easy to both add your translated content and for your users to
+navigate between language versions.
 
 ## Content and configuration
 
-To add content in multiple languages, you first need to define the available languages in a `languages` section in your site configuration. Each language can have its own language-specific configuration. For example, the Docsy Example Site config specifies that it provides content in English and Norwegian, and that the language version visitors will see by default is English:
+To add content in multiple languages, you first need to define the available
+languages in a `languages` section in your site configuration. Each language can
+have its own language-specific configuration. For example, the Docsy Example
+Site config specifies that it provides content in English and Norwegian, and
+that the language version visitors will see by default is English:
 
+<!-- prettier-ignore-start -->
 {{< tabpane >}}
 {{< tab header="Configuration file:" disabled=true />}}
 {{< tab header="hugo.toml" lang="toml" >}}
@@ -85,35 +90,73 @@ languages:
 }
 {{< /tab >}}
 {{< /tabpane >}}
+<!-- prettier-ignore-end -->
 
-Any setting not defined in a `[languages]` block will fall back to the global value for that setting: so, for example, the content directory used for the site above will be `content/en` unless the user selects the Norwegian language option.
+Any setting not defined in a `[languages]` block will fall back to the global
+value for that setting: so, for example, the content directory used for the site
+above will be `content/en` unless the user selects the Norwegian language
+option.
 
-Once you've updated your site config, you create a content root directory for each language version in your source repo, such as  `content/en` for English text, and add your [content](/docs/adding-content/content/) as usual. See the [Hugo Docs](https://gohugo.io/content-management/multilingual) on multi-language support for more information.
+Once you've updated your site config, you create a content root directory for
+each language version in your source repo, such as `content/en` for English
+text, and add your [content](/docs/adding-content/content/) as usual. See the
+[Hugo Docs](https://gohugo.io/content-management/multilingual) on multi-language
+support for more information.
+
+{{% alert title="Attention (only when using Docsy as hugo module)" color="warning" %}}
+
+If you have a multi language installation, ensure that the section `[languages]`
+inside your
+[configuration file](https://gohugo.io/getting-started/configuration/#configuration-file)
+is declared **before** the section `[module]` with the module imports. Otherwise
+you will run into trouble!
 
-{{% alert title="Attention (only when using docsy as hugo module)" color="warning" %}}
-If you have a multi language installation, please make sure that the section `[languages]` inside your [configuration file](https://gohugo.io/getting-started/configuration/#configuration-file) is declared **before** the section `[module]` with the module imports. Otherwise you will run into trouble!
 {{% /alert %}}
 
 {{% alert title="Tip" %}}
-If there's any possibility your site might be translated into other languages, consider creating your site with your content in a language-specific subdirectory, as it means you don't need to move it if you add another language.
+
+If there's any possibility your site might be translated into other languages,
+consider creating your site with your content in a language-specific
+subdirectory, as it means you don't need to move it if you add another language.
+
 {{% /alert %}}
 
-For adding multiple language versions of other site elements such as button text, see the [internationalization bundles](#internationalization-bundles) section below.
+For adding multiple language versions of other site elements such as button
+text, see the [internationalization bundles](#internationalization-bundles)
+section below.
 
 ## Selecting a language
 
-If you configure more than one language in your [configuration file](https://gohugo.io/getting-started/configuration/#configuration-file), the Docsy theme adds a language selector drop down to the top-level menu. Selecting a language takes the user to the translated version of the current page, or the home page for the given language.
+If you configure more than one language in your
+[configuration file](https://gohugo.io/getting-started/configuration/#configuration-file),
+the Docsy theme adds a language selector drop down to the top-level menu.
+Selecting a language takes the user to the translated version of the current
+page, or the home page for the given language.
 
 ## Internationalization bundles
 
-All UI strings (text for buttons, repository links, etc.) are bundled inside `/i18n` in the theme, with a `.toml` file for each language.
+All UI strings (text for buttons, repository links, etc.) are bundled inside
+`/i18n` in the theme, with a `.toml` file for each language.
 
-If your chosen language isn't currently in the theme and you create your own `.toml` file for all the common UI strings (for example, if you translate the UI text into Esperanto and create a copy of `en.toml` called `eo.toml`), we recommend you do this **in the theme** rather than in your own project. You can then open a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) to contribute your translation to the Docsy community.
+If your chosen language isn't currently in the theme and you create your own
+`.toml` file for all the common UI strings (for example, if you translate the UI
+text into Esperanto and create a copy of `en.toml` called `eo.toml`), we
+recommend you do this **in the theme** rather than in your own project. You can
+then open a
+[pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
+to contribute your translation to the Docsy community.
 
-{{% alert title="Hugo Tip" %}}
-Run `hugo server --printI18nWarnings` when doing translation work, as it will give you warnings on what strings are missing.
+{{% alert title="Hugo Tip" %}} Run `hugo server --printI18nWarnings` when doing
+translation work, as it will give you warnings on what strings are missing.
 {{% /alert %}}
 
 ### Create custom UI strings
 
-If any of the Docsy theme UI strings in your chosen language aren't suitable for your project, or if you need additional strings for your site, you can create your own project-specific internationalization file in your project's `/i18n` directory. For example, if you want to override any of Docsy's [English-language strings](https://github.com/google/docsy/blob/main/i18n/en.toml), create your own `/i18n/en.toml` with just your custom strings.  Any values you specify in this file will override the theme versions, while the remaining strings will come from the theme's corresponding internationalization bundle.
+If any of the Docsy theme UI strings in your chosen language aren't suitable for
+your project, or if you need additional strings for your site, you can create
+your own project-specific internationalization file in your project's `/i18n`
+directory. For example, if you want to override any of Docsy's
+[English-language strings](https://github.com/google/docsy/blob/main/i18n/en.toml),
+create your own `/i18n/en.toml` with just your custom strings. Any values you
+specify in this file will override the theme versions, while the remaining
+strings will come from the theme's corresponding internationalization bundle.

userguide/package.json

@@ -28,6 +28,7 @@
   },
   "devDependencies": {
     "autoprefixer": "^10.4.20",
-    "postcss-cli": "^11.0.0"
+    "postcss-cli": "^11.0.0",
+    "rtlcss": "^4.3.0"
   }
 }