{
  "schemaVersion": "1.0",
  "entity": "BlogPosting",
  "title": "Using Raw HTML Inside Markdown",
  "description": "Learn when and how raw HTML tags work inside Markdown documents, including block vs. inline HTML rules, common use cases, and MDX-specific behavior.",
  "author": "hinal-acharya",
  "datePublished": "2026-07-15T00:00:00.000Z",
  "dateModified": "2026-07-15T00:00:00.000Z",
  "tags": [
    "Markdown",
    "Tutorial"
  ],
  "aeoDirectAnswers": [
    {
      "question": "How Does Markdown Recognize Raw HTML?",
      "answer": "CommonMark defines a fixed set of recognized HTML tags and patterns. When the parser encounters one, it copies it into the output as-is instead of escaping it as plain text. This renders as: This sentence has inline HTML mixed into it."
    },
    {
      "question": "What Is the Difference Between Inline and Block HTML?",
      "answer": "**Inline HTML** sits inside a line of regular Markdown text, like the ` example above. **Block HTML** is a standalone HTML element that takes up its own section, such as a ` wrapping several lines of content. This renders as a centered block: A block-level HTML tag must be separated from the surrounding Markdown by a blank line both before and after it. Skip the blank line and some parsers will merge the tag into the adjacent paragraph instead of treating it as its own block."
    },
    {
      "question": "Does Markdown Syntax Work Inside an HTML Block?",
      "answer": "By default, no. Once the parser enters an HTML block, it stops processing Markdown syntax until the block ends. Text inside renders exactly as written, asterisks and all. There's one common exception worth knowing: leaving a blank line directly after the opening tag (like the centered image example above) causes some parsers, including the remark/rehype pipeline Astro's MDX uses, to treat the inner content as regular Markdown again. Behavior here varies by tooling, so test it in your own setup rather than assuming. ---"
    },
    {
      "question": "How Do I Hide Content With an HTML Comment?",
      "answer": "An HTML comment (``) is valid HTML passthrough, and most Markdown renderers strip it from the output entirely rather than displaying it. This renders as: This paragraph is visible, but the comment above it is not."
    },
    {
      "question": "When Should I Reach for Raw HTML Instead of Markdown?",
      "answer": "Reach for HTML only when Markdown genuinely has no equivalent: image resizing, centering content, opening links in a new tab, or adding attributes like class or id. For everything else (emphasis, links, lists, tables) stick to plain Markdown. Mixing HTML in where Markdown syntax already works makes source files harder to read and edit. ---"
    },
    {
      "question": "Is raw HTML safe to use in every Markdown renderer?",
      "answer": "Not always. Some platforms and static-site generators sanitize or strip HTML for security reasons (to prevent script injection from untrusted content), so behavior depends on your specific tooling and its sanitization settings."
    },
    {
      "question": "Can I use HTML attributes like `class` or `id` on Markdown elements?",
      "answer": "Not on native Markdown syntax directly. To add a class or ID, you generally need to write the element as raw HTML instead, or use an extension specific to your renderer (some support a {.class #id} attribute syntax)."
    },
    {
      "question": "Does MDX treat HTML differently from plain Markdown?",
      "answer": "Yes, somewhat. MDX compiles HTML-looking tags as JSX, so components and raw HTML both get parsed by a JSX-aware compiler rather than a plain HTML parser, though standard tags like ` and ` still render the same way visually. ---"
    },
    {
      "question": "What to Read Next",
      "answer": "Images in Markdown: Complete Guide — See the centered-image and resizing use cases that motivated this article. How to Create Links in Markdown — Learn the target=\"_blank\" case where raw HTML fills a real Markdown gap."
    }
  ],
  "semanticFactualBody": "Markdown intentionally covers only a small set of formatting needs. The moment you need something it doesn't offer, such as centering an image, opening a link in a new tab, or hiding a note from readers, the fallback is plain HTML. Both links/index.mdx and images/index.mdx in this series already point to raw HTML for exactly those cases. This guide explains the actual rule that makes that work: when Markdown parsers recognize HTML tags and pass them through untouched. ) must be separated from surrounding Markdown by a blank line to parse correctly.\",   \"Markdown syntax is NOT processed inside an HTML block by default, only inside inline HTML spans.\",   \"Comments () are valid HTML passthrough too, and are a common way to hide notes from the rendered page.\" ]} /> --- How Does Markdown Recognize Raw HTML? CommonMark defines a fixed set of recognized HTML tags and patterns. When the parser encounters one, it copies it into the output as-is instead of escaping it as plain text. This renders as: This sentence has inline HTML mixed into it. Without that recognition, angle brackets would just print literally, the same way they do in ordinary prose about code (like the ` example earlier in this series). --- What Is the Difference Between Inline and Block HTML? **Inline HTML** sits inside a line of regular Markdown text, like the  example above. **Block HTML** is a standalone HTML element that takes up its own section, such as a  wrapping several lines of content. This renders as a cen"
}