Merge pull request #431 from github/trim-contributing

Make docs more helpful for end-users

CONTRIBUTING.md

@@ -1,6 +1,16 @@
 # Contributing
 
-Want to contribute? Great!
+This library's only job is to decide which markup format to use and call out to an external library to convert the markup to HTML (see the [README](README.md) for more information on how markup is rendered on GitHub.com).
+
+If you are having an issue with:
+
+* **Syntax highlighting** - see [github/linguist](https://github.com/github/linguist/blob/master/CONTRIBUTING.md#fixing-syntax-highlighting)
+* **Markdown on GitHub** - contact [email protected]
+* **Styling issues on GitHub** - contact [email protected]
+
+Anything else - [search open issues](https://github.com/github/markup/issues) or create an issue and and we'll help point you in the right direction.
+
+## Submitting a Pull Request
 
 1. Fork it.
 2. Create a branch (`git checkout -b my_markup`)
@@ -9,57 +19,12 @@ Want to contribute? Great!
 5. Open a [Pull Request][1]
 6. Enjoy a refreshing Diet Coke and wait
 
-
-There are two ways to add markups.
-
-### Commands
-
-If your markup is in a language other than Ruby, drop a translator
-script in `lib/github/commands` which accepts input on STDIN and
-returns HTML on STDOUT. See [rest2html][r2h] for an example.
-
-Once your script is in place, edit `lib/github/markups.rb` and tell
-GitHub Markup about it. Again we look to [rest2html][r2hc] for
-guidance:
-
-    command(:rest2html, /re?st(.txt)?/)
-
-Here we're telling GitHub Markup of the existence of a `rest2html`
-command which should be used for any file ending in `rest`,
-`rst`, `rest.txt` or `rst.txt`. Any regular expression will do.
-
-Finally add your [tests](#testing).
-
-### Classes
-
-If your markup can be translated using a Ruby library, that's
-great. Check out `lib/github/markups.rb` for some
-examples. Let's look at Markdown:
-
-    markup(:markdown, /md|mkdn?|markdown/) do |content|
-      Markdown.new(content).to_html
-    end
-
-We give the `markup` method three bits of information: the name of the
-file to `require`, a regular expression for extensions to match, and a
-block to run with unformatted markup which should return HTML.
-
-If you need to monkeypatch a RubyGem or something, check out the
-included RDoc example.
-
-Finally add your [tests](#testing).
-
-### Testing
+## Testing
 
 To run the tests:
 
     $ rake
 
-When adding support for a new markup library, create a `README.extension` in `test/markups` along with a `README.extension.html`. As you may imagine, the `README.extension` should be your known input and the
-`README.extension.html` should be the desired output.
-
-Now run the tests: `rake`
-
 If nothing complains, congratulations!
 
 ## Releasing a new version

README.md

@@ -1,8 +1,15 @@
 GitHub Markup
 =============
 
-We use this library on GitHub when rendering your README or any other
-rich text file. The generated HTML is then run through filters in the [html-pipeline](https://github.com/jch/html-pipeline) to perform things like [sanitization](#html-sanitization) and [syntax highlighting](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/syntax_highlight_filter.rb).
+This library is the first step of a journey that every markup file in a repository goes on before it is rendered on GitHub.com:
+
+0. This library converts the raw markup to HTML. See the list of [supported markup formats](#markups) below.
+0. The HTML is sanitized, aggressively removing things that could harm you and your kin—such as `script` tags, inline-styles, and `class` or `id` attributes. See the [sanitization filter](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/sanitization_filter.rb) for the full whitelist.
+0. Syntax highlighting is performed on code blocks. See [github/linguist](https://github.com/github/linguist#syntax-highlighting) for more information about syntax highlighting.
+0. The HTML is passed through other filters in the [html-pipeline](https://github.com/jch/html-pipeline) that add special sauce, such as [emoji](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/emoji_filter.rb), [task lists](https://github.com/github/task_list/blob/master/lib/task_list/filter.rb), [named anchors](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/toc_filter.rb), [CDN caching for images](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/camo_filter.rb), and  [autolinking](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/autolink_filter.rb).
+0. The resulting HTML is rendered on GitHub.com.
+
+Please see our [contributing guidelines](CONTRIBUTING.md) before reporting an issue.
 
 Markups
 -------
@@ -41,32 +48,3 @@ Contributing
 ------------
 
 See [Contributing](CONTRIBUTING.md)
-
-HTML sanitization
------------------
-
-HTML rendered by the various markup language processors gets passed through an [HTML sanitization filter](https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/sanitization_filter.rb) for security reasons. HTML elements not in the whitelist are removed. HTML attributes not in the whitelist are removed from the preserved elements.
-
-The following HTML elements, organized by category, are whitelisted:
-
-|Type | Elements
-|------|----------
-|Headings | `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `h7`, `h8`
-|Prose |  `p`, `div`, `blockquote`
-|Formatted | `pre`
-| Inline | `b`, `i`, `strong`, `em`, `tt`, `code`, `ins`, `del`, `sup`, `sub`, `kbd`, `samp`, `q`, `var`
-| Lists | `ol`, `ul`, `li`, `dl`, `dt`, `dd`
-| Tables | `table`, `thead`, `tbody`, `tfoot`, `tr`, `td`, `th`
-| Breaks | `br`, `hr`
-| Ruby (East Asian) | `ruby`, `rt`, `rp`
-
-The following attributes, organized by element, are whitelisted:
-
-|Element | Attributes
-|------|----------
-| `a` | `href` (`http://`, `https://`, `mailto://`, `github-windows://`, and `github-mac://` URI schemes and relative paths only)
-| `img` | `src` (`http://` and `https://` URI schemes and relative paths only)
-| `div` | `itemscope`, `itemtype`
-| All | `abbr`, `accept`, `accept-charset`, `accesskey`, `action`, `align`, `alt`, `axis`, `border`, `cellpadding`, `cellspacing`, `char`, `charoff`, `charset`, `checked`, `cite`, `clear`, `cols`, `colspan`, `color`, `compact`, `coords`, `datetime`, `dir`, `disabled`, `enctype`, `for`, `frame`, `headers`, `height`, `hreflang`, `hspace`, `ismap`, `label`, `lang`, `longdesc`, `maxlength`, `media`, `method`, `multiple`, `name`, `nohref`, `noshade`, `nowrap`, `prompt`, `readonly`, `rel`, `rev`, `rows`, `rowspan`, `rules`, `scope`, `selected`, `shape`, `size`, `span`, `start`, `summary`, `tabindex`, `target`, `title`, `type`, `usemap`, `valign`, `value`, `vspace`, `width`, `itemprop`
-
-Note that the `id` attribute is *not* whitelisted.