Github Markdown - 使用 XML 和 HTML 渲染代码块 - kramdown vs redcarpet

Question

我在我的 git 站点中遇到了一些不寻常的错误。

注意:我正在使用 Kramdown + highlight.js 来突出显示代码。

下面是我正在学习的一课。在本课中，我需要渲染EML (类似于 XML)在代码块中。我正在使用 kramdown。
我还想在代码块中呈现 HTML - 例如，我需要一个代码块来解释如何添加包含文件:

{% include _toc.html %}

举个例子——下面的教训:
http://neoninc.github.io/NEON-DataSkills-Lesson-Development/R/EML/

网址
https://github.com/NEONInc/NEON-DataSkills-Lesson-Development/blob/gh-pages/_posts/EML/2015-12-12-Intro-to-EML.md

奇怪的是，当 JEKYLL 构建页面时，它正在运行包含 XML 和 HTML 的代码块。

我试过了:

<code>
<creator>
      <individualName>
        <givenName>Emery</givenName>
        <surName>Boose</surName>
      </individualName>
</creator>
</code>

这使得结束 </code>页面上的标签很奇怪。如果我不使用代码标签，那么 jekyll 会尝试解析 XML。

<pre><code class="xml">
<creator>
          <individualName>
            <givenName>Emery</givenName>
            <surName>Boose</surName>
          </individualName>
</creator>
</code></pre>

这仍然尝试解析和作为 HTML 标记。

我试图切换到 Redcarpet 。然而， Redcarpet 打破了我的分线框，我编码如下:使用{: .notice }将样式应用于 div。

<i class="fa fa-star"></i> **Data Tip:**  To figure out the full slot string, 
in `RStudio` we can use Tab Complete as we type.

最后——我的工作流程是从 RMD 到 md，所以在我构建时向每个代码块(pre 和 code)添加自定义代码是有问题的。

简而言之 - 我很难找到一个解决方案

允许带有 HTML/XML 的代码块

允许我将类/id 应用到我的突破 div。
{: .notice }

非常感谢您对此问题的任何反馈/指导。
利亚

Answer 1

如果您想在代码块中表示 XML/HTML，有几种方法可以做到。

第一个也是最基本的(简单且适用于每个实现)是简单地将代码块缩进至少四个空格:

    <creator>
        <individualName>
            <givenName>Emery</givenName>
            <surName>Boose</surName>
        </individualName>
    </creator>

请注意，没有 <pre>或 <code>使用了标签。在 most any implementation ，这将呈现为:

<pre><code>&lt;creator&gt;
    &lt;individualName&gt;
        &lt;givenName&gt;Emery&lt;/givenName&gt;
        &lt;surName&gt;Boose&lt;/surName&gt;
    &lt;/individualName&gt;
&lt;/creator&gt;
</code></pre>

请注意，XML 被转义(尖括号被 HTML 实体替换)，因此浏览器不会将其解释为 HTML。然而，它会为读者正确显示它。

由于 Highligh.js 具有自动语言检测功能，这对于大多数代码块来说应该足够了。如果您担心 Highlight.js 会被转义的 XML 混淆，请不要担心，Highlight.js 实际上希望得到这样的转义代码。如果给定未转义的 XML，则更有可能感到困惑。但是，如果您想明确定义语言，那么您仍然有几个选择。

要使用原始 HTML 创建您自己的代码块(可能为语法高亮分配一个类)，您需要自己手动转义 XML。将以下文本直接插入到您的 Markdown 文档中:

<pre><code class="xml">&lt;creator&gt;
    &lt;individualName&gt;
        &lt;givenName&gt;Emery&lt;/givenName&gt;
        &lt;surName&gt;Boose&lt;/surName&gt;
    &lt;/individualName&gt;
&lt;/creator&gt;
</code></pre>

请注意，在这种情况下，代码块没有缩进，因为它是原始 HTML，应该按原样解释。当然，每次都像这样手动转义 XML 不是很方便。

作为替代方案，一些 Markdown 实现包含一个称为“隔离代码块”的附加组件，它不需要缩进，但允许将类分配给代码块并提供自动转义。事实证明，Kramdown supports此功能。要使用它，请执行以下操作:

~~~ xml
<creator>
    <individualName>
        <givenName>Emery</givenName>
        <surName>Boose</surName>
    </individualName>
</creator>
~~~

Kramdown 将 output这:

<pre><code class="language-xml">&lt;creator&gt;
    &lt;individualName&gt;
        &lt;givenName&gt;Emery&lt;/givenName&gt;
        &lt;surName&gt;Boose&lt;/surName&gt;
    &lt;/individualName&gt;
&lt;/creator&gt;
</code></pre>

请注意，XML 已正确转义，并分配了一个类来标识该语言。虽然 Kramdown 附加了 language-到类名 Highlight.js 就可以理解这一点(事实上，这是 HTML5 Spec 推荐的格式)。作为它的docs状态:

Classes can also be prefixed with either language- or lang-.

附带说明一下，起初我认为 Krandown 不支持“隔离代码块”，但那是因为我尝试了 GitHub 推广的三个反引号语法(``` 而不是 ~~~)。但是，Kramdown 仅支持最早在 Markdown 邮件列表中讨论并由 Python Markdown 和 PHP Markdown Extra 多年前同时引入的较旧的原始波浪号语法。据我所知，Kramdown 是唯一仍然只使用旧代字号语法的实现(例如，Python 和 PHP 实现的现代版本都支持代字号和反引号)。