Hugo serverでショートコードエラー

failed to extract shortcode

状況 

現在、ここのブログでは、GitllabでMarkdownを管理し、Gitでローカルマシンで記事を書いています。

流れは、GitlabからローカルのMacやLinuxへGitでcloneし、記事を書いて、コンパイル後pushしています。

hugoでは、serverモードがあり、hugo server -wとして起動すると、localhost:1313で書いた記事のプレビューモードで確認できたりします。

不具合症状 

ところが、hugo server -wした際に、下記のエラーが出ることがあります。

(現在のHugoテーマはBeautifulhugoを使用しています)

Error: Error building site: “/tmp/test/content/post/mermaid-sample.md:18:1”: failed to extract shortcode: template for shortcode “mermaid” not found

上記エラーは、mermaidですが、galleryであったり、要はshortcode書いてるけど、そんなshortcodeは無いよ!と言うエラーのようです。

原因 

Hugoの中のテーマをGitのサブモジュールと言う仕組みで構成している場合、git cloneする際にサブモジュールの取得が出来ていないのが原因です。

つまり、hugoでの構成が下記のようになっていますが、そのまま git cloneした場合、themes内のサブモジュールテーマが空なのです。

記事内に記述されたshortcodeがthemes/テーマ内のテンプレートファイルを探しに行くのでエラーとなるのです

├── archetypes
├── content
├── layouts
├── resources
├── static
└── themes

解決 

git cloneした際に、thmes内のテーマも取得してあげれば解決します。

サブモジュールで管理していない場合は、通常のgit cloneで問題ありません

$ git clone https://gitlab.com/user/test.git

今回はのようにサブモジュール構成にしてある場合は、git cloneする際、下記のようにサブモジュールも取得してあげればOKです

$ git clone --recurse-submodules --depth 1 https://gitlab.com/user/test.git

このようにする事で、theme内のサブモジュールも取得されるようになります

解決2 

ついつい、recurse-submodulesを忘れて、普通に git cloneしてしまい、今回のようなエラーに見舞われるのですが、実は、git cloneした後で、submoduleで管理しているリポジトリを取得することが出来ます。

git clone後にsubmoduleを更新する方法

$ git submodule update --init --recursive

今回のBeautifulhugoテーマをサブモジュールしたHugoではこんな感じです

$ git submodule status
-1ff3894b84b1802433b58e22dd22f4eb46a49fa9 themes/beautifulhugo

$ git submodule update --init --recursive
Submodule 'themes/beautifulhugo' (https://github.com/halogenica/beautifulhugo.git) registered for path 'themes/beautifulhugo'
Cloning into '/private/tmp/test/themes/beautifulhugo'...
Submodule path 'themes/beautifulhugo': checked out '1ff3894b84b1802433b58e22dd22f4eb46a49fa9'

度々、今回の症状に出くわすので、自分用のメモとして残しておきました