HTML in Markdown files

Markdown is a writing format; HTML is a publishing format. Thus, Markdown syntax is not meant to offer the full versatility of HTML, just the most common elements for written text. When you need to do something more complicated, you can use any inline HTML tag and block-level tags that are supported by DevSite in a Markdown file. There's no need to indicate that you're switching from Markdown to HTML, just use the HTML tag as in the example below.

This sentence is in Markdown with a <b>bold inline HTML tag</b>.

Inline HTML

Inline HTML tags can be used within a Markdown paragraph, list item, or header, and they can also contain Markdown syntax (e.g., **strong**, *emphasis*, etc.) This is helpful when you want to draw attention to a bit of code, as in the example below.

This is a Markdown paragraph about Java:
<code>System.out.format("The square of *%d* is *%f*.*%n*", i, r);</code>

Block-level HTML

Block-level HTML tags that are supported by DevSite must be separated from surrounding content with a blank line. And unlike inline HTML tags, Markdown syntax (e.g., **strong**, *emphasis*, etc.) in block-level HTML tags are not rendered as in the example below.

This is a Markdown paragraph that explains Java format strings:
                                  // required blank line
<pre>
  System.out.format("The square of *%d* is *%f*.*%n*", i, r);
</pre>
                                  // required blank line
This is another Markdown paragraph.

Best practices

We recommend formatting HTML in Markdown files in the following ways to prevent rendering errors on DevSite.

Don't use unsupported block-level HTML tags DevSite supports many block-level HTML tags; but including an unsupported one will either render your HTML as text or break the code.

Don't add extra tabs or spaces when indenting Block-level start and end tags should not be indented with tabs or spaces. Some editors automatically add extra tabs or spaces — watch out!

This is a regular paragraph in Markdown.

<p>
    This is an HTML paragraph with proper indentation!
</p>

This is a regular paragraph in Markdown.

Don't forget that unindented code is relative

For example, you don't need to indent block-level start and end tags when creating lists in Markdown.

* This is a list item in Markdown

<p>This is an HTML paragraph with proper indentation!</p>

* This is a list item in Markdown

Don't add a blank line between a start and end tag

This is easy to do when you're switching between Markdown and HTML, but a simple blank line can easily render a page incorrectly.

This is a regular paragraph in Markdown.

<section>
  <p>
    hello
   </p>
  <p>
    hello
  </p>
</section>

This is a regular paragraph in Markdown.