Document the Markdown API

Vicent Marti · Vicent Marti · commit 40c3af3b4f62 · 2012-06-25T21:18:58.000+02:00
diff --git a/content/v3/markdown.md b/content/v3/markdown.md
@@ -0,0 +1,49 @@
+---
+title: Markdown Rendering | GitHub API
+---
+
+# Markdown Rendering API
+
+## Render an arbritrary Markdown document
+
+	POST /markdown
+
+### Input
+
+text
+: _Required_ **string** - The Markdown text to render
+
+mode
+: _Optional_ **string** - The rendering mode
+
+	- `markdown` to render a document as plain Markdown, just like README files are rendered.
+	- `gfm` to render a document as user-content, e.g. like user comments or issues are rendered. In GFM mode, hard line breaks are always taken into account, and issue and user mentions are linked accordingly.
+
+context
+: _Optional_ **string** - The repository context, only taken into account when rendering as `gfm`
+
+<%= json \
+  :text => "Hello world github/linguist#1 **cool**, and #1!",
+  :mode => "gfm",
+  :context => "github/gollum"
+%>
+
+### Response
+
+<%= text_html \
+	%(<p>Hello world <a href="http://github.com/github/linguist/issues/1" class="issue-link" title="This is a simple issue">github/linguist#1</a> <strong>cool</strong>, and <a href="http://github.com/github/gollum/issues/1" class="issue-link" title="This is another issue">#1</a>!</p>), 200
+%>
+
+# Render a Markdown document in raw mode
+
+	POST /markdown/raw
+
+### Input
+
+The raw API it not JSON-based. It takes a Markdown document as plaintext (`text/plain` or `text/x-markdown`) and renders it as plain Markdown without a repository context (just like a README.md file is rendered -- this is the simplest way to preview a readme online).
+
+### Response
+
+<%= text_html \
+	%(<p>Hello world github/linguist#1 <strong>cool</strong>, and #1!</p>), 200
+%>
diff --git a/layouts/default.html b/layouts/default.html
@@ -120,6 +120,7 @@ <h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v3/search/">
               <li><a href="/v3/search/#email-search">Email</a></li>
             </ul>
           </li>
+          <li class="js-guides"><h3><a href="/v3/markdown/">Markdown</a></h3></li>
         </ul>
       </div> <!-- /sidebar-module -->
       <div class="sidebar-module">
diff --git a/lib/resources.rb b/lib/resources.rb
@@ -1,6 +1,7 @@
 require 'pp'
 require 'yajl/json_gem'
 require 'stringio'
+require 'cgi'
 
 module GitHub
   module Resources
@@ -54,6 +55,12 @@ def json(key)
         %(<pre class="highlight"><code class="language-javascript">) +
           JSON.pretty_generate(hash) + "</code></pre>"
       end
+
+      def text_html(response, status, head = {})
+        hs = headers(status, head.merge('Content-Type' => 'text/html'))
+        res = CGI.escapeHTML(response)
+        hs + %(<pre class="highlight"><code>) + res + "</code></pre>"
+      end
     end
 
     USER = {
