Add RTL Support

[zakariaf]

Add RTL Support to Jekyll Theme Chirpy

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Improvement (refactoring and improving code)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

Description

This PR adds comprehensive Right-to-Left (RTL) language support to the Chirpy theme. It enables the theme to automatically detect RTL languages and apply appropriate styling, making it accessible to users of Arabic, Kurdish, Persian, Urdu, and other RTL languages.

The implementation:

• Applies appropriate direction and styling for RTL content
• Maintains all existing LTR functionality without changes
• Includes configuration options to customize RTL behavior
• Contains a complete Persian translation of the "Text and Typography" sample post, demonstrating all theme features in RTL mode

Important behavior to note: When viewing a page with an RTL language code (e.g., lang: fa, lang: ar and rtl: true), the theme will automatically switch to RTL mode for that page and use the appropriate locale. This is standard behavior for internationalized websites and follows web accessibility best practices.

Key components:

1. Language/Direction Detection: Added to lang.html to detect RTL languages
2. RTL Stylesheet: Created rtl.scss with comprehensive RTL styling
3. Example Implementation: Provided Persian locale file and sample content

New Files

• _sass/rtl.scss: Contains RTL-specific styles for layout and UI elements
• _data/locales/: locale files as reference implementation:
  • fa-IR.yml: Persian (Modified)
  • ku-IQ.yml: Kurdish (Sorani)
  • ur-PK.yml: Urdu
  • ps-AF.yml: Pashto
  • dv-MV.yml: Dhivehi
• _posts/2025-04-20-rtl-test-persian.md: Persian translation of the sample post(text-and-typography) showcasing all theme features

Modified Files

• _sass/main.scss: Added import for rtl.scss
• _includes/lang.html: Added RTL detection logic
• _layouts/default.html: Added dir attribute to HTML tag
• _config.yml: Added RTL configuration options

This change enhances accessibility for millions of users worldwide who read and write in RTL languages without affecting any existing functionality.

Screenshots

Additional context

This implements a non-breaking enhancement that makes the theme more accessible to global users.

Note: The implementation requires a small addition to head.html to include the RTL font loader, which I've documented in the PR.

This closes the issue #1928 too

[zakariaf]

I'm running my Persian blog based on these changes, and it seems works perfectly. https://zakariafatahi.ir/

[zakariaf]

hello @cotes2020 I just wanted to check if there’s anything else needed from my side to move this PR forward or if there are any concerns about merging it.

[cotes2020]

... I just wanted to check if there’s anything else needed from my side to move this PR forward or if there are any concerns about merging it.

Hi there, this is an excellent PR and thank you for your effort! Since there are quite a lot of changes, I’ll need to find some time to review it. Please don’t worry.

[cotes2020]

Sorry for leaving this PR pending for so long. Here is my initial review:

1. Defining different webfonts for specific languages is too complex and will make the project harder to maintain. Therefore, for languages other than English, it's better to use the system's default fonts.

2. If you want to achieve automatic enabling of the RTL (right-to-left) attribute by intelligently identifying the language, then the configuration file does not need new settings. The Liquid code can identify which languages are RTL.

[zakariaf]

Thank you for the review!

Regarding the font: I agree it's better to keep things simple for maintainability. That said, the default English font renders quite poorly for RTL languages in practice. For now, I’ve removed the custom fonts as suggested, but I’ll experiment with a simpler approach in a future PR—likely by adding something like this to config.yml file:

# Font Configuration
fonts:
  # Base font for body text
  base: ["Source Sans Pro", "Microsoft Yahei", sans-serif]
  # Font for headings
  heading: ["Lato", "Microsoft Yahei", sans-serif]
  # Optional: Google Fonts to load
  google_fonts:
    # - "Roboto:400,700"
    # - "Montserrat:700"

I'll open a separate PR for this to keep things clean.

As for RTL detection via Liquid: I had tested that path, but couldn’t find a reliable way to automatically detect RTL languages purely within Liquid. I’ve simplified the implementation significantly in this PR to make it easier to manage.

Thanks again!

[Nicolai9852]

Hey @zakariaf

I just saw your RTL - it looks really awesome! I did however notice one thing - not sure if it's intentional or not

In the default LTR version, the button to copy the header link is right next to the title
In this RLT it is by the far end to the left side.

From LRT:

RLT:

[cotes2020]

... but couldn’t find a reliable way to automatically detect RTL languages purely within Liquid.

Use this code to automatically detect RTL:

{% assign _lang_code = lang | split: '-' | first %}

{%- case _lang_code -%}
  {%- when 'ar', 'fa', 'he', 'iw', 'kd', 'pk', 'ps', 'ug', 'ur', 'yi' -%}
    {% assign dir = 'rtl' %}
{%- endcase -%}

Additionally, please move the newly added files in _data/locales to a separate PR. The file _posts/2025-04-20-rtl-test-persian.md doesn't need to be included in the repository either.

[zakariaf]

Hey @Nicolai9852, thanks for catching that! I think it was a mistake — I just fixed it. Appreciate you pointing it out!

[zakariaf]

@cotes2020 Thanks so much for the suggestions! I’ve applied all of them. Also, I just created another PR for the new locale files:

#2415

[cotes2020]

The search bar and the trending tags and TOC in the panel are still not vertically aligned. Please test each page locally first. Thank you!

[zakariaf]

I tried to check everything, I think all are fixed now.