纯 markdown 无法实现可折叠代码块、表格横向滚动等交互功能，必须用 html；因 markdown 仅转换语法而不执行行为，html 标签如 或 可直接渲染生效，但需遵守空行、不嵌套 markdown 等混用规则。
你想在技术文档里插入一个可折叠的代码块，或者让表格支持横向滚动，又或者给一段文字加个点击展开的说明——这些需求用纯 Markdown 写不出来，但直接切到 HTML 又怕破坏文档结构和协作流程。
根本区别：一个写给人看，一个传给机器读
Markdown 是为「书写」设计的轻量标记语言，它的语法只覆盖纯文本能表达的范围，比如 # 标题、**加粗**、- 列表；HTML 是浏览器原生理解的「交付语言」，它定义结构（
你写一个 ## 二级标题，最终会被解析器转成 <h2>二级标题</h2>；但你写一个 <details><summary>点我展开</summary>内容</details>，Markdown 解析器会原样保留——因为它不认这个语法。
所以【不要指望 Markdown 解析器能执行 HTML 的行为】，它只做转换，不运行。
什么时候必须用 HTML？三个典型场景
方法一：需要语义化容器或布局控制
当你要把一段说明文字居中显示，或者让两段内容并排呈现，Markdown 没有对应语法。此时直接插入 <div style="text-align:center">居中文字</div> 即可。注意：某些静态站点生成器（如 Jekyll）会对 <div> 前后强制加空行，否则可能被套上 <code><p></p> 标签导致样式错乱。
方法二：需要原生交互元素
比如插入一个可展开/收起的 FAQ 区块：<details><summary>常见问题</summary><p>答案在这里</p></details>。这种标签在 GitHub README、Obsidian、Typora 中都可直接渲染生效，无需额外配置。
方法三：需要精确数学公式或特殊符号排版
LaTeX 公式（如 $E = mc^2$）依赖 MathJax 或 KaTeX 渲染，而它们底层加载的就是 HTML + JS；如果你的环境不支持 KaTeX，又想快速展示下标 Al2O3，直接写 HTML 标签比找插件更快。
混用时必须遵守的三条铁律
第一步：区块级 HTML 标签（<div>、<code><table>、<code><pre class="brush:php;toolbar:false;"></pre>、<p></p>）前后必须空一行，且不能缩进。
第二步：行内 HTML 标签（<em></em>、<span></span>、<sub></sub>）可直接嵌入段落、列表项、标题中，且其内部仍可使用 Markdown 语法，例如：这是<em>斜体</em>，也是**加粗** → 渲染为“这是斜体，也是加粗”。
第三步：禁止在 HTML 区块内混写 Markdown 语法，例如：<div>**这不会加粗**</div> → 它只会原样输出星号，因为解析器已进入“HTML 模式”，跳过 Markdown 解析阶段。
【一旦进入 第一步：准备一段超长代码，比如 50 行的 JSON 配置。 第二步：用 第三步：添加内联样式控制溢出： 第四步：将整段 HTML 粘贴进 README.md 文件，确保前后都有空行，保存后刷新页面即可看到垂直滚动条。 等区块标签，就彻底脱离 Markdown 解析上下文】，这点极易踩坑。
实操：在 GitHub README 中插入带滚动条的代码块
<pre class="brush:php;toolbar:false;"><code class="json">...</code></pre> 包裹，而非 Markdown 的 ```json 语法。<pre class="brush:php;toolbar:false;" style="max-height:300px;overflow-y:auto"><code class="json">...</code></pre>。
