Can github-pages work with only a .md, no .html no jekyll, like gist.github?

Question

Gist.github displays .md files with 0 effort on my part. Can github pages do that too -- no user html, no jekyll ? https://github.com/blog/2289-publishing-with-github-pages-now-as-easy-as-1-2-3 says

Create a repository (or navigate to an existing repository)

Commit a Markdown file via the web interface, just like you would any other file

Activate GitHub Pages via your repository's settings
And that's it
...
We'll use your README file as the site's index if you don't have an index.md (or index.html)

But this doesn't seem to work, or I've misunderstood. Has anyone else tried this flow ? Symptom:

Your GitHub Pages site is currently being built from the /docs folder in the master branch
Your site is published at https://denis-bz.github.io/test-gh-pages/

hangs -- 404, hours later.

Master/docs under https://github.com/denis-bz/test-gh-pages looks ok, to a git dummy; the same .md renders fine on gist.github .

What didn't work:

git --version
    # git version 2.2.1
echo "# test-gh-pages `isotime`" > README.md
touch .nojekyll docs/.nojekyll

git init
git add README.md .nojekyll docs/.nojekyll docs/Gish.md
git commit -m "docs/Gish.md `isotime`"
    # github.com/new test-gh-pages
git remote add origin https://github.com/denis-bz/test-gh-pages.git
git push -v --set-upstream origin master

Why are you trying to disable Jekyll? What is your end goal? — Kevin Workman
@Kevin Workman, simplicity: Jekyll seems to be unnecessary, see github.com/blog/572-bypassing-jekyll-on-github-pages Also stackoverflow.com/questions/11577147/… with quite a few solutions, some voodoo — denis
What content do you want to have? Is it .md files that you want to process into HTML? Is it just HTML files that you want left alone? Something else? — Kevin Workman
@Kevin Workman, I'd like to see the .md just like on gist.github -- changed the top part to say that. Just this minute a nice Github staff guy emailed "remove the .nojekyll and add an index.md"; trying that. Thanks — denis
Right, if you want to render your .md files as nice formatted HTML pages, then that's exactly what Jekyll does for you. You don't want to get rid of Jekyll in this case. — Kevin Workman

denis denis · Accepted Answer · 2018-01-13T14:08:04

master/docs/index.md alone, with no index.html and no .nojekyll, works:

# github.com/new: make a new repo test-gh-pages
mkdir docs
cp -p .../my.md docs/index.md
echo "# test-gh-pages `isotime`" > README.md

git init
git add README.md docs/index.md
git commit -m "docs/index.md `isotime`"
git remote add origin https://github.com/<user>/test-gh-pages.git
git push -v --set-upstream origin master

# github.com/<user>/test-gh-pages settings: GitHub Pages master branch /docs
# (don't forget save)

Your GitHub Pages site is currently being built from the /docs folder in the master branch

Apparently this calls Jekyll to turn the docs/index.md into .html for browsers to display (in a hidden cache ? on-the-fly ? don't know). After 10 minutes you should see

Your site is published at https://<user>.github.io/test-gh-pages/

See also is-there-a-command-line-utility-for-rendering-github-flavored-markdown : grip .

Thanks, GitHub support.

Can github-pages work with only a .md, no .html no jekyll, like gist.github?

1 Answers