Fully document which HTML tags are allowed in GitHub flavored Markdown

[nvkelso]

In the related issue #119 (comment) @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 [email protected] ;)

[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 <style> inside a wiki page because you're worried about a project owner accidentally making their project page ugly or unusable, then I don't see what anyone would do that. I need to use this to ensure that people reading the MD files in a plain text editor don't have to see tons of excess HTML that needs to be there to keep the densely populated tables in line and from being an eyechart.

At the very least as the project owner I should be able to turn on "Allow <style> in documentation" if I want to run the risk of one of my contributors accidentally screwing up the UI in my repo. Aside from styling inadvertently ruining my project (and nothing else), you have really no concern there. Don't be a Facebook and limit valuable markdown tools because you think teenagers will use it to make animated snow in their README.md.

Making it so someone has to use an external markdown viewer just to view documentation properly is stupid. If that's the road you're going down then add a PDF preview so that you can display exactly what I need to show them without any chance of it bleeding into your UI elements. My only recourse at this time is to make every table or anything needing CSS adjustments an image.

[StingyJack]

make animated snow in their README.md

I did not know I needed this until you said it.

[andyruwruw]

I agree, Github is not a web host, but you do provide a wiki and restricting <style> inside a wiki page because you're worried about a project owner accidentally making their project page ugly or unusable, then I don't see what anyone would do that.

Style tags would style Github's UI as well...they don't care if you make your wiki ugly. They care that we can't change things outside of the markdown. Go make your own wiki, or find a service meant for making custom wikis. You're choosing the wrong tool for the job, and it's not the tool's fault.

[aminomancer]

I agree, Github is not a web host, but you do provide a wiki and restricting <style> inside a wiki page because you're worried about a project owner accidentally making their project page ugly or unusable, then I don't see what anyone would do that.

Style tags would style Github's UI as well...they don't care if you make your wiki ugly. They care that we can't change things outside of the markdown. Go make your own wiki, or find a service meant for making custom wikis. You're choosing the wrong tool for the job, and it's not the tool's fault.

I don't really have a dog in this race or feel too strongly, but the more I think about it, why not make the tool more robust? I don't see what the risk is, though feel free to inform me if there is one. It's not like anyone's asking for script tags. If we're really paranoid, markdown file previews could always be embedded in iframes or shadow dom. I suppose it doesn't even need to be full css. Github's markdown could be expanded to parse custom html attributes from some predefined list of safe CSS properties and render accordingly. Like user could type <div css-display="flex"> and get a div with inline style display: flex. Or <table css-border-spacing="2px" css-border-collapse="collapse">

I get the attitude "if it ain't broke, don't fix it," but github is an enterprise service, trying to expand its "prosumer" market cap by targeting small teams and FOSS developers with cheap but better-than-free collaboration and automation features. Stylable readmes with real functional tables, flexboxes, etc. would be a valuable documentation tool for those customers, among many other things. Expanded markdown could even be a paid feature. It makes a lot of sense to implement the necessary tools to make a better repo landing page since that's probably a dimension of competition, however minor. I think gitlab's markdown preview supports style and I doubt it costs them a fortune to maintain.

And of course github pages already exists, but 1) that's not what people see when they're trying to look at the source code, or when a "support page" link directs them to the github issues tab, and 2) the fact that an option is already available somewhere else isn't a good reason for not having it available everywhere. That's like saying because dairy queen has chocolate ice cream at their los angeles store, they shouldn't bother selling it at their san diego location. The only thing I can think of is that there might be a security risk in older browsers. But if that's the case, you could just program the filter to reject custom attributes under whatever conditions are deemed dangerous.

[nasserHm]

في جمعة، ١٦ أبريل، ٢٠٢١ في ١١:٥٩ م، كتب Andrew Young < ***@***.***>:

…

I agree, Github is *not* a web host, but you do provide a wiki and restricting <style> inside a wiki page because you're worried about a project owner accidentally making their project page ugly or unusable, then I don't see what anyone would do that. Style tags would style Github's UI as well...they don't care if you make your wiki ugly. They care that we can't change things outside of the markdown. Go make your own wiki, or find a service meant for making custom wikis. You're choosing the wrong tool for the job, and it's not the tool's fault. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#245 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ATORMDY27VO65YP24EY4SQTTJCQKZANCNFSM4ALUUKVQ> .