CONTRIBUTING.md does not render as a web page on github pages

Question

i'm in the process of moving my contributing.md file from the project root to the docs/ directory so it can be with the rest of the documentation. Other markdown files in docs render properly when viewed in github pages. For example, the page

https://jtablesaw.github.io/tablesaw/userguide/toc renders the page toc.md as expected.

however,

https://jtablesaw.github.io/tablesaw/contributing

returns a 404, while simply adding the .md extension

https://jtablesaw.github.io/tablesaw/contributing.md

returns the page as markdown source

The github project is https://github.com/jtablesaw/tablesaw. and the contributing.md file is in the docs/ folder.

Answer 1

Zachary's answer is correct but there is a way to modify the jekyll's configuration to include the specific page.

Here is an example: https://masterex.github.io/test-docs/contributing

You have to modify _config.yml as follows:

theme: jekyll-theme-minimal
include: contributing.md

Here is github's relevant help page.

Answer 2

After forking your repo, playing around with it for a bit, and banging my head against the wall because I didn't understand why it wasn't working, I realized something:

Github Pages doesn't support building Jekyll pages from files that have names that Github recognizes for other purposes. These file names include (in addition to their lowercase versions):

• CONTRIBUTING.md
• ISSUE_TEMPLATE.md
• PULL_REQUEST_TEMPLATE.md
• ISSUE_AND_PULL_REQUEST_TEMPLATE.md
• CODEOWNERS.md

On the other hand, despite that README.md is also a Github keyword file, it looks like Github Pages supports using files with the README.md name because it purposely will interpret them the same way as an index.md or index.html file. See this link from the Github blog for more information.

---

To answer your specific question on how you could get the file to show at the /tablesaw/contributing path, you could rename it and move it to the /docs/contributing/index.md or /docs/contributing/README.md path.

U̶n̶f̶o̶r̶t̶u̶n̶a̶t̶e̶l̶y̶,̶ ̶a̶t̶ ̶l̶e̶a̶s̶t̶ ̶i̶n̶ ̶t̶h̶e̶ ̶p̶r̶e̶s̶e̶n̶t̶,̶ ̶t̶h̶e̶r̶e̶'̶s̶ ̶c̶u̶r̶r̶e̶n̶t̶l̶y̶ ̶n̶o̶ ̶w̶a̶y̶ ̶t̶o̶ ̶k̶e̶e̶p̶ ̶i̶t̶ ̶w̶i̶t̶h̶ ̶t̶h̶e̶ ̶s̶a̶m̶e̶ ̶f̶i̶l̶e̶ ̶n̶a̶m̶e̶ ̶a̶n̶d̶ ̶h̶a̶v̶e̶ ̶G̶i̶t̶h̶u̶b̶ ̶P̶a̶g̶e̶s̶ ̶b̶u̶i̶l̶d̶ ̶a̶ ̶p̶a̶g̶e̶ ̶f̶o̶r̶ ̶i̶t̶.̶

---

Edit: @Master_ex notes correctly that you can use the include configuration option in the _config.yml file to include files that would normally be excluded by Github:

theme:   jekyll-theme-minimal
include: contributing.md

In reference to the original example, this will allow Github Pages to build a page successfully at the /docs/contributing path.