Github wiki pages vs markdown/html in main repository.

I’ve noticed that the github “file browser” now renders various types of markup/markdown language files.
What the the technical and philosophical issues WRT putting project documentation in the “wiki” section vs putting .md files in a …/docs directory of the main project?
(And I guess now there is “pages” as well?)


Wiki pages can be edited much more freely than files in the main repository.

  1. They don’t require a pull request or create a commit in the main repository
  2. By default anyone who is a collaborator can edit the wiki and the ability to edit the wiki can be made completely open separate from the main repository

Some people like this method of operation for documentation. Some people prefer keeping the documentation in the main repository (or in a documentation repository that is a peer of the main one). I’m in the latter camp because I like managing documentation using the same tools as everything else.

GitHub Pages isn’t specifically a mechanism for editing or maintaining documentation, though it is often used for that as well. It is a system whereby one can easily publish the contents of a repository (not a wiki) on a website.

I hope that helps!


Is it possible to access a Github-Wiki through Github-Pages?

Hi @jirkadelloro,

I’m not exactly sure what you mean, but GitHub Pages and wikis for repositories aren’t connected in any way.

Hope that helps!

GitHub repository wikis are a very convenient way to write and maintain documentation.
GitHub pages is a convenient way to host documentation with a fancy domain-url.

Being able to use GitHub Pages’ domain feature to render content that one composed in a GitHub repository wiki is a totally reasonable wish/request.

One could create a tiny github pages that just redirects to the wiki, but that doesn’t yield a shiny domain…