Skip to content

Commit

Permalink
Breaking change: switch to '{{%' decorators in shortcodes to better s…
Browse files Browse the repository at this point in the history 
…upport shortcode-in-shortcode
  • Loading branch information
@alex-shpak
alex-shpak committed Oct 4, 2024
1 parent 69886cc commit 925dbd3
Show file tree
Hide file tree
Showing 21 changed files with 61 additions and 91 deletions.
4 changes: 2 additions & 2 deletions exampleSite/content.bn/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ type: docs

# বাংলা ভাষায় শুরু করুন

{{< columns >}}
{{% columns %}}
## অস্ট্রিস চিপসে ফুর্তিভা

Est in vagis et Pittheus tu arge accipiter regia iram vocatur nurus. Omnes ut
Expand All @@ -19,7 +19,7 @@ modo arsit? Utinam rapta fiducia valuere litora _adicit cursu_, ad facies
Ea _furtique_ risere fratres edidit terrae magis. Colla tam mihi tenebat:
miseram excita suadent es pecudes iam. Concilio _quam_ velatus posset ait quod
nunc! Fragosis suae dextra geruntur functus vulgata.
{{< /columns >}}
{{% /columns %}}


## টেম্পোরার নিশি
Expand Down
4 changes: 2 additions & 2 deletions exampleSite/content.en/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ type: docs

# Acerbo datus maxime

{{< columns >}}
{{% columns %}}
## Astris ipse furtiva

Est in vagis et Pittheus tu arge accipiter regia iram vocatur nurus. Omnes ut
Expand All @@ -19,7 +19,7 @@ modo arsit? Utinam rapta fiducia valuere litora _adicit cursu_, ad facies
Ea _furtique_ risere fratres edidit terrae magis. Colla tam mihi tenebat:
miseram excita suadent es pecudes iam. Concilio _quam_ velatus posset ait quod
nunc! Fragosis suae dextra geruntur functus vulgata.
{{< /columns >}}
{{% /columns %}}


## Tempora nisi nunc
Expand Down
4 changes: 2 additions & 2 deletions exampleSite/content.en/docs/shortcodes/buttons.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,5 +9,5 @@ Buttons are styled links that can lead to local page or external link.
{{</* button href="https://github.com/alex-shpak/hugo-book" */>}}Contribute{{</* /button */>}}
```

{{< button relref="/" >}}Get Home{{< /button >}}
{{< button href="https://github.com/alex-shpak/hugo-book" >}}Contribute{{< /button >}}
{{<button relref="/">}}Get Home{{</button>}}
{{<button href="https://github.com/alex-shpak/hugo-book">}}Contribute{{</button>}}
8 changes: 4 additions & 4 deletions exampleSite/content.en/docs/shortcodes/columns.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Columns help organize shorter pieces of content horizontally for readability.


```html
{{</* columns */>}} <!-- begin columns block -->
{{%/* columns */%}} <!-- begin columns block -->
# Left Content
Lorem markdownum insigne...

Expand All @@ -17,12 +17,12 @@ Lorem markdownum insigne...

# Right Content
Lorem markdownum insigne...
{{</* /columns */>}}
{{%/* /columns */%}}
```

## Example

{{< columns >}}
{{% columns %}}
## Left Content
Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
Expand All @@ -42,4 +42,4 @@ Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
protulit, sed sed aere valvis inhaesuro Pallas animam: qui _quid_, ignes.
Miseratus fonte Ditis conubia.
{{< /columns >}}
{{% /columns %}}
12 changes: 6 additions & 6 deletions exampleSite/content.en/docs/shortcodes/details.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,19 @@ Details shortcode is a helper for `details` html5 element. It is going to replac

## Example
```tpl
{{</* details "Title" [open] */>}}
{{%/* details "Title" [open] */%}}
## Markdown content
Lorem markdownum insigne...
{{</* /details */>}}
{{%/* /details */%}}
```
```tpl
{{</* details title="Title" open=true */>}}
{{%/* details title="Title" open=true */%}}
## Markdown content
Lorem markdownum insigne...
{{</* /details */>}}
{{%/* /details */%}}
```

{{< details "Title" open >}}
{{% details "Title" open %}}
## Markdown content
Lorem markdownum insigne...
{{< /details >}}
{{% /details %}}
16 changes: 8 additions & 8 deletions exampleSite/content.en/docs/shortcodes/hints.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,29 @@ Hint shortcode can be used as hint/alerts/notification block.
There are 3 colors to choose: `info`, `warning` and `danger`.

```tpl
{{</* hint [info|warning|danger] */>}}
{{%/* hint [info|warning|danger] */%}}
**Markdown content**
Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
{{</* /hint */>}}
{{%/* /hint */%}}
```

## Example

{{< hint info >}}
{{% hint info %}}
**Markdown content**
Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
{{< /hint >}}
{{% /hint %}}

{{< hint warning >}}
{{% hint warning %}}
**Markdown content**
Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
{{< /hint >}}
{{% /hint %}}

{{< hint danger >}}
{{% hint danger %}}
**Markdown content**
Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
{{< /hint >}}
{{% /hint %}}
10 changes: 3 additions & 7 deletions exampleSite/content.en/docs/shortcodes/katex.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,21 @@ title: KaTeX
KaTeX shortcode let you render math typesetting in markdown document. See [KaTeX](https://katex.org/)

## Example

<div class="book-columns flex flex-wrap">
<div class="flex-even markdown-inner">
{{% columns %}}

```latex
{{</* katex display=true class="optional" >}}
f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
{{< /katex */>}}
```

</div>
<div class="flex-even markdown-inner">
<--->

{{< katex display=true class="optional" >}}
f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
{{< /katex >}}

</div>
</div>
{{% /columns %}}

## Display Mode Example

Expand Down
16 changes: 6 additions & 10 deletions exampleSite/content.en/docs/shortcodes/mermaid.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,16 @@

[MermaidJS](https://mermaid-js.github.io/) is library for generating svg charts and diagrams from text.

{{< hint info >}}
**Override Mermaid Initialization Config**

{{% hint info %}}
**Override Mermaid initialization config**
To override the [initialization config](https://mermaid-js.github.io/mermaid/#/Setup) for Mermaid,
create a `mermaid.json` file in your `assets` folder!
{{< /hint >}}
{{% /hint %}}

## Example


<div class="book-columns flex flex-wrap">
<div class="flex-even markdown-inner">
{{% columns %}}

```tpl
{{</* mermaid class="optional" >}}
Expand All @@ -28,8 +26,7 @@ stateDiagram-v2
{{< /mermaid */>}}
```

</div>
<div class="flex-even markdown-inner">
<--->

{{< mermaid class="optional" >}}
stateDiagram-v2
Expand All @@ -42,5 +39,4 @@ stateDiagram-v2
note left of State2 : This is the note to the left.
{{< /mermaid >}}

</div>
</div>
{{% /columns %}}
2 changes: 1 addition & 1 deletion exampleSite/content.en/docs/shortcodes/section/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,4 @@ Section renders pages in section as definition list, using title and description
{{</* section [summary] */>}}
```

{{<section summary >}}
{{<section summary>}}
26 changes: 13 additions & 13 deletions exampleSite/content.en/docs/shortcodes/tabs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,17 @@
Tabs let you organize content by context, for example installation instructions for each supported platform.

```tpl
{{</* tabs */>}}
{{</* tab "MacOS" */>}} # MacOS Content {{</* /tab */>}}
{{</* tab "Linux" */>}} # Linux Content {{</* /tab */>}}
{{</* tab "Windows" */>}} # Windows Content {{</* /tab */>}}
{{</* /tabs */>}}
{{%/* tabs */%}}
{{%/* tab "MacOS" */%}} # MacOS Content {{%/* /tab */%}}
{{%/* tab "Linux" */%}} # Linux Content {{%/* /tab */%}}
{{%/* tab "Windows" */%}} # Windows Content {{%/* /tab */%}}
{{%/* /tabs */%}}
```

## Example

{{< tabs >}}
{{< tab "MacOS" >}}
{{% tabs %}}
{{% tab "MacOS" %}}
# MacOS

This is tab **MacOS** content.
Expand All @@ -22,9 +22,9 @@ Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
protulit, sed sed aere valvis inhaesuro Pallas animam: qui _quid_, ignes.
Miseratus fonte Ditis conubia.
{{< /tab >}}
{{% /tab %}}

{{< tab "Linux" >}}
{{% tab "Linux" %}}

# Linux

Expand All @@ -34,9 +34,9 @@ Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
protulit, sed sed aere valvis inhaesuro Pallas animam: qui _quid_, ignes.
Miseratus fonte Ditis conubia.
{{< /tab >}}
{{% /tab %}}

{{< tab "Windows" >}}
{{% tab "Windows" %}}

# Windows

Expand All @@ -46,5 +46,5 @@ Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat
stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa
protulit, sed sed aere valvis inhaesuro Pallas animam: qui _quid_, ignes.
Miseratus fonte Ditis conubia.
{{< /tab >}}
{{< /tabs >}}
{{% /tab %}}
{{% /tabs %}}
22 changes: 0 additions & 22 deletions exampleSite/content.en/menu/index.md
View file

This file was deleted.

4 changes: 2 additions & 2 deletions exampleSite/content.ru/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ type: docs

# Стартовая страница на русском языке

{{< columns >}}
{{% columns %}}
## Astris ipse furtiva

Est in vagis et Pittheus tu arge accipiter regia iram vocatur nurus. Omnes ut
Expand All @@ -19,7 +19,7 @@ modo arsit? Utinam rapta fiducia valuere litora _adicit cursu_, ad facies
Ea _furtique_ risere fratres edidit terrae magis. Colla tam mihi tenebat:
miseram excita suadent es pecudes iam. Concilio _quam_ velatus posset ait quod
nunc! Fragosis suae dextra geruntur functus vulgata.
{{< /columns >}}
{{% /columns %}}


## Tempora nisi nunc
Expand Down
4 changes: 2 additions & 2 deletions exampleSite/content.zh/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ type: docs

# 中文索引页

{{< columns >}}
{{% columns %}}
## Astris ipse furtiva

Est in vagis et Pittheus tu arge accipiter regia iram vocatur nurus. Omnes ut
Expand All @@ -19,7 +19,7 @@ modo arsit? Utinam rapta fiducia valuere litora _adicit cursu_, ad facies
Ea _furtique_ risere fratres edidit terrae magis. Colla tam mihi tenebat:
miseram excita suadent es pecudes iam. Concilio _quam_ velatus posset ait quod
nunc! Fragosis suae dextra geruntur functus vulgata.
{{< /columns >}}
{{% /columns %}}


## Tempora nisi nunc
Expand Down
2 changes: 1 addition & 1 deletion layouts/shortcodes/button.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,5 @@
{{- $ref = relref $ . -}}
{{- end -}}
<a {{ with $ref }} href="{{.}}" {{ end }} {{ with $target }} target="{{.}}" rel="noopener" {{ end }} class="book-btn{{ with .Get "class" }} {{ . }}{{ end }}">
{{ .InnerDeindent | .Page.RenderString }}
{{ .InnerDeindent }}
</a>
4 changes: 2 additions & 2 deletions layouts/shortcodes/columns.html
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<div class="book-columns flex flex-wrap">
{{ range split .Inner "<--->" }}
{{ range split .InnerDeindent "<--->" }}
<div class="flex-even markdown-inner">
{{ . | $.Page.RenderString }}
{{ . | safeHTML }}
</div>
{{ end }}
</div>
4 changes: 2 additions & 2 deletions layouts/shortcodes/details.html
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<details {{ if or (.Get "open") (in .Params "open") }}open{{ end }}>
{{- $summary := cond .IsNamedParams (.Get "title") (.Get 0) -}}
<summary>{{ $summary | .Page.RenderString }}</summary>
<summary>{{ $summary }}</summary>
<div class="markdown-inner">
{{ .InnerDeindent | .Page.RenderString }}
{{ .InnerDeindent | safeHTML }}
</div>
</details>
2 changes: 1 addition & 1 deletion layouts/shortcodes/hint.html
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
<blockquote class="book-hint {{ .Get 0 }}">
{{ .InnerDeindent | .Page.RenderString }}
{{ .InnerDeindent | safeHTML }}
</blockquote>
2 changes: 1 addition & 1 deletion layouts/shortcodes/html.html
View file
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{{- .Inner -}}
{{- .Inner | safeHTML -}}
2 changes: 1 addition & 1 deletion layouts/shortcodes/katex.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,6 @@

<span {{- with .Get "class" }} class="{{ . }}"{{ end }}>
{{ with .Get "display" }}\[{{else}}\({{end}}
{{- trim .Inner "\n" -}}
{{- .InnerDeindent -}}
{{ with .Get "display" }}\]{{else}}\){{end}}
</span>
2 changes: 1 addition & 1 deletion layouts/shortcodes/mermaid.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,5 +8,5 @@
{{ end }}

<pre class="mermaid{{ with .Get "class" }} {{ . }}{{ end }}">
{{- .Inner | safeHTML -}}
{{- .Inner -}}
</pre>
2 changes: 1 addition & 1 deletion layouts/shortcodes/tabs.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
{{- $tab.Name -}}
</label>
<div class="book-tabs-content markdown-inner">
{{- .Content | $.Page.RenderString -}}
{{- .Content | safeHTML -}}
</div>
{{- end -}}
</div>

4 comments on commit 925dbd3

@jpritikin
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great! Thanks!

@matypist
Copy link

@matypist matypist commented on 925dbd3 Oct 4, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It still does not support shortcodes as hints within layouts, right?

Image

@alex-shpak
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It depends on the shotcode, {{% %}} notation will treat output as source of markdown and it will be processed as markdown
so if shortcode prints something that can be detected as markup it could break.
as example youtube shortcode prints spaces before actual html code, so markdown turns it into blockquote.

your example with T function would not work anyway. because T and i18n are hugo functions and not a shortcode
but there is an easy-enough fix, create a shortcode layouts/shortcodes/i18n.html with

{{ T (.Get 0) }}

now you can use

{{% hint warning %}}
  {{% i18n "Subj" %}}
{{% /hint %}}

@alex-shpak
Copy link
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I decided to add i18n shortcode to the theme, should be useful feature.
1bda9fb

Please sign in to comment.