fix: improve formatting of RTL content creation instructions in documentation

zakariaf · zakariaf · commit 001b093580da · 2025-05-23T19:34:38.000+02:00
fix: swap float directions for images in Persian RTL content

fix: remove duplicated font source and unicode-range for RTL fonts

fix: update font weights for RTL language stylesheets

fix: add spaces to read time unit and prompt for better formatting

fix: reorder RTL font loader inclusion for rendering after googlefonts

fix: update RTL language configuration to use 'fa' instead of 'fa-IR' for better compatibility

fix: add transform to sidebar for better responsiveness in RTL layout

fix: add RTL Support feature to README

fix: update RTL support comments for clarity

fix: enhance RTL support documentation for clarity and usability

fix: correct meta format in fa.yml for clarity

Signed-off-by: Zakaria Fatahi &lt;zakaria@buzzjective.com&gt;

fix: improve sidebar transform handling for RTL layout in mobile
diff --git a/README.md b/README.md
@@ -38,6 +38,7 @@
 - PWA
 - Web Analytics
 - SEO & Performance Optimization
+- RTL Support
 
 ## Documentation
 
diff --git a/_config.yml b/_config.yml
@@ -3,15 +3,21 @@
 # Import the theme
 theme: jekyll-theme-chirpy
 
-# RTL Support Configuration
-# Set this to true to enable RTL support for all languages
-# If false, RTL will only be applied to RTL languages (ar, he, fa, etc.)
+# Force RTL mode for the entire website
+# When set to true, all pages will be rendered right-to-left, regardless of language
+# Useful if your entire site is in an RTL language
+# If enabled, also set one of the RTL languages in rtl_languages list as your site.lang value
 rtl_support: false
 
-# RTL Languages array - add more languages if needed
+# RTL Languages array
+# If you want to have your entire website in an RTL language, and you set rtl_support: true,
+# then set one of these languages for lang: in the _config.yml and your entire website locale will change too.
+# But if rtl_support is false and you just want specific pages in RTL with RTL locale,
+# add 'lang: fa' (or another code from this list) to the front matter of those specific pages.
+# The page will then be displayed in RTL mode with the appropriate font and locale
 rtl_languages:
   - ar
-  - fa-IR
+  - fa
   - ku-IQ
   - ur-PK
   - ps-AF
diff --git a/_data/locales/fa.yml b/_data/locales/fa.yml
@@ -40,7 +40,7 @@ copyright:
     به‌جز مواردی که خلاف آن ذکر شده باشد، محتوای پست‌های این وبلاگ
     تحت مجوز Creative Commons Attribution 4.0 International (CC BY 4.0) توسط نویسنده منتشر شده‌اند.
 
-meta: با استفاده از :PLATFORM قالب :THEME
+meta: با استفاده از قالب :THEME برای :PLATFORM 
 
 not_found:
   statement: متأسفیم، لینک زیر معتبر نیست یا به صفحه‌ای که وجود ندارد اشاره می‌کند.
@@ -58,8 +58,8 @@ post:
   words: کلمه
   pageview_measure: بازدید
   read_time:
-    unit: دقیقه
-    prompt: زمان مطالعه
+    unit: "دقیقه "
+    prompt: " زمان مطالعه"
   relate_posts: بیشتر بخوانید
   share: اشتراک‌گذاری
   button:
diff --git a/_includes/head.html b/_includes/head.html
@@ -57,9 +57,6 @@
     {{ site.title }}
   </title>
 
-  <!-- This ensures the RTL fonts are loaded early in the page rendering process -->
-  {% include rtl-font-loader.html %}
-
   {% include_cached favicons.html %}
 
   <!-- Resource Hints -->
@@ -71,6 +68,9 @@
     {% endfor %}
   {% endunless %}
 
+  <!-- This ensures the RTL fonts are loaded early in the page rendering process -->
+  {% include rtl-font-loader.html %}
+
   <!-- Bootstrap -->
   {% unless jekyll.environment == 'production' %}
     <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.6/dist/css/bootstrap.min.css">
diff --git a/_includes/rtl-font-loader.html b/_includes/rtl-font-loader.html
@@ -5,17 +5,17 @@
 {% include lang.html %}
 
 {% if dir == 'rtl' %}
- {% if lang == 'fa-IR' %}
+ {% if lang == 'fa' %}
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    <link href="https://fonts.googleapis.com/css2?family=Vazirmatn:wght@400;700&display=swap" rel="stylesheet">
+    <link href="https://fonts.googleapis.com/css2?family=Vazirmatn:wght@100..900&display=swap" rel="stylesheet">
   {% elsif lang == 'ur-PK' %}
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    <link href="https://fonts.googleapis.com/css2?family=Noto+Nastaliq+Urdu&display=swap" rel="stylesheet">
+    <link href="https://fonts.googleapis.com/css2?family=Noto+Nastaliq+Urdu:wght@400..700&display=swap" rel="stylesheet">
   {% else %}  <!-- for Arabic and other rtl languages -->
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+Arabic:wght@400;700&display=swap" rel="stylesheet">
+    <link href="https://fonts.googleapis.com/css2?family=Noto+Sans+Arabic:wght@100..900&display=swap" rel="stylesheet">
   {% endif %}
 {% endif %}
diff --git a/_posts/2025-04-20-rtl-test-persian.md b/_posts/2025-04-20-rtl-test-persian.md
@@ -11,7 +11,7 @@ image:
   path: /commons/devices-mockup.png
   lqip: data:image/webp;base64,UklGRpoAAABXRUJQVlA4WAoAAAAQAAAADwAABwAAQUxQSDIAAAARL0AmbZurmr57yyIiqE8oiG0bejIYEQTgqiDA9vqnsUSI6H+oAERp2HZ65qP/VIAWAFZQOCBCAAAA8AEAnQEqEAAIAAVAfCWkAALp8sF8rgRgAP7o9FDvMCkMde9PK7euH5M1m6VWoDXf2FkP3BqV0ZYbO6NA/VFIAAAA
   alt: نمایش واکنش‌گرای قالب Chirpy روی دستگاه‌های مختلف.
-lang: fa-IR
+lang: fa
 ---
 
 ## سرتیترها
@@ -173,17 +173,17 @@ _عرض کامل صفحه و تراز وسط_
 
 ![نمای دسکتاپ](/posts/20190808/mockup.png){: width="972" height="589" .w-75 .normal}
 
-### شناور به سمت چپ
+### شناور به سمت راست
 
-![نمای دسکتاپ](/posts/20190808/mockup.png){: width="972" height="589" .w-50 .left}
+![نمای دسکتاپ](/posts/20190808/mockup.png){: width="972" height="589" .w-50 .right}
 
-لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ، و با استفاده از طراحان گرافیک است، چاپگرها و متون بلکه روزنامه و مجله در ستون و سطرآنچنان که لازم است، و برای شرایط فعلی تکنولوژی مورد نیاز، و کاربردهای متنوع با هدف بهبود ابزارهای کاربردی می باشد.
+لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ، و با استفاده از طراحان گرافیک است، چاپگرها و متون بلکه روزنامه و مجله در ستون و سطرآنچنان که لازم است، و برای شرایط فعلی تکنولوژی مورد نیاز، و کاربردهای متنوع با هدف بهبود ابزارهای کاربردی می باشد. لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ، و با استفاده از طراحان گرافیک است، چاپگرها و متون بلکه روزنامه و مجله در ستون و سطرآنچنان که لازم است، و برای شرایط فعلی تکنولوژی مورد نیاز، و کاربردهای متنوع با هدف بهبود ابزارهای کاربردی می باشد.
 
-### شناور به سمت راست
+### شناور به سمت چپ
 
-![نمای دسکتاپ](/posts/20190808/mockup.png){: width="972" height="589" .w-50 .right}
+![نمای دسکتاپ](/posts/20190808/mockup.png){: width="972" height="589" .w-50 .left}
 
-لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ، و با استفاده از طراحان گرافیک است، چاپگرها و متون بلکه روزنامه و مجله در ستون و سطرآنچنان که لازم است، و برای شرایط فعلی تکنولوژی مورد نیاز، و کاربردهای متنوع با هدف بهبود ابزارهای کاربردی می باشد.
+لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ، و با استفاده از طراحان گرافیک است، چاپگرها و متون بلکه روزنامه و مجله در ستون و سطرآنچنان که لازم است، و برای شرایط فعلی تکنولوژی مورد نیاز، و کاربردهای متنوع با هدف بهبود ابزارهای کاربردی می باشد. لورم ایپسوم متن ساختگی با تولید سادگی نامفهوم از صنعت چاپ، و با استفاده از طراحان گرافیک است، چاپگرها و متون بلکه روزنامه و مجله در ستون و سطرآنچنان که لازم است، و برای شرایط فعلی تکنولوژی مورد نیاز، و کاربردهای متنوع با هدف بهبود ابزارهای کاربردی می باشد.
 
 ### حالت روشن/تاریک و سایه
 
diff --git a/_sass/rtl-fonts.scss b/_sass/rtl-fonts.scss
@@ -8,21 +8,13 @@
   font-style: normal;
   font-weight: 400;
   font-display: swap;
-  src: url('https://fonts.gstatic.com/s/notosansarabic/v18/nwpCtLGrOAZMl5nJ_wfgRg3DrWFZWsnVBJ_sS6tlqHHFlj4wv4o.woff2')
-    format('woff2');
-  unicode-range: U+0600-06FF, U+200C-200E, U+2010-2011, U+204F, U+2E41,
-    U+FB50-FDFF, U+FE80-FEFC;
 }
 
 @font-face {
   font-family: 'Noto Sans Arabic';
   font-style: normal;
   font-weight: 700;
   font-display: swap;
-  src: url('https://fonts.gstatic.com/s/notosansarabic/v18/nwpCtLGrOAZMl5nJ_wfgRg3DrWFZWsnVBJ_sS6tlqHHFlj4wv4o.woff2')
-    format('woff2');
-  unicode-range: U+0600-06FF, U+200C-200E, U+2010-2011, U+204F, U+2E41,
-    U+FB50-FDFF, U+FE80-FEFC;
 }
 
 /* Persian (Farsi) Font */
@@ -31,21 +23,13 @@
   font-style: normal;
   font-weight: 400;
   font-display: swap;
-  src: url('https://fonts.gstatic.com/s/vazirmatn/v13/Dxx78j6PP2D_kU2muijlEcI_MZP9UkS9x6EgRoIqYbU.woff2')
-    format('woff2');
-  unicode-range: U+0600-06FF, U+200C-200E, U+2010-2011, U+204F, U+2E41,
-    U+FB50-FDFF, U+FE80-FEFC;
 }
 
 @font-face {
   font-family: 'Vazirmatn';
   font-style: normal;
   font-weight: 700;
   font-display: swap;
-  src: url('https://fonts.gstatic.com/s/vazirmatn/v13/Dxx78j6PP2D_kU2muijlEcI_MZP9UkS9x6EgRoIqYbU.woff2')
-    format('woff2');
-  unicode-range: U+0600-06FF, U+200C-200E, U+2010-2011, U+204F, U+2E41,
-    U+FB50-FDFF, U+FE80-FEFC;
 }
 
 /* Urdu Font */
@@ -54,11 +38,6 @@
   font-style: normal;
   font-weight: 400;
   font-display: swap;
-  src: url('https://fonts.gstatic.com/s/notonastaliqurdu/v14/LhW4MUPbN-oZdNFcBy1-DJYsEoTq5pudQ9L940.woff2')
-    format('woff2');
-  unicode-range: U+0600-06FF, U+200C-200E, U+2010-2011, U+204F, U+2E41,
-    U+FB50-FDFF, U+FE80-FEFC, U+0660-0669, U+0951-0952, U+1EE00-1EEF9,
-    U+0900-097F;
 }
 
 /* RTL font-family mapping based on lang attribute */
@@ -81,7 +60,7 @@ html[lang^='ar-'] {
   }
 }
 
-html[lang='fa-IR'] {
+html[lang='fa'] {
   &,
   body {
     font-family: 'Vazirmatn', v.$font-family-base;
@@ -118,7 +97,7 @@ html[lang='ur-PK'] {
 }
 
 /* Default RTL font for other RTL languages */
-html[dir='rtl']:not([lang='ar']):not([lang^='ar-']):not([lang='fa-IR']):not(
+html[dir='rtl']:not([lang='ar']):not([lang^='ar-']):not([lang='fa']):not(
     [lang='ur-PK']
   ) {
   &,
diff --git a/_sass/rtl.scss b/_sass/rtl.scss
@@ -9,6 +9,8 @@
 @use 'rtl-fonts';
 
 html[dir='rtl'] {
+  $sidebar-display: 'sidebar-display'; /* the attribute for sidebar display */
+
   /* Basic text direction */
   direction: rtl;
   text-align: right;
@@ -17,9 +19,15 @@ html[dir='rtl'] {
   #sidebar {
     left: auto;
     right: 0;
+
     border-right: none;
     border-left: 1px solid var(--sidebar-border-color);
 
+    @include bp.lt(bp.get(lg)) {
+      transform: translateX(#{v.$sidebar-width});
+      -webkit-transform: translateX(#{v.$sidebar-width});
+    }
+
     .profile-wrapper {
       padding-left: 1.25rem;
       padding-right: 2.5rem;
@@ -30,17 +38,7 @@ html[dir='rtl'] {
       }
     }
 
-    .site-title {
-      text-align: right;
-    }
-
     ul li.nav-item {
-      @include mx.pl-pr(1.5rem);
-
-      @include bp.xxxl {
-        @include mx.pl-pr(2.75rem);
-      }
-
       a.nav-link i {
         margin-right: 0;
         margin-left: 1.5rem;
@@ -68,6 +66,21 @@ html[dir='rtl'] {
     }
   }
 
+  [#{$sidebar-display}] #sidebar {
+    @include bp.lt(bp.get(lg)) {
+      transform: translateX(0);
+      -webkit-transform: translateX(0);
+    }
+  }
+
+  [#{$sidebar-display}] {
+    #main-wrapper {
+      @include bp.lt(bp.get(lg)) {
+        transform: translateX(-#{v.$sidebar-width});
+      }
+    }
+  }
+
   /* Main wrapper */
   #main-wrapper {
     @include bp.lg {
diff --git a/docs/RTL-SUPPORT.md b/docs/RTL-SUPPORT.md
@@ -21,24 +21,32 @@ The Chirpy theme provides support for Right-to-Left (RTL) languages such as Arab
 RTL support can be configured in your `_config.yml` file:
 
 ```yaml
-# RTL Support Configuration
-# Set this to true to enable RTL support for all languages
-# If false, RTL will only be applied to RTL languages (ar, he, fa, etc.)
+# Force RTL mode for the entire website
+# When set to true, all pages will be rendered right-to-left, regardless of language
+# Useful if your entire site is in an RTL language
+# If enabled, also set one of the RTL languages in rtl_languages list as your site.lang value
 rtl_support: false
 
-# RTL Languages array - add more languages if needed
+# RTL Languages array
+# If you want to have your entire website in an RTL language, and you set rtl_support: true,
+# then set one of these languages for lang: in the _config.yml and your entire website locale will change too.
+# But if rtl_support is false and you just want specific pages in RTL with RTL locale,
+# add 'lang: fa' (or another code from this list) to the front matter of those specific pages.
+# The page will then be displayed in RTL mode with the appropriate font and locale
 rtl_languages:
   - ar
-  - fa-IR
-  - he
+  - fa
   - ku-IQ
   - ur-PK
   - ps-AF
   - dv-MV
 ```
 
-- `rtl_support`: If set to `true`, all pages will be rendered in RTL mode regardless of language. If `false` (default), only pages with languages listed in `rtl_languages` will be in RTL mode.
-- `rtl_languages`: An array of language codes that should be rendered in RTL mode. Add your RTL language code to this list if needed.
+- `rtl_support`: When set to `true`, forces RTL mode for the entire website, regardless of language. If enabled, you should also set one of the RTL languages as your main site language (e.g., `lang: fa` in `_config.yml`) to apply the appropriate locale.
+
+- `rtl_languages`: A list of language codes that trigger RTL mode. These can be used in two ways:
+  1. If `rtl_support: true`, set one of these as your site's main language in `_config.yml`
+  2. If `rtl_support: false`, add `lang: fa` (or another code from this list) to the front matter of specific pages you want displayed in RTL mode
 
 ## How It Works
 
@@ -52,27 +60,42 @@ The RTL support works by:
 
 ## Creating RTL Content
 
-To create content in an RTL language:
+You have two options for creating RTL content:
 
-1. Add the appropriate `lang` attribute in the front matter of your post or page:
+### 1. Individual RTL Pages
 
-```yaml
----
-title: عنوان المقال
-author: اسم الكاتب
-date: 2023-01-01
-lang: ar
-# other front matter...
----
-
-محتوى المقال هنا...
-```
+To make a specific page or post display in RTL mode:
+
+- Add the appropriate `lang` attribute in the front matter, using one of the languages defined in `rtl_languages`:
+
+  ```yaml
+  ---
+  title: عنوان المقال
+  author: اسم الكاتب
+  date: 2023-01-01
+  lang: ar
+  # other front matter...
+  ---
+
+  محتوى المقال هنا...
+  ```
+
+- The theme will automatically:
+  - Display only this specific page in RTL mode
+  - Use the appropriate font for the language
+  - Apply the corresponding locale file if available (e.g., `_data/locales/ar.yml`)
+  - The rest of your site will remain in LTR mode
+
+This approach is ideal for multilingual sites where only some content is in RTL languages.
+
+### 2. Entire Site in RTL
 
-2. The theme will automatically detect the language and apply RTL styling and appropriate fonts.
+If your entire site is in an RTL language:
 
-3. When using RTL languages, the whole page will be displayed in RTL mode, including navigation, sidebar, and other UI elements.
+1. Set `rtl_support: true` in your `_config.yml`
+2. All pages will be displayed in RTL mode regardless of their language setting
 
-4. If you've provided a localization file for the language (e.g., `_data/locales/ar.yml`), the theme will use it for UI text.
+This approach is simpler if you don't need to mix RTL and LTR content.
 
 ## Language-Specific Fonts
 
@@ -83,7 +106,7 @@ The theme includes built-in support for several RTL language fonts:
 - **Hebrew**: Noto Sans Hebrew
 - **Urdu**: Noto Nastaliq Urdu
 
-These fonts are automatically applied based on the page's language attribute. For example, if your page has `lang: fa-IR`, the Vazirmatn font will be used.
+These fonts are automatically applied based on the page's language attribute. For example, if your page has `lang: fa`, the Vazirmatn font will be used.
 
 ## Customization
 
