GHP bad rendering on CONTRIBUTE & HOWTO (fa_IR locale)

[davorpa]

Problem

It seems that Github Pages engine doesn't deal fine rendering links for this RTL resources:

• https://ebookfoundation.github.io/free-programming-books/HOWTO-fa_IR.html
  
• https://ebookfoundation.github.io/free-programming-books/CONTRIBUTE-fa_IR.html
  

It works well in other markdown files like books, courses... for the same locale.

Solution

Maybe due to some issue with the div tag:

free-programming-books/HOWTO-fa_IR.md

Lines 1 to 5 in e629db6

	این متن را در زبان‌های دیگر بخوانید: [English](HOWTO.md), [Français](HOWTO-fr.md), [Español](HOWTO-es.md), [简体中文](HOWTO-zh.md), [हिन्दी](HOWTO-hi.md), [繁體中文](HOWTO-zh-TW.md), [Português (BR)](HOWTO.pt_BR.md)
	<div dir="rtl">
	به Free-Programming-Books خوش آمدید! ما به مشارکت‌کنندگان جدید خوش‌آمد می‌گوییم. حتی آنهایی که اولین پول‌ریکوئست خود را در گیت‌هاب می‌گذارند. اگر شما هم یکی از آنهایید، منابع زیر می‌توانند به شما کمک کنند.

Need some experiments to deal with this tag, and maybe apply on listings too.

[charlottetan]

Spent some time looking into this, it looks like Github's markdown and the <div dir="rtl"> aren't playing well together. To fix it, all of the markdown syntax will need to be changed to regular HTML tags instead of markdown, which include not just the links but also the headings 😧

Tests/examples - Only a couple of links and headings changed:
Code: https://github.com/charlottetan/free-programming-books/commits/master/CONTRIBUTING-fa_IR.md
Github page: https://charlottetan.github.io/free-programming-books/CONTRIBUTING-fa_IR.html

Screenshot with highlighting to show what got changed:

Somewhat related issue filed on Github's markup repo, although the issue here is with github pages' code, not markup since the .md files are rendered fine in Github itself: github/markup#332

[davorpa]

To fix it, all of the markdown syntax will need to be changed to regular HTML tags instead of markdown, which include not just the links but also the headings

It is an option. 💡 The other may be to configure the Jekyll theme well using some gem

[charlottetan]

Thanks for the idea! Didn't realise there was that option, submitted a PR that fixes this issue

[davorpa]

As I comment in #5810 (comment) it's a bit weird why use directly GFM is a bit different of kramdown with input: GFM (default). Maybe, to investigate about it and report to Jekyll project @jekyll.

From default config docs: https://jekyllrb.com/docs/configuration/default/

# Markdown Processors
kramdown:
  auto_ids          : true
  entity_output     : as_char
  toc_levels        : [1, 2, 3, 4, 5, 6]
  smart_quotes      : lsquo,rsquo,ldquo,rdquo
  input             : GFM
  hard_wrap         : false
  footnote_nr       : 1
  show_warnings     : false

[charlottetan]

(Responded in #5810 (comment))