Louis93 Louis93 - 3 months ago 15
Markdown Question

GitHub Pages: How do I edit this page in markdown format, just as I created it?

I'm not too comfortable with touching the generated HTML that the site gives, I was wondering whether there is any way to change the contents of my page in markdown formatting, the same way that I did upon creating the page?

Any input as to go about doing this would be awesome.

Answer

By default, GitHub Pages helps you generate html pages only.

But if you setup your site to use jekyll, then you can store files in markdown. For example, in the _posts section of this repo 'cboettig/labnotebook' which is generated to carlboettiger.info.

See Help page "Using Jekyll with Pages"


As mentioned in the Help page, after generating those page, you can get a local copy of the generated pages:

If you generated a project page, fetch and check out the new branch:

$ cd repo
$ git fetch origin
# remote: Counting objects: 92, done.
# remote: Compressing objects: 100% (63/63), done.
# remote: Total 68 (delta 41), reused 0 (delta 0)
# Unpacking objects: 100% (68/68), done.
# From https://github.com/user/repo.git
#  * [new branch]      gh-pages     -> origin/gh-pages

$ git checkout gh-pages
# Branch gh-pages set up to track remote branch gh-pages from origin.
# Switched to a new branch 'gh-pages'

If you generated a user page, the page code lives on the master branch instead of the gh-pages branch, so just check out master and then pull!

$ cd repo
$ git checkout master
# Switched to branch 'master'
$ git pull origin master

From there, you can modify any page:

  • in html if generated by default,
  • or respecting the GitHub Flavored Markdown for pages processed by jekyll (in the _posts directory of your repo).

However, if you don't use Jekyll, what you get back is the generated html, so no markdown files there.


Update August 2016: Simpler GitHub Pages publishing now allows to keep your page files in a subfolder of the same branch (no more gh-pages needed):

Now you can select a source in your repository settings and GitHub Pages will look for your content there.

So you don't need multiple branch anymore.