笔记:Hugo 中 Shortcode 的基本使用


 拍摄于 2018-02-22, 春夏秋冬又一春。
拍摄于 2018-02-22, 春夏秋冬又一春。

起因

Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video ) to Markdown content. We think this contradicts the beautiful simplicity of Markdown’s syntax.

Hugo created Shortcodes to circumvent these limitations.

– 《What a Shortcode is

使用到 Shortcode,是博客迁移过程中的历史遗留问题。 博客中有不少自定义的样式,甚至有时候在写一篇笔记的时候直接在 markdown 文件里直接通过行内 <style/> 标签写一些想要的样式,例子是下面这几个不同颜色背景的区块:


使用 Jekyll 的时候,借助其 markdown 语法渲染引擎 kramdown 的帮助,这些不同背景颜色的 <div/>,要使其标签里的内容也可以获得 markdown 渲染,只需要在元素标签加上 markdown="1" 这个属性1

但 markdown 的标准中不允许 HTML 元素和 markdown 内容共存,所以 Hugo 的 markdown 语法解析器 BlackFriday 并没有对 markdown="1" 这个属性作支持,也没有找到其它类似的属性可以达到需要的效果。最后在社区里找到利用 Shortcode 来达到效果的办法2

基本使用

从基本的创建开始。首先在声明每一个 Shortcode 的时候,都需要在 ./layouts 目录下的同名目录(./Shortcodes) 下来创建对应的文件,结合自己使用感受,其实可以把 Shortcode 理解成 Hugo 视图渲染里的 template in template

以将 <div/> 之中的内容获得 markdown 渲染这一基础需求为例:

  1. 创建 ./layouts/Shortcodes/md.html
  2. 在上一步创建的 ./layouts/Shortcodes/md.html 中输入 {{ .Inner }}

之后在 html 中就可以通过一下片段来使 html 标签中的 markdown 生效:

但 Shortcode 的用法不止于此,本小节开头那几个作为例子、不同背景颜色区块使用的是同一个 Shortcode,被我命名为 section.html,通过传参的方式在不同时候调用不同的 class 已达到不同的区块显示效果:

比如我想建立一个 class="warning" 的区块,在 .md 中输入如下片段就可以调用:

效果:


除了 section.html 之外,本地还做了更好展示图片和 CodePen 的两个 Shortcode,展示图片的如下:

官方文档上也给出了相当多例子,比如图片墙,Shortcode 的相互嵌套,具体请阅读《Custom Shortcode Examples

感谢阅读

你们好, 2018 年初把小站从 Jekyll 迁移到 Hugo 的过程中,删除了评论区放的 Disqus 插件,考虑有二:首先无论评论、还是对笔记内容的进一步讨论,读者们更喜欢通过邮件、或者 Twitter 私信的方式来沟通;其次一年多以来 Disqus 后台能看到几乎都是垃圾留言(spam),所以这里直接贴一下邮件、以及 Twitter 账户 地址。

技术发展迭代很快,所以这些笔记内容也有类似新闻的时效性,不免有过时、或者错误的地方,欢迎指正 ^_^。

BEST
Lien(A.K.A 胡椒)
本站总访问量 本站总访客量 本文总阅读量