Fully document which HTML tags are allowed in GitHub flavored Markdown

[nvkelso]

In the related issue https://github.com/github/markup/issues/119#issuecomment-25713900 @bkeepers mentioned "unsafe" HTML tags and attributes aren't allowed. Please clearly document which tags and attributes are safe and supported.

[bkeepers]

Here is the exact code we run: https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/sanitization_filter.rb

Feel free to submit pull requests to make changes.

[nvkelso]

Sorry, unless that link is provided in the main Readme file, this doesn't count.

[forivall]

I love how https://help.github.com/articles/github-flavored-markdown/ says to refer to github/markup for the list of tags, but it's not mentioned anywhere. And by love, I mean that it's pretty damn annoying.

[pchaigno]

@forivall You should report it to support@github.com ;)

[bishopb]

Highlighting the relative lines from @bkeepers link:

https://github.com/jch/html-pipeline/blob/master/lib/html/pipeline/sanitization_filter.rb#L44-L106

Code is speech, after all.

[gregglind]

Is there some reason that span isn't allowed?

PROTECT ME FROM THE INTERNETS, PLZ.

[nektro]

h1 h2 h3 h4 h5 h6 h7 h8 br b i strong em a pre code img tt div ins del sup sub p ol ul table thead tbody tfoot blockquote dl dt dd kbd q samp var hr ruby rt rp li tr td th s strike summary details

[nektro]

why isn't <style> allowed?

[kivikakk]

@Nektro it would allow you to change the styling of the entire page, compromising the usability of the website. GitHub isn't a web host.

[nektro]

@kivikakk this is slightly off-topic, but in response, this is why whatwg/html#1226 should not have gone though

[zavr-1]

What's the point of allowing color attribute when it's only allowed in the hr and it's overridden by CSS? And action makes no sense becauseform is not allowed. clear, axis, char (and probably others) are not HTML5 attributes according to MDN.

[aschrijver]

If you want to make proper reference to, say a flickr image, then it is a pity that <script> is not allowed. The flickr embed HTML looks like this:

<a data-flickr-embed="true" data-header="true" data-footer="true"  href="https://www.flickr.com/photos/ritzotencate/albums/72157675979464116" title="Lost in Social Interaction"><img src="https://farm6.staticflickr.com/5453/30754905385_e31f2df5a5_n.jpg" width="320" height="180" alt="Lost in Social Interaction"></a>
<script async src="//embedr.flickr.com/assets/client-code.js" charset="utf-8"></script>

Is there facility for this (i.e. whitelisted domains, besides whitelisted tags)?

[tjanson]

@aschrijver No, there is not. And — no offense — but that’s a terrible idea. Do you propose GitHub audits the whitelisted scripts? Or just trust Flickr not to have any security-related bugs? Besides, what’s the use case for embedding a Flickr album in a GitHub README?

If you want to host a website, try GitHub Pages, maybe that’s a better fit for you.

[aschrijver]

Point taken. I agree it is not a good idea. But in the case of flicker including the script is part of making proper reference, so wanted to bring up the point. In my case this is not for GH Pages. We are having a documentation project where we design tech awareness campaigns and need to have mood boards that honor licensing terms, so need to give proper reference. This occurss in issues, comments and markdown docs in the code. Including embed html unmodified, if it exists, is easiest for many of the (non-technical) contributors in the project.

If you are curious: https://github.com/humanetech-community/humanetech-community-awareness

[devasia2112]

github pages is a very basic thing, markdown is limited. period.

[mnesarco]

Hi Friends, I want to embed Github's STL Viewer in README.md but scripts are not allowed. Is there any workaround?

Thanks.

[eric-wieser]

Note that @bishopb's comment is now incorrect, that gem is no longer used by GitHub.

[tamb]

<small> would be incredibly useful

[coolaj86]

The thing you want to look for in the code (since the line numbers change) is WHITELIST=.

Test and See

Check out https://gist.github.com/coolaj86/89821fe046623d5503ce5c4133e70506

Limited Whitelist (Always Allowed)

<b>
<i>
<strong>
<em>
<a>
<pre>
<code>
<img>
<ins>
<del>
<sup>
<sub>
<mark>
<abbr>
<p>
<ol>
<ul>
<li>

Full Whitelist (Sometimes Allowed)

<h1>
<h2>
<h3>
<h4>
<h5>
<h6>
<h7>
<h8>
<br>
<b>
<i>
<strong>
<em>
<a>
<pre>
<code>
<img>
<tt>
<div>
<ins>
<del>
<sup>
<sub>
<p>
<ol>
<ul>
<table>
<thead>
<tbody>
<tfoot>
<blockquote>
<dl>
<dt>
<dd>
<kbd>
<q>
<samp>
<var>
<hr>
<ruby>
<rt>
<rp>
<li>
<tr>
<td>
<th>
<s>
<strike>
<summary>
<details>
<caption>
<figure>
<figcaption>
<abbr>
<bdo>
<cite>
<dfn>
<mark>
<small>
<span>
<time>
<wbr>

[merlinstardust]

@coolaj86 What determines the "sometimes" in "sometimes allowed"?

[coolaj86]

@merlinpatt Magic. (e.g. I have no idea)

If you right-click inspect element on the list at https://gist.github.com/coolaj86/89821fe046623d5503ce5c4133e70506 (I just fixed the broken link above) you will see that some of the allowed elements have been stripped away.

It may just be that they were not being used correctly (i.e. they must be nested in something specific in order to have meaning)... but the <li> and such seem to work regardless, so I'm not so sure.

Some guesses:

• if not used properly
• comment vs gist vs repo

[StingyJack]

this whitelist is annoying considering it strips out things that are definitely not html tags or even attempts at making an html tag like "UserName: <enter your user name>" and make it into "UserName: " without any warning or notice. It should at least have the decency to inform the user that they cant enter some text combinations, rather than censor them silently.

[aminomancer]

UserName: \<enter your user name>

[aminomancer]

@StingyJack use the backslash \ before the character you're trying to escape. it's a pretty standard convention in web languages. e.g. UserName: \<enter your user name\>

[nillkitty]

Who else is here after spending hours writing docs that show fine in Visual Studio's markdown editor and on the Team Foundation Server/Azure DevOps Wiki but turn into a blob of unformatted text on github?

I agree, Github is not a web host, but you do provide a wiki and restricting