• Github Markdown Guide
• Markdown List Syntax

This tutorial covers Markdown lists - Ordered, unordered, syntax with examples. To see a complete list of formatting options, click the Markdown link to open the syntax list, then click the help icon.

The userguide uses Markdown and Markdown Extra for the userguide pages, and the in-code comments used to generate the API browser. This is a brief summary of most of Markdown and Markdown extra features. It does not cover everything, and it does not cover all the caveats.

Be sure to check out the Userguide Specific Syntax for things that Userguide adds to markdown.

Headers

Paragraphs

Regular text will be transformed into paragraphs.Single returns will not make a new paragraph, thisallows for wrapping (especially for in-codecomments).

A new paragraph will start if there is a blank line betweenblocks of text. Chars like > and & are escaped for you.

To make a line break,
put two spaces at the
end of a line.

Links

This is a normal link: Kohana

This link has a title: Kohana

Code blocks

For inline code simply surround some text with tick marks.

You can also do a 'fenced' code block:

Unordered Lists

• To make a unordered list, put an asterisk, minus, or + at the beginning
• of each line, surrounded by spaces. You can mix * - and +, but it
• makes no difference.

Ordered Lists

1. For ordered lists, put a number and a period
2. On each line that you want numbered.
3. It doesn't actually have to be the correct number order
4. Just as long as each line has a number

Nested Lists

• To nest lists you just add four spaces before the * or number
  1. Like this
     • It's pretty basic, this line has eight spaces, so its nested twice
  2. And this line is back to the second level
     • Out to third level again
• And back to the first level

Italics and Bold

Surround text you want italics with asterisks or underscores.

Double asterisks or double underscores makes text bold.

Triple will do both at the same time.

Horizontal Rules

Horizontal rules are made by placing 3 or more hyphens, asterisks, or underscores on a line by themselves.

Images

Image syntax looks like this:

Note that the images in userguide are namespaced.

Tables

Note that the pipes on the very left and very right side are optional, and you can change the text-alignment by adding a colon on the right, or on both sides for center.

In addition to the features and syntax of Markdown and Markdown Extra the following apply to userguide pages and api documentation:

Namespacing

The first thing to note is that all links are 'namespaced' to the current module. For example, from anywhere within the Kohana core docs you do not need to include kohana at the beginning of a link url. For example: [Hello World Tutorial](tutorials/hello-world) rather than (kohana/tutorials/hello-world).

To link to a modules index page, have an empty url like: [Kohana]().

To link to page in a different module, prefix your url with ../ and the module name. For example: [Kohana Routes](../kohana/routing)

Images are also namespaced, using ![Alt Text](imagename.jpg) would look for media/guide/<modulename>/imagename.jpg.

If you want your userguide pages to be browsable on github or similar sites outside Kohana's own userguide module, specify the optional .md file extension in your links

API Links

You can make links to the api browser by wrapping any class name in brackets. You may also include a function name, or propery name to link to that specifically. All of the following will link to the API browser:

Request
Request::execute
Request::execute()
Request::$status

If you want to have parameters and have the function be clickable, only put the brackets around the class and function (not the params), and put a backslash in front of the opening parenthesis.

Kohana::$config('foobar','baz')

Notes

If you put [!!] in front of a line it will be a 'note' and be placed in a box with a lightbulb.

will display as:

This is a note

Headers automatically get IDs

Headers are automatically assigned an id, based on the content of the header, so each header can be linked to. You can manually assign a different id using the syntax as defined in Markdown Extra. If multiple headers have the same content (e.g. more than one 'Examples' header), only the first will get be automatically assigned an id, so you should manually assign more descriptive ids. For example:

Including Views

If you need you may include a regular Kohana View file by placing the name of the view in double curly brackets. If the view is not found, no error or exception will be shown, the curly brackets and view name will simply remain there!

Markdown is a lightweight and easy-to-use syntax for styling all forms of writing on the GitHub platform.

What you will learn:

• How the Markdown format makes styled collaborative editing easy
• How Markdown differs from traditional formatting approaches
• How to use Markdown to format text
• How to leverage GitHub’s automatic Markdown rendering
• How to apply GitHub’s unique Markdown extensions

What is Markdown?

Markdown is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like # or *.

You can use Markdown most places around GitHub:

• Comments in Issues and Pull Requests
• Files with the .md or .markdown extension

For more information, see “Writing on GitHub” in the GitHub Help.

Examples

Syntax guide

Here’s an overview of Markdown syntax that you can use anywhere on GitHub.com or in your own text files.

Headers

Emphasis

Lists

Unordered

Ordered

Images

Links

Blockquotes

Inline code

GitHub Flavored Markdown

GitHub.com uses its own version of the Markdown syntax that provides an additional set of useful features, many of which make it easier to work with content on GitHub.com.

Note that some features of GitHub Flavored Markdown are only available in the descriptions and comments of Issues and Pull Requests. These include @mentions as well as references to SHA-1 hashes, Issues, and Pull Requests. Task Lists are also available in Gist comments and in Gist Markdown files.

Syntax highlighting

Here’s an example of how you can use syntax highlighting with GitHub Flavored Markdown:

You can also simply indent your code by four spaces:

Here’s an example of Python code without syntax highlighting:

Task Lists

If you include a task list in the first comment of an Issue, you will get a handy progress indicator in your issue list. It also works in Pull Requests!

Tables

You can create tables by assembling a list of words and dividing them with hyphens - (for the first row), and then separating each column with a pipe |:

Github Markdown Guide

Would become:

SHA references

Any reference to a commit’s SHA-1 hash will be automatically converted into a link to that commit on GitHub.

Issue references within a repository

Any number that refers to an Issue or Pull Request will be automatically converted into a link.

Username @mentions

Typing an @ symbol, followed by a username, will notify that person to come and view the comment. This is called an “@mention”, because you’re mentioning the individual. You can also @mention teams within an organization.

Automatic linking for URLs

Any URL (like http://www.github.com/) will be automatically converted into a clickable link.

Strikethrough

Any word wrapped with two tildes (like ~~this~~) will appear crossed out.

Emoji

GitHub supports emoji!

To see a list of every image we support, check out the Emoji Cheat Sheet.

Markdown List Syntax

Last updated Jan 15, 2014