How to place readme.md on the top of the page

Question

I wrote a readme.md file for my git page. Now I wanna advertise for my program on some forums. I don't want to always update every single forum entry, so I though I just link to my git repo and they people can get the information about my tool just by reading the readme (in the future, all I need to is update this single file).

However, the source files are placed on the top and 99% of the people that will visit my repo won't have a clue about code. Therefore it would attract people more if they just see the readme.md instead of code (which might scare them away "oh I don't get it and it looks to hard to get a fast overview leave").

Is there a way to switch the code section with the readme.md section?

Answer 1

Is there a way to switch the code section with the readme.md section?

There is not for now in a classic GitHub repo.

One workaround would be to limit the number of top elements to a minimum, moving all those folders into a src/ or project/ subfolder.

That would make the code section very short, and the README (just below) that much more visible.

A different repo, as commented by the OP TrudleR, is available with GitHub pages, like a project site using the gh-pages branch.

For that approach, I like to declare that branch as a submodule in the master branch of the same project repo: that way, I can update my project pages while updating the sources of the project itself.

---

Update August 2016: Simpler GitHub Pages publishing now allows to keep your page files in a subfolder of the same branch (no more gh-pages needed):

Those pages can be in a subfolder of the same branch now.