Please do not use the README.md file of a GitHub repository as a web page.

I have noticed a pattern that is becoming distressingly common these days. Someone wants to create a web page, specifically for the purpose of writing documentation. Instead of just creating a web page that contains only the content they want to share with no extraneous content, they create a GitHub repository and put the content they want to share in the README.md file for the GitHub repository.

The following is a list of excellent resources that take this approach.

• Awesome C
• Awesome HPP: A curated list of awesome header-only C++ libraries
• The Art of Command Line

There are some benefits to this. There is no need to generate HTML yourself. Just let GitHub do it for you automatically. What could possibly go wrong? Why would anyone find this to be unacceptable.

The reason is that there is a very high cost to to using this approach that makes your content damned annoying to use. GitHub adds a great deal of fluff above and below your content that is completely irrelevant to your content.

I know what you are thinking. You are thinking that I could just scroll down past that fluff and ignore it. The problem is that this is not so easy for a person who relies on a screen reader to do. Besides, it is not professional. A professional would put forth the extra bit of effort to present the content in a way that presents just the content with no fluff!

The moment I see that a page is nothing more that a README.md file for a GitHub repository I become far less inclined to ever visit the page again.

There is nothing wrong with hosting your web page in GitHub. But please, put forth the little bit of extra effort it takes to host is using the GitHub Pages service. The Awesome C+ page is an excellent example of a web page that uses the GitHub Pages service. I find it to be far more usable and accessible than the others I mentioned earlier.