I just tested Pages on one of my repositorie, with Jekyll theme. But there is several things that works nice in normal readme and isn't displayed in pages, the main one being images. I don't want to use different md files for github and pages, won't spend more time updating both. So if there is no solution, no problem, I won't use pages and that's all.
Example working nice on readme.md:
<img align="right" src="https://bibi.com/bibi.jpg" width=96>
Such declaration is wrote as string on pages, all < and > being encoded.
I also can't find how to set [title](link) syntax with a specified image size and alignement.
Have search for this on the web, but no real answer. Or maybe by installing plugins, config.yaml and lot of time to just display a readme ...
I've seen discourse support [title|96x96](link) but this doesn't work on github. And still no aligment option.
Is it something that will evolve in futur github Pages ? Or maybe another simple Pages theme that support this ?
Customized formatting like what you're trying to do is tough to get right in both the GitHub-presented README and the Jekyll-presented GitHub Pages site. For example, if you look at this README file on GitHub you see:
with the HTML image formatted correctly but the Markdown-syntax one formatted incorrectly. But if you look at it on the Pages site you see:
with the Markdown image formatted correctly and the HTML image not displayed at all.
However, if you give up the custom sizing and the alignment, then the README and the Pages site will both be formatted very similarly. If you want something more than that, it is possible, it just requires quite a bit more work. The fast and easy version is to work within the subset of Markdown that both GitHub's front-end and Kramdown, the Markdown parser that Jekyll uses, both understand.
I hope that helps!