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/

git url 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 破坏了我的分线框，我按如下方式编码：使用 {: .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 和代码）添加自定义代码是有问题的。

简而言之 - 我很难找到

的解决方案

允许带有 HTML / XML
允许我将 class/ id 应用到我的 breakout divs。 {: .notice}

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

Answer 1

您可以使用 jekyll highlight tag :

{% highlight xml %}
<creator>
      <individualName>
        <givenName>Emery</givenName>
        <surName>Boose</surName>
      </individualName>
</creator>
{% endhighlight %}

pygments highlight are here 的可用词法分析器。

Answer 2

如果您想在代码块中表示 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。然而，它将正确显示 reader。

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

要使用原始 HTML 创建您自己的代码块（可能分配一个 class 用于语法高亮显示），那么您需要自己手动转义 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，应该被解释 as-is。当然每次都那样手动转义XML也不是很方便

作为替代方案，一些 Markdown 实现包含一个名为 "fenced code blocks" 的 add-on，它不需要缩进，但允许将 class 分配给代码块并提供自动化逃跑。事实证明，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 已正确转义，并分配了 class 来标识语言。虽然 Kramdown 将 language- 附加到 class 名称，但 Highlight.js 可以很好地理解这一点（事实上，这是 HTML5 Spec). As its docs 状态推荐的格式：

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

作为旁注，起初我以为 Krandown 不支持 "fenced code blocks," 但那是因为我尝试了三种 back-ticks 语法（``` 而不是 ~~~) 由 GitHub 推广。然而，Kramdown 只支持在 Markdown 邮件列表中首次讨论并由 Python Markdown 和 PHP Markdown Extra 多年前同时引入的旧的原始波浪线语法。据我所知，Kramdown 是唯一仍然只使用旧波浪号语法的实现（例如 Python 和 PHP 实现的现代版本同时支持波浪号和 back-ticks）。

Answer 3

只需添加代码块关键字（xml,cpp 等）就可以做到这一点：

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

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

Github Markdown - rendering code blocks with XML & HTML - kramdown vs redcarpet

github

markdown

jekyll

redcarpet

kramdown