gfm.text (3250B)
1 # Introduction to GFM 2 3 GitHub uses what we're calling "GitHub Flavored Markdown" (GFM) for messages, issues, and comments. It differs from standard Markdown (SM) in a few significant ways and adds some additional functionality. 4 5 If you're not already familiar with Markdown, you should spend 15 minutes and go over the excellent [Markdown Syntax Guide](http://daringfireball.net/projects/markdown/syntax) at Daring Fireball. 6 7 If you prefer to learn by example, see the following source and result: 8 9 * [Source](sample_content.html) 10 * [Result](http://github.com/mojombo/github-flavored-markdown/issues/#issue/1) 11 12 If you're interested in how we render Markdown files, you might want to check out [Redcarpet](https://github.com/vmg/redcarpet), our Ruby interface to the [Sundown](https://www.github.com/vmg/sundown) library. 13 14 ## Differences from traditional Markdown 15 16 ### Newlines 17 18 The biggest difference that GFM introduces is in the handling of linebreaks. With SM you can hard wrap paragraphs of text and they will be combined into a single paragraph. We find this to be the cause of a huge number of unintentional formatting errors. GFM treats newlines in paragraph-like content as real line breaks, which is probably what you intended. 19 20 The next paragraph contains two phrases separated by a single newline character: 21 22 Roses are red 23 Violets are blue 24 25 becomes 26 27 Roses are red 28 Violets are blue 29 30 ### Multiple underscores in words 31 32 It is not reasonable to italicize just _part_ of a word, especially when you're dealing with code and names often appear with multiple underscores. Therefore, GFM ignores multiple underscores in words. 33 34 perform_complicated_task 35 do_this_and_do_that_and_another_thing 36 37 becomes 38 39 perform_complicated_task do_this_and_do_that_and_another_thing 40 41 ### URL autolinking 42 43 GFM will autolink standard URLs, so if you want to link to a URL (instead of setting link text), you can simply enter the URL and it will be turned into a link to that URL. 44 45 ### Fenced code blocks 46 47 Markdown converts text with four spaces at the front of each line to code blocks. GFM supports that, but we also support fenced blocks. Just wrap your code blocks in `` ``` `` and you won't need to indent manually to trigger a code block. 48 49 ### Syntax highlighting 50 51 We take code blocks a step further and add syntax highlighting if you request 52 it. In your fenced block, add an optional language identifier and we'll run it 53 through syntax highlighting. For example, to syntax highlight Ruby code: 54 55 ```ruby 56 require 'redcarpet' 57 markdown = Redcarpet.new("Hello World!") 58 puts markdown.to_html 59 ``` 60 61 This yields 62 63 ```ruby 64 require 'redcarpet' 65 markdown = Redcarpet.new("Hello World!") 66 puts markdown.to_html 67 ``` 68 69 ## Code 70 71 The newline and underscore modification code can be seen below. If you find a bug in the rendering, we'd love to hear about it. Browse through open Issues and report new Issues on the [GitHub-flavored Markdown Issues page](https://github.com/github/github-flavored-markdown/issues). 72 73 ## Markdown Cheat Sheet 74 75 On Markdown-enabled portions of the site, press **M** on your keyboard to display a cheat sheet. 76 77 © 2013 GitHub Inc. All rights reserved. 78 <http://github.github.com/github-flavored-markdown/>