From f062f519a20cbba382f6ff66a6d5fd5ee88f528a Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Mon, 22 Dec 2014 12:37:50 -0500 Subject: [PATCH 1/6] Remove rarely used docs for adding new markup langauges --- CONTRIBUTING.md | 45 --------------------------------------------- 1 file changed, 45 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 57ba6e97..935fa2e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,57 +9,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 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 From a548494d5f8d5d56d3d19b07db231ca4c2451240 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Mon, 22 Dec 2014 14:05:55 -0500 Subject: [PATCH 2/6] Explain how markup is rendered to HTML on GitHub --- README.md | 38 +++++++------------------------------- 1 file changed, 7 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index d6d0c8b1..9bb01367 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,13 @@ 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. Markups ------- @@ -41,32 +46,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. From 8f46ed3ab16af411c763f96829c3b63a55f69ea5 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Fri, 16 Jan 2015 10:34:51 -0500 Subject: [PATCH 3/6] point to other places before creating issues --- CONTRIBUTING.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 935fa2e2..fec6b48a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,15 @@ # 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#syntax-highlighting) for more information about syntax highlighting. +* **Markdown on GitHub** - contact support@github.com to report issues with markdown processing. + +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,7 +18,7 @@ Want to contribute? Great! 5. Open a [Pull Request][1] 6. Enjoy a refreshing Diet Coke and wait -### Testing +## Testing To run the tests: From 78aa3779447cb66c1ea93ab32db5cad412e7fb09 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Tue, 3 Mar 2015 20:46:14 -0800 Subject: [PATCH 4/6] Fix link to linguist --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fec6b48a..42d0d818 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ This library's only job is to decide which markup format to use and call out to If you are having an issue with: -* **Syntax highlighting** - see [github/linguist](https://github.com/github/linguist#syntax-highlighting) for more information about syntax highlighting. +* **Syntax highlighting** - see [github/linguist](https://github.com/github/linguist/blob/master/CONTRIBUTING.md#fixing-syntax-highlighting) for more information about syntax highlighting. * **Markdown on GitHub** - contact support@github.com to report issues with markdown processing. 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. From 2ab36061ef48e4e657f747ec0f3a9f6c09e48fa8 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Tue, 3 Mar 2015 20:48:46 -0800 Subject: [PATCH 5/6] Call out CSS issues --- CONTRIBUTING.md | 3 ++- README.md | 2 ++ 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 42d0d818..14a6cfbd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,7 +5,8 @@ This library's only job is to decide which markup format to use and call out to If you are having an issue with: * **Syntax highlighting** - see [github/linguist](https://github.com/github/linguist/blob/master/CONTRIBUTING.md#fixing-syntax-highlighting) for more information about syntax highlighting. -* **Markdown on GitHub** - contact support@github.com to report issues with markdown processing. +* **Markdown on GitHub** - contact support@github.com +* **Styling issues on GitHub** - contact support@github.com 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. diff --git a/README.md b/README.md index 3869633c..63b34ef0 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ This library is the first step of a journey that every markup file in a reposito 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 ------- From 6404e98837e5dbbee53db4ca6964db5c46b5cdb9 Mon Sep 17 00:00:00 2001 From: Brandon Keepers Date: Tue, 3 Mar 2015 20:50:28 -0800 Subject: [PATCH 6/6] tweaks --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 14a6cfbd..658ac0f0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ This library's only job is to decide which markup format to use and call out to If you are having an issue with: -* **Syntax highlighting** - see [github/linguist](https://github.com/github/linguist/blob/master/CONTRIBUTING.md#fixing-syntax-highlighting) for more information about syntax highlighting. +* **Syntax highlighting** - see [github/linguist](https://github.com/github/linguist/blob/master/CONTRIBUTING.md#fixing-syntax-highlighting) * **Markdown on GitHub** - contact support@github.com * **Styling issues on GitHub** - contact support@github.com