在Jekyll HTML中嵌入Markdown

53

我正在试图在使用Jekyll的HTML文件中嵌套Markdown。有没有办法实现以下类似的效果?

# index.html

---
layout: default
---


<p>[Stack Overflow](http://www.stackoverflow.com)</p>

注意:我知道我可以选择这样做。

# index.html

---
layout: default
---


<p><a href="http://www.stackoverflow.com">Stack Overflow</a></p>
7个回答

88

如果您正在使用Kramdown,根据它们的文档,您可以这样做:

<div markdown="1">
   My text with **markdown** syntax
</div>

这样,div中的文本将会作为Markdown呈现。

请确保使用.md.markdown文件扩展名,因为.html文件不会被发送到Kramdown进行处理!


4
非常感谢,这个方案是提出的最清晰的解决方案。 - Art
5
注意缩进HTML代码时不要使用四个空格,否则会得到<pre>标签,请参见 https://github.com/gettalong/kramdown/issues/213 - tanguy_k
3
我也曾经为此苦苦挣扎,尝试过各种方法!!! 最终我找到了这个:http://ricostacruz.com/til/markdown-in-jekyll.html 长话短说,把 index.html 改成 index.md。花费了我太长时间才弄明白。 - Kobold
对我来说,与Jekyll 3.0兼容。 - Lucas
在最小的GitHub设置中,无法在default.html中工作。 - SeanFromIT
显示剩余2条评论

27

以下是如何使用Jekyll插件定义一个Markdown块的方法:

module Jekyll
  class MarkdownBlock < Liquid::Block
    def initialize(tag_name, text, tokens)
      super
    end
    require "kramdown"
    def render(context)
      content = super
      "#{Kramdown::Document.new(content).to_html}"
    end
  end
end
Liquid::Template.register_tag('markdown', Jekyll::MarkdownBlock)

为将此代码片段安装为插件,请将其放在源站根目录下的_plugins目录中的*.rb文件中。

然后可以按照以下方式使用:

{% markdown %}
[Stack Overflow](http://www.stackoverflow.com)
{% endmarkdown %}

编辑:请查看 @Cristian 的答案,这是一个更好的解决方案!如果您正在使用 Kramdown(因为您正在使用 Jekyll),您可以使用它的特性在带有 markdown="1" 属性的 div 内呈现 markdown。


1
请注意,我必须通过“gem install kramdown”来安装kramdown。不使用Jekyll内置的markdown解析器似乎有点hacky,但它确实有效! - Peter Ehrlich
2
请注意,Document.new(content, input: 'GFM) 可以为你启用 Github 风格的 Markdown。 - Peter Ehrlich
@PeterEhrlich:Jekyll默认使用Kramdown:https://github.com/jekyll/jekyll/blob/master/lib/jekyll/configuration.rb#L37。但是,如果能够以某种方式委托调用*当前配置中使用的任何Markdown处理器*,那将会更好。 - Per Lundberg
1
@detly,我已经更新了答案,并附上了简短的安装说明。 - MisterMetaphor
不适用于: {% markdown %}
  • 目录 {:toc} {% endmarkdown %}
- Natalie Perret
显示剩余2条评论

14

截至目前的Jekyll 3.6.2版本,以下两个选项可使生活变得更加简单:

在此输入图片描述

<div>
{{ "## Yes, this renders as markdown" | markdownify }}
</div>

注意markdown属性:

<div markdown="1">
## some markdown
inside some html. `snippet` _italic_ **bold**
</div>

markdown="1"应该适用于其他元素,比如display,还是只能在div中使用? - dlu
我不知道是否有一个“P”显示元素,但是它应该同样适用于<section><nav><main> - Frank N

9

@sunny-juneja,请查看名为markdownify的Liquid扩展过滤器:

https://github.com/mojombo/jekyll/wiki/liquid-extensions#markdownify

使用方式如下:

<p>{{ '[Stack Overflow](http://www.stackoverflow.com)' | markdownify }}</p>

输出标签中,将单引号或双引号括起来。

在Jekyll 1.0.0beta3版本上,它对我有效。


1
这适用于变量,但如果您想导入单独的Markdown文件或直接将Markdown放在HTML块中,则不适用。 @MisterMetaphor在下面提供的答案可以解决这个问题。 - KeyboardCowboy
我认为这不会起作用。输出内容将是<p><p><p><a href="http://www.stackoverflow.com">Stack Overflow</a></p> - srain

7

最近我花了很多时间尝试做类似的事情。@J.T.提到的第二个小点,参考了markdownify,是让我朝着正确方向前进的关键。

在我的_layouts目录中有几个不同的布局。其中一个,我想在页面内容之前添加一些“索引”。如果我直接从页面或文章中调用它,则索引作为部分起作用,但是当尝试将其添加到布局中时就不起作用了。

这是我拥有的:

---
layout: default
---

<div class="table-of-contents">
  
  {% include series_index.md %}
  
  {{ content }}
</div>


但它并没有起作用。与其在页面上呈现HTML,include却输出了Markdown,导致Markdown以丑陋的块状形式添加到了页面上,而不是以HTML格式呈现Markdown。因此,我尝试将| markdownify附加到include语句上,如下所示:
  {% include jekyll-bug-fix-index.md | markdownify %}

但是那并没有起作用。

解决方案:使用变量、捕获“块”和 markdownify

所以,我捕获了 Markdown,保存到一个变量中,然后使用 Liquid 的 markdownify 标签渲染该变量:

  {% capture index %}
  {% include series_index.md %}
  {% endcapture %}
  
  {{ index | markdownify }}

这个方法有效!Markdown被呈现为HTML放在我的页面上,一切都很好。

我毫不怀疑这是不传统的,希望有一天能学到更好的解决方案,但对我来说已经完全足够了,我想分享出来让其他人受益。


你让我开心了 ^^ - Despertaweb
@Josh_Thompson:谢谢!在你的帮助下我离目标最近了。但我的Markdown内容(主要链接部分)仍然无法正确呈现。我使用Markdown而不是HTML来处理包含许多链接的内容,并一直在努力使用jekyll来实现它。 - functional_overflow

5

要将在Jekyll页面中的markdown格式化字符串转换为HTML,以下有三种方法可供选择:


1. Kramdown:

如果您使用Kramdown,可以根据它们的文档进行如下操作:

<div markdown="1">
## Some Markdown Title
Let's have a look. `snippet` _italic_ **bold**
</div>

“markdown”属性:

  • 如果HTML标签具有属性markdown =“0”,则该标签将解析为原始的HTML块。
  • 如果HTML标签具有属性markdown =“1”,则使用默认机制解析此标签中的语法。
  • 如果HTML标签具有属性markdown =“block”,则该标签的内容将解析为块级元素。
  • 如果HTML标签具有属性markdown =“span”,则该标签的内容将解析为行内元素。

要求:

  • Markdown内容需要在
    标签内。
  • 确保使用.md或.markdown扩展名的文件,因为.html文件不会被发送到Kramdown进行处理。

2. Liquid扩展过滤器

有一个名为markdownify的Liquid扩展过滤器,它可以帮助您将Markdown格式的字符串转换为HTML。

<div>
{{ "Renders as markdown. `snippet` _italic_ **bold**" | markdownify }}
</div>

3. Jekyll插件:

jekyll-spaceship - 一个Jekyll插件,提供了强大的支持,包括表格、mathjax、mermaid、plantuml、emoji、youtube、vimeo、dailymotion等。

https://github.com/jeffreytse/jekyll-spaceship

使用这个插件,可以在HTML中轻松编写markdown:

<script type="text/markdown">
# Hybrid HTML with Markdown is a not bad choice ^\_^

##2. Table Usage

| :        Fruits \|\| Food       : |||
| :--------- | :-------- | :--------  |
| Apple      | :  Apple :| Apple      \
| Banana     |   Banana  | Banana     \
| Orange     |   Orange  | Orange     |
| :   Rowspan is 4    : || How's it?  |
|^^    A. Peach         ||   1. Fine :|
|^^    B. Orange        ||^^ 2. Bad   |
|^^    C. Banana        ||  It's OK!  |

## PlantUML Usage

@startuml
Bob -> Alice : hello
@enduml

## Video Usage

![](https://www.youtube.com/watch?v=Ptk_1Dc2iPY)
</script>

2

请查看Paul Irish的Gist,这里有一段JS代码,能够将你页面中的部分内容从Markdown格式转换成HTML格式。


这真的很酷。我希望有一个特定于Jekyll的解决方案,但如果没有人提供,我会将您标记为答案。 - sunnyrjuneja
如果这个代码片段消失了,这个答案对于未来的访问者就没有用处了。将内容放在这个答案中,同时提供原始链接,将使这个答案永远有用。 - Ky -

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接