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

Question

我在我的git网站上遇到了一些不寻常的错误.

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

以下是我正在研究的课程.在本课中,我需要EML在代码块中呈现 (类似于XML).我正在使用kramdown.我还想在代码块中呈现HTML - 例如,我需要一个代码块来解释如何添加包含文件:

{% include _toc.html %}

例证 - 以下课程:http: //neoninc.github.io/NEONvalsSkills-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会尝试PARSE 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)添加自定义代码是有问题的.

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

1. 允许使用HTML/XML的代码块
2. 允许我将一个类/ id应用于我的breakout div.{: .注意 }

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

Answer 1

如果要在代码块中表示XML/HTML,有几种方法可以实现.

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

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

请注意,没有使用<pre>或<code>标签.在大多数任何实现中,这将呈现为:

<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实现包含一个名为"fenced code blocks"的附加组件,它不需要缩进,但允许将类分配给代码块并提供自动转义.事实证明,Kramdown 支持此功能.要使用它,请执行以下操作:

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

而Kramdown将输出:

<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规范推荐的格式).正如其文档所述:

类也可以与任何前缀language-或lang-.

作为旁注,起初我认为Krandown不支持"fenced代码块",但那是因为我尝试了GitHub推广的三种反向语法(```相反~~~).但是,Kramdown仅支持Markdown邮件列表中首次讨论的较旧的原始tilde语法,并且多年前由Python Markdown和PHP Markdown Extra同时引入.据我所知,Kramdown是唯一仍然只使用较旧的tilde语法的实现(例如,Python和PHP实现的现代版本都支持波浪号和反向标记).

Answer 2

只需添加代码块关键字（xml,cpp等）即可实现此技巧：

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