Since this is from plain markdown, I'd recommend not including it here. For one, many users of Pagure probably do know markdown and will really just want to know the special Pagure-only extensions to it. Secondly, the link you gave above probably does a good job of documenting markdown (if it doesn't, you could easily inlcude a link to good Markdown docs).

It will make this document shorter and easier to get to the info that users need.

Basically, I recommend dropping all the lines above this point, because it seems that this is where Pagure-specific docs begin, and this is probably the info that users really need to get to.

This all looks fine, and my comments are just suggestions, so feel free to merge as-is, or feel free to make the recommended modifications and merge that too.

Haha, it's also a little humorous to document markdown in restructured text ☺

agreed and was quite fun ^^

strikethrough it not built-in, so we would need to keep it

I have been pondering about your remark, they make a lot of sense, but on the other hand it would mean people would have to go through two pages to get the basic syntax (since my idea is to change the Markdown Syntax links near the comment fields to point to that page). So I think I will keep it as it is now, I may actually need to expand it a little to document the extensions we are using as well (at least the basic) and indeed refer the users to the upstream doc for more advanced usage.

I drop the headers section which was and messing up a little sphinx and I think less relevant.

I added a blob about the different markdown extensions enabled.

Let me know what you think :)

LGTM!

Thanks for the review :)