February 16, 2021

Add RTL formatting to GitHub markdown

Recently Abdelhadi Jaffar has translated the Alpine.js documentation to Arabic, and it was added among the other translations on the Alpine.js GitHub repository, all of which are Markdown files so they are nicely rendered and can be read directly on GitHub.

Arabic is written right to left, but GitHub's layout is LTR. This made the Arabic documentation hard to read on GitHub. Fortunately, we can add HTML to Markdown files. I opened a PR (which has been merged) to sprinkle a bit of HTML to change the layout to RTL.

How?

Wrap the whole thing in div[dir="rtl"]:

<div dir="rtl">
# العنوان

ها نحن ذا ، على دروب كنزنا. نسير معاً و أمالنا تسير قبلنا. من غيرنا؟ يقطع درباً مثلنا! درباً خطيرة إلى الجزيرة ، من غيرنا؟
</div>

Wrap code blocks in div[dir="ltr"] (assuming your code is written in a LTR language!):

<div dir="rtl">
# العنوان

ها نحن ذا ، على دروب كنزنا. نسير معاً و أمالنا تسير قبلنا. من غيرنا؟ يقطع درباً مثلنا! درباً خطيرة إلى الجزيرة ، من غيرنا؟

<div dir="ltr">
```js
import 'alpinejs'
```
</div>

</div>

If you have LTR copy/code within RTL copy, it may be a good practice to default to wrapping it in span[dir="ltr"] as some characters may flip to the wrong side. For instance, the brackets () of a function can appear on the left instead the right e.g. myFunction():

<div dir="rtl">
# العنوان

إذا أضفنا <span dir="ltr">`.passive`</span> إلى المتصنّت للحدث، فإن هذا الرمز المميز سيعطل وظيفة <span dir="ltr">`preventDefault()`</span> ولن تعمل على أي حدث يتم تنفيذه. يمكن أن يساعدك أحياناً في تحسين أداء التمرير (scroll) على الأجهزة التي تعمل باللمس.
</div>