What is the equivalent of `.. raw: html` of Sphinx in Markdown?

Question

Question title should be self explanatory. I couldn't find anything in Markdown of Sphinx raw.

I know I can type directly html within the md file, but I have a very long html code snippet that I'd like to keep separated from the markdown.

Answer 1

As the rules plainly state (emphasis added):

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

The only restrictions are that block-level HTML elements — e.g. <div>, <table>, <pre>, <p>, etc. — must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <p> tags around HTML block-level tags.

If you are concerned that Markdown might munge up the content of your raw HTML, the rules also state:

Note that Markdown formatting syntax is not processed within block-level HTML tags. E.g., you can’t use Markdown-style *emphasis* inside an HTML block.

So, as long as your HTML blocks are properly wrapped in block level HTML tags, Markdown will leave them alone. Of course, that does not aply to inline HTML elements, included within Markdown text:

Span-level HTML tags — e.g. <span>, <cite>, or <del> — can be used anywhere in a Markdown paragraph, list item, or header. If you want, you can even use HTML tags instead of Markdown formatting; e.g. if you’d prefer to use HTML <a> or <img> tags instead of Markdown’s link or image syntax, go right ahead.

Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.

It is also important to note that some Markdown implementations do not follow the rules as stated above. So you might want to check the documentation for the implementation you are using to ensure it either follows the rules, or has a configuration switch which forces it to follow the rules.

And then there is Commonmark, which does not follow the original Markdown rules, but uses a different set of rules. Specifically, Commonmark requires no blank lines within the raw HTML block to avoid Markdown parsing. CommonMark will treat everything as Markdown after the first blank line within a raw HTML block. However, if you are using an old-school Markdown parser rather than a Commonmark parser, this should be a non-issue.

As a final word of caution, Markdown (not Commonmark) is much older than HTML 5. Therefore the newer block-level elements added to HTML 5 (<section>, <article>, etc.) are not recognized by most Markdown implementations as being block level elements. Some implementations have been updated to add support, but even then there is no consistency between implementations regarding which new elements should be treated as block-level as the reference implementation has not been updated to set a president. Therefore, it is best to stick with elements defined as block-level in the old HTML 4 and/or XHTML 1 specs.