1

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

  1. Create a repository (or navigate to an existing repository)
  2. Commit a Markdown file via the web interface, just like you would any other file
  3. 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
denis
  • 21,378
  • 10
  • 65
  • 88
  • Why are you trying to disable Jekyll? What is your end goal? – Kevin Workman Jan 10 '18 at 21:20
  • @Kevin Workman, simplicity: Jekyll seems to be unnecessary, see https://github.com/blog/572-bypassing-jekyll-on-github-pages Also https://stackoverflow.com/questions/11577147/how-to-fix-page-404-on-github-page with quite a few solutions, some voodoo – denis Jan 11 '18 at 11:49
  • 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 Jan 11 '18 at 17:06
  • @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 Jan 12 '18 at 17:11
  • 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 Jan 12 '18 at 17:44

1 Answers1

0

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.

denis
  • 21,378
  • 10
  • 65
  • 88
  • Do note that this also injects a bunch of SEO code into the HTML header, which you won't be able to turn off without dramatically more configuration. – Mike 'Pomax' Kamermans Dec 24 '20 at 00:29
  • @Mike 'Pomax' Kamermans, is there a simpler way, or an overview of the process ? Also with MathJax in github markdown ? Thanks – denis Dec 24 '20 at 09:41
  • You'd be looking at a slightly more involved process, see https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/about-github-pages-and-jekyll#configuring-jekyll-in-your-github-pages-site – Mike 'Pomax' Kamermans Dec 24 '20 at 18:16