Skip to main content
View on GitHub

Markdown レンダーフック

レンダーフックにより、カスタムテンプレートがマークダウンのレンダリングをオーバーライドできるようになります。

On this page

これは、 Goldmark レンダラーでのみサポートされていることに注意してください。

layouts/_default/_markup にベース名 render-{kind} を持つテンプレートを作成することで、HTML へのデフォルトの Markdown レンダリングの特定の部分をオーバーライドできます。

また、たとえば layouts/blog/_markup のように、layouts/[type/section]/_markup にタイプ/セクション固有のフックを作成することもできます。

現在サポートされているフックの種類は、以下のとおりです。

必要に応じて、出力形式 および 言語 固有のテンプレートを定義できます。 layouts フォルダーは、以下のようになります。

l └ a ─ y ─ o u _ └ t d ─ s e ─ / f a _ ├ ├ ├ ├ ├ └ u m ─ ─ ─ ─ ─ ─ l a ─ ─ ─ ─ ─ ─ t r / k r r r r r r u e e e e e e p n n n n n n / d d d d d d e e e e e e r r r r r r - - - - - - c c h i i l o o e m m i d d a a a n e e d g g k b b i e e . l l n . . h o o g h r t c c . t s m k k h m s l - . t l . b h m x a t l m s m l h l . h t m l

上記のいくつかの使用例には、以下があります。

  • リンクの参照は .GetPage を使って解決します。これにより、./my-post.md (および GitHub で動作する同様の構造) を /blog/2019/01/01/my-post/ などに変換できるため、リンクが移植可能になります。
  • 外部リンクに target=_blank を追加します。
  • 画像を解決して 処理 します。
  • ヘッダーリンク  を追加します。

render-link および render-image テンプレートは、以下のコンテキストを受け取ります。

Page
レンダリングされる Page です。
Destination
URL です。
Title
タイトル属性です。
Text
レンダリングされた (HTML) リンクテキストです。
PlainText
上記のプレーンテキストのバリアントです。

render-Heading に渡されるコンテキスト

render-heading テンプレートは、以下のコンテキストを受け取ります。

Page
レンダリングされる Page です。
Level
ヘッダーレベル (1 から 6)
Anchor
ページ内のヘッダーに固有の自動生成された html ID です。
Text
レンダリングされた (HTML) テキストです。
PlainText
上記のプレーンテキストのバリアントです。
Attributes (map)
属性のマップ (たとえば、 id、class) です。現在、リンクの場合、これは常に空であることに注意してください。

また、render-image テンプレートは、以下のコンテキストも受け取ることになります。

IsBlock
これがスタンドアロン画像で、設定オプション markup.goldmark.parser.wrapStandAloneImageWithinParagraph が無効になっている場合は true を返します。
Ordinal
現在のドキュメントに含まれるすべての画像のゼロから始まる序数。
[Text](https://www.gohugo.io "Title")

以下は、render-link.html テンプレートがどのように見えるかのコード例です。

layouts/_default/_markup/render-link.html
<a href="{{ .Destination | safeURL }}"{{ with .Title }} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>

画像 Markdown の例 

![Text](https://gohugo.io/images/hugo-logo-wide.svg "Title")

以下は、render-image.html テンプレートがどのように見えるかのコード例です。

layouts/_default/_markup/render-image.html
<p class="md__image">
  <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title }} title="{{ . }}"{{ end }} />
</p>

以下のテンプレートファイル、

layouts/_default/_markup/render-heading.html
<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}"></a></h{{ .Level }}>

と、以下の Markdown ファイルに対して、

### Section A

レンダリングされた html は以下のようになります

<h3 id="section-a">Section A <a href="#section-a"></a></h3>

コードブロックのためのレンダーフック

すべてのコードブロックまたは特定のタイプ/言語 (以下の例では bash) のフックテンプレートを追加できます。

l └ a ─ y ─ o u _ └ t d ─ s e ─ f a _ └ └ u m ─ ─ l a ─ ─ t r k r r u e e p n n d d e e r r - - c c o o d d e e b b l l o o c c k k . - h b t a m s l h . h t m l

これらのコードブロックのデフォルトの動作は、コードのハイライト表示 ですが、これらのコードブロックに属性を渡すことができるので、ほとんどのことに使用できます。一例として、組み込みの GoAT ダイアグラム や、この Mermaid ダイアグラム コードブロック フック の例などがあります。

コードブロック テンプレートで受け取るコンテキスト (".") には、以下のものが含まれます。

Type (string)
コードブロックの種類を指定します。これは、コードのハイライト表示を行う際のプログラミング言語、たとえば bash になります。
Attributes (map)
Markdown から渡された属性です (たとえば、{ attrName1=attrValue1 attrName2="attr Value 2" })。
Options (map)
Chroma ハイライト処理オプションです。これは Type が既知の Chroma Lexer である場合にのみ入力されます。
Inner (string)
コード フェンス間のテキストです。
Ordinal (integer)
現在のドキュメントに含まれるすべてのコードブロックのゼロベースの (ゼロから始まる) 序数です。
Page
所有する Page です。
Position
ファイル名と位置 (行番号、列) を出力するため、エラーログに役立ちます。たとえば、 {{ errorf "error in code block: %s" .Position }} です。