Repository navigation
Fix the order in which README files are chosen #360
Description
Hi @bkeepers
Following the merge of PR #343, everything has been working great, but there is a new issue that has come up. If a repository contains both a README.Rmd and a README.md, GitHub now shows README.Rmd. I'm sure you have some mechanism in place to handle which file to choose when repos contain multiple README files/formats.
Example: https://github.com/ropensci/git2r
Here you see the raw, unparsed Rmd is shown by default, when in fact the parsed README is what needs to be displayed.
So if I were to have README.md, README.rst and README.txt (same repo and same folder), how is the order determined?
If it is possible to set the order, README.md should always be displayed over README.Rmd since the latter contains unparsed code. The purpose of having both files in the same folder is so that with each software update, the author can parse the Rmd file and have the most up to date code rendered into the README.md.
I apologize if this issue needs to go elsewhere so please close and open in the right repo.
Thank you.
Activity
renkun-ken commentedon Sep 13, 2014
Fully agree with @karthik! I would appreciate it if the the display order is set like:
If final result (README.md) exists, show it;
otherwise, show its producer (README.Rmd).
hilaryparker commentedon Sep 13, 2014
Yes, +1 to this! I'm VERY happy with the .Rmd rendering. However, this change has broken my workflow because I use README.Rmd -> README.md as my default way for creating reports.
bkeepers commentedon Sep 14, 2014
Interesting. Currently we just choose the first README that can be rendered, where "first" is determined by the order of the git tree. I don't know if git trees are in any deterministic order.
I'll work on getting this fixed on Monday.
You'll generally get a faster response if you contact [email protected].
jennybc commentedon Sep 14, 2014
👍 to displaying
README.mdby default, even if a (now beautifully rendered!)README.Rmdis also presentleeper commentedon Sep 15, 2014
+1
leeper commentedon Sep 15, 2014
This issue is solved by changing the
.Rmdextension to.rmd. Example: https://github.com/rOpenGov/recallsbkeepers commentedon Sep 15, 2014
This is true. It looks like git trees use asciibetical order, so
.mdcomes after.Rmdand before.rmd.Either way, we don't expect everyone to rename their files, so we will get it fixed.
ymendel commentedon Sep 16, 2014
Your
README.mdfiles should now take precedence over theREADME.Rmdfiles.To answer the question in the original post, generally we look for "formatted" README files before plaintext ones, and we sort them alphabetically (now — it was ASCIIbetical until just a short while ago, hence the problem with
.Rmdfiles). That means, for the specific example, the order isREADME.mdREADME.rstREADME.txt(In all examples, the first element in the list is the one used as the README.)
But that's a little unclear because it's also just plain alphabetic order. If instead of ReStructured Text there were a format called "ZappoText" with an extension
.zt, then we'd haveREADME.mdREADME.ztREADME.txtAnd if the markdown file were deleted, it'd be
README.ztREADME.txtAnd finally, if the only existing file were the plaintext
README.txt, that would be the one used.That's what we do right now, at least. We may do something more sophisticated in the future. We may never find something that works better than this, which is good news for the AsciiDoc fans.
hilaryparker commentedon Sep 16, 2014
Thank you!
Fix README on Github