tests/gfm.text

   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 &copy; 2013 GitHub Inc. All rights reserved.
  78 <http://github.github.com/github-flavored-markdown/>