Cannot find detailed, specific documentation for using markdown on github projects and user pages

Question

I am going to add github pages to some of my repositories and to my user page. For many web pages, I want to use Markdown formatting.

However, since I can find vague, raw information on how to do this, I make a test error and figure out how it works.

Where is the real documentation? Details gory?

---

Here is the best information I have found so far, which says:

• use the special name of the gh-pages branch to create a site for a repo project

• a three-line spell is required at the top of the file:

   --- title: something --- 

• suffix changes to .html

But I still have a lot of questions about the details, for example:

• Can i import css files?
• what does this “title” actually do?
• What suffix should the file have?

etc .. Therefore, I would really like to receive detailed documentation on all functions.

---

Please note that this question is not about how to use Markdown syntax, but how to use github magic to automatically create html from Markdown within user and project pages.

Answer 1

how to use github magic to automatically create html from Markdown within user and project pages

Sounds like you're talking to Jekyll .

---

What does this “title” actually do?

title is part of the YAML Front Matter . This is basically a variable that you can access through page.title

---

What suffix should the file have?

Provided that the file has a YAML Front Matter section, it will be converted by Jekyll. The same will happen for any .html , .markdown , .md or .textile in the root directory of your directory or directories not listed above.

github.com/mojombo/jekyll/wiki/usage

Answer 2

Only files with the extensions .md or .markdown will be converted to HTML on the GitHub user page.

Files with the extensions .html and .textile not translated, according to my attempts.

Please note that UTF8 encoding should be avoided.