Kramdown Jekyll

| 29-04-2021
[RAND-1-100] Comments



TLDR up front

There's a bug involving <picture> tags wrapped in <a> tags which is not in my power to fix.

Jekyll기반 블로그에서 고려할 마크다운은 kramdown이다. 그 이유는 Github page에서는 작년 5월부터 kramdown 만 지원하기 때문이다. A simple blog hosted in the cloud.

Kramdown jekyll
  1. During my migration to Jekyll I’ve found that the markdown parser, Maruku, doesn’t compile the current Codepen embed code.
  2. Front matter is metadata included at the beginning of a Markdown document, preceding its content. This data can be used by static site generators such as Jekyll, Hugo, and many other applications. When you view a Markdown file rendered by GitLab, any front matter is displayed as-is, in a box at the top of the document.

  • If you're getting extra {::nomarkdown} tags floating around your images, add nomarkdown: false to either the relevant preset or under picture in _config.yml.

  • If you're getting mangled HTML when trying to wrap images with anchor tags, add nomarkdown: true to the preset.

What's going on here:

Kramdown is Jekyll's default markdown parser. Kramdown gets grumpy when you give it a block level element (such as a <picture>) surrounded by a span level element (such as an <a>), and horribly mangles it. The fix for this is to tell Kramdown to chill with a {::nomarkdown}..{:/nomarkdown} wrapper.

Jekyll Picture Tag can be called from many different places: a markdown file, an HTML file, an HTML layout for a markdown file, and an HTML include, to name a few. JPT tries its best to determine whether its output will be parsed by Kramdown or not, but Jekyll itself doesn't make this particularly easy which results in some false positives. (The one I'm most aware of is when a markdown file uses an HTML layout which includes a picture tag.)

Jekyll kramdown code block

Unfortunately, I don't see an easy way to fix this. We've gotten this far mostly by trial and error. I'll continue to work on improving the autodetection, but you can override this behavior explicitly.

The fix:

By default, JPT will add a {::nomarkdown} tag if all of the following are true:

Kramdown Jekyll

Best Jekyll Themes

  • It thinks it's called from a markdown page
  • The image will be wrapped in an anchor tag (i.e. link_source_image: or a --link parameter)
  • This behavior hasn't been explicitly disabled.

You can disable nomarkdown tags globally by setting nomarkdown: false under the picture: key in _config.yml.

Jekyll Kramdown Config

You can enable or disable markdown tags per preset by adding nomarkdown: true|false to them. This setting overrides everything else, both JPT autodetection and the global setting.