Shortcodes

Posted on Jul 20, 2024 5 mins

Table of Contents

In addition to all the default Hugo shortcodes, Kayals adds a few extras for additional functionality.

Callout

callout outputs its contents as a stylised message box within your article. It’s useful for drawing attention to important information that you don’t want the reader to miss.

Parameter	Description
`icon`	Optional. the icon to display on the left side. Default: `triangle-exclamation` (Check out the icon shortcode for more details on using icons.)
`iconColor`	Optional. the color for the icon in basic CSS style. Can be either hex values (`#FFFFFF`) or color names (`white`) By default chosen based on the current color theme.
`cardColor`	Optional. the color for the card background in basic CSS style. Can be either hex values (`#FFFFFF`) or color names (`white`) By default chosen based on the current color theme.
`textColor`	Optional. the color for the text in basic CSS style. Can be either hex values (`#FFFFFF`) or color names (`white`) By default chosen based on the current color theme.

Example 1

{{< callout >}}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed vestibulum diam in lectus efficitur, in consequat purus ultricies.
{{< /callout >}}

Rendered as:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed vestibulum diam in lectus efficitur, in consequat purus ultricies.

Example 2

{{< callout github >}}
Feel free to show your support by giving a star 🌟 on [GitHub](https://github.com/mnjm/kayal)
{{< /callout >}}

Rendered as:

Feel free to show your support by giving a star 🌟 on GitHub

Code Importer

codeimport can be used for importing code from external sources easily without copying and pasting.

Parameter	Description
`url`	Required URL to an externally hosted code file.
`type`	Code type used for syntax highlighting.
`startLine`	Optional The line number to start the import from.
`endLine`	Optional The line number to end the import at.
`showLineNos`	Optional Whether to show line numbers Default: `false`

Example 1

{{< codeimport url="https://raw.githubusercontent.com/mnjm/kayal/main/layouts/shortcodes/mdimport.html" type="go" >}}

Rendered as:

{{ $url := .Get "url"}}
{{ with resources.GetRemote (urls.Parse $url) }}
    {{ .Content | markdownify }}
{{ else }}
    {{ errorf "Mardown Importer Shortcode - Unable to get remote resource" . }}
{{ end }}

Example 2

{{< codeimport url="https://raw.githubusercontent.com/mnjm/kayal/main/config/_default/params.toml" startLine=95 type="toml" showLineNos=true >}}

Rendered as:

 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
# Whether to display taxonomies as a grid of cards.
cardView = true

# Term settings
[term]
# Whether to group articles by year.
groupByYear = false
# Whether to display breadcrumbs
showBreadcrumbs = false
# Whether to display pages as a card
cardView = true
# Whether to display RSS link
showRSS = false

# Social links
# [[social]]
# name = "GitHub"
# icon = "github"
# url = "https://github.com/mnjm/kayal"
#
# [[social]]
# name = "Email"
# icon = "email"
# url = "mailto:name@example.com"
#
# [[social]]
# name = "Twitter / X"
# icon = "x-twitter"
# url = "https://x.com/sample"

Collapse

collapse shortcode generates an HTML <details> element. It allows for collapsible content sections on your Hugo site.

Parameter	Description
`summary`	The summary text displayed as the clickable title of the collapsible section.
`open`	Optional boolean parameter. If set to `true`, the `<details>` element will be initially expanded/open. Default `false`
`Inner`	The inner content of the shortcode. This can include any additional text or Markdown content that should be displayed within the collapsible section.

Example

{{< collapse summary="Click to expand" open=true >}}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed vestibulum diam in lectus efficitur, in consequat purus ultricies.
{{< /collapse >}}

Rendered as:

Click to expand

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed vestibulum diam in lectus efficitur, in consequat purus ultricies.

Icon

icon outputs an SVG icon and takes the icon name as its only parameter. The icon is scaled to match the current text size. Here you can find all available icons.

Also new icons can be added, Check Icons Section in Advanced Customization

Example

GitHub Icon {{< icon "github" >}}

Rendered as:

GitHub Icon

KaTeX

katex shortcode can be used to add mathematical expressions to article content using the KaTeX package. Refer here for more info.

Example 1

{{< katex >}}
\\(f(a,b,c) = (a^2+b^2+c^2)^3\\)

Rendered as:

$f(a,b,c) = (a^2+b^2+c^2)^3$

Example 2

{{< katex >}}
$$
\det(A) = a_{11}
\begin{vmatrix} a_{22} & a_{23} \\ a_{32} & a_{33} \end{vmatrix}
- a_{12}
\begin{vmatrix} a_{21} & a_{23} \\ a_{31} & a_{33} \end{vmatrix}
+ a_{13}
\begin{vmatrix} a_{21} & a_{22} \\ a_{31} & a_{32} \end{vmatrix}
$$

Rendered as:

$$ \det(A) = a_{11} \begin{vmatrix} a_{22} & a_{23} \\ a_{32} & a_{33} \end{vmatrix} - a_{12} \begin{vmatrix} a_{21} & a_{23} \\ a_{31} & a_{33} \end{vmatrix} + a_{13} \begin{vmatrix} a_{21} & a_{22} \\ a_{31} & a_{32} \end{vmatrix} $$

Markdown Importer

mdimport allows you to import markdown files from external sources. This is useful for including content from other repositories or websites without having to copy and paste the content.

Parameter	Description
`url`	Required URL to an externally hosted markdown file.

<hr>
{{< mdimport url="https://raw.githubusercontent.com/mnjm/mnjm/master/README.md" >}}
<hr>

Rendered as:

Hi 👋, I'm Manjunath

About Me

I am currently working on Computer Vision, Machine Learning related projects. Sometimes on linux/foss stuff
Personal Site: mnjm.github.io
Email: manjunat.mohan@gmail.com

Mermaid

mermaid can be used for create diagrams and visualizations using text and code. It uses Mermaid.js which is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams.

Refer here for more examples.

Example

{{< mermaid >}}
graph TD
    B[Boil Water] --> C[Add Tea Powder]
    C --> D[Add Milk]
    D --> E[Add Sugar]
    E --> F[Strain]
    F --> G[Drink]
    G --> |Repeat|B
{{< /mermaid >}}

Rendered as:

graph TD B[Boil Water] --> C[Add Tea Powder] C --> D[Add Milk] D --> E[Add Sugar] E --> F[Strain] F --> G[Drink] G --> |Repeat|B