# Media and Content Embeddings

## Article Card

The `article` shortcode generates a visual preview card for a specified internal page.

| Parameter | Description |
| --- | --- |
| `link` | **Required.** The logical path of the target internal page. |
| `showSummary` | **Optional.** Whether the page summary is displayed. **Default:** `true` |
| `lang` | **Optional.** Get page from another language of your site. |

**Example**

```md
{{</* article link="/docs/40-getting-started" showSummary="true" */>}}
```

{{< article link="/docs/40-getting-started" showSummary="true" >}}

> [!CAUTION]
> Avoid circular links to prevent infinite recursion.

## Cols

`cols` shortcode allows you to create flexible multi-column layouts with custom widths and optional responsive behaviors. Note that it uses markdown notation (`{{%/*  */%}}`).

| Parameter | Description |
| --- | --- |
| `widths` | **Optional.** Comma-separated list of column widths (e.g., `30%,70%`). If not specified, columns are evenly distributed. |
| `rwd` | **Optional.** Responsive web design (rwd) controls responsive behavior. When `true`, columns stack vertically on small screens and display horizontally on larger screens. **Default:** `true` |

```md
{{%/* cols widths="70%,30%" rwd=false %}}

![qwe](/img/01.webp)

<!-- cell -->

Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit.

{{% /cols */%}}
```

{{% cols widths="70%,30%" rwd=false %}}

![qwe](/img/01.webp)

<!-- cell -->

Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit.

{{% /cols %}}

See more examples in [rich-content](../../../blog/5-rich-content/index.md#cols-shortcode).

## Masonry

`masonry` shortcode allows you to create a fluid, masonry-style image gallery where items are arranged in columns with varying heights. The inner content uses YAML format to define images.

Images can be specified individually with `src`, or batch-loaded with `match`.

| Parameter | Description |
| --- | --- |
| `columns` | **Optional.** The number of columns to display. **Default:** `3` |

**YAML fields per item:**

| Field | Description |
| --- | --- |
| `src` | Image path. Resolves as page resource first, then global resource. |
| `match` | Glob pattern to batch-load images. See [`Match`](https://gohugo.io/functions/resources/match/) for more details. |
| `caption` | **Optional.** Caption text displayed below the image. |
| `alt` | **Optional.** Alt text for accessibility. Falls back to `caption` if omitted. |

**Example**

```yaml
{{</* masonry columns="3" >}}

- src: /img/02.webp
  alt: Fly high
  caption: Hello world!
- src: /img/03.webp
  alt: Contrails
- src: /img/04.webp
  alt: Parapet
- src: /img/05.webp
  alt: Wing
- src: /img/06.webp
  alt: Eaves
- src: /img/07.webp
  alt: Biplane sunset
- src: /img/drop.svg
  alt: SVG sample

{{< /masonry */>}}
```

{{< masonry columns="3" >}}

- src: /img/02.webp
  alt: Fly high
  caption: Hello world!
- src: /img/03.webp
  alt: Contrails
- src: /img/04.webp
  alt: Parapet
- src: /img/05.webp
  alt: Wing
- src: /img/06.webp
  alt: Eaves
- src: /img/07.webp
  alt: Biplane sunset
- src: /img/drop.svg
  alt: SVG sample

{{< /masonry >}}

## Code Importer

The `codeimporter` shortcode fetches source code from a remote URL and renders it as a highlighted code block.

| Parameter | Description |
| --- | --- |
| `url` | **Required.** The absolute URL of the remote source file. |
| `type` | **Optional.** The programming language for syntax highlighting. |
| `startLine` | **Optional.** The starting line number. **Default:** `1` |
| `endLine` | **Optional.** The ending line number. **Default:** `-1` |

**Example: Fetching specific lines from GitHub**

```md
{{</* codeimporter url="https://raw.githubusercontent.com/githubtraining/hellogitworld/refs/heads/master/src/main/java/com/github/App.java" type="java" startLine="3" endLine="7" */>}}
```

{{< codeimporter url="https://raw.githubusercontent.com/githubtraining/hellogitworld/refs/heads/master/src/main/java/com/github/App.java" type="java" startLine="3" endLine="7">}}

## Gallery

The `gallery` shortcode displays an image gallery with a main viewport, navigation buttons, and a scrollable thumbnail strip. The inner content uses YAML format to define images.

Images can be specified individually with `src`, or batch-loaded with `match`.

| Parameter | Description |
| --- | --- |
| `ratio` | **Optional.** Aspect ratio of the slide frame, in `x/y` format. **Default:** `4/3` |
| `fit` | **Optional.** How images fill the frame. `contain` shows the full image (may letterbox); `cover` crops to fill. **Default:** `contain` |
| `thumbs` | **Optional.** Whether to show the thumbnail strip. **Default:** `true` |
| `arrows` | **Optional.** Whether to show the previous/next buttons. **Default:** `true` |
| `counter` | **Optional.** Whether to show the slide counter. **Default:** `true` |

**YAML fields per item:**

| Field | Description |
| --- | --- |
| `src` | Image path. Resolves as page resource first, then global resource. |
| `match` | Glob pattern to batch-load images. See [`Match`](https://gohugo.io/functions/resources/match/) for more details. |
| `caption` | **Optional.** Caption text displayed below the main image. |
| `alt` | **Optional.** Alt text for accessibility. Falls back to `caption` if omitted. |

**Example 1: fit="cover" arrows=false**

```yaml
{{</* gallery ratio="32/9" fit="cover" arrows=false >}}

- match: /img/?[5-7]* # 05, 06, 07
- src: /img/drop.svg
  caption: gallery caption
  alt: gallery alt

{{< /gallery */>}}
```

{{< gallery ratio="32/9" fit="cover" arrows=false >}}

- match: /img/?[5-7]* # 05, 06, 07
- src: /img/drop.svg
  caption: gallery caption
  alt: gallery alt

{{< /gallery >}}

**Example 2: thumbs=false counter=false**

```yaml
{{</* gallery ratio="32/9" thumbs=false counter=false >}}

- match: /img/?[5-7]* # 05, 06, 07
- src: /img/drop.svg
  caption: gallery caption
  alt: gallery alt

{{< /gallery */>}}
```

{{< gallery ratio="32/9" thumbs=false counter=false >}}

- match: /img/?[5-7]* # 05, 06, 07
- src: /img/drop.svg
  caption: gallery caption
  alt: gallery alt

{{< /gallery >}}

## Gist

The `gist` shortcode embeds a GitHub Gist into the page.

| Parameter | Description |
| --- | --- |
| `0` | **Required.** GitHub username. |
| `1` | **Required.** Gist ID. |
| `2` | **Optional.** Specific filename. |

**Example: Embedding a specific file**

```md
{{</* gist mudge 3064 "count_benchmark.rb" */>}}
```

{{< gist mudge 3064 "count_benchmark.rb" >}}

## GitHub

The `github` shortcode creates a dynamic preview card for a GitHub repository.

| Parameter | Description |
| --- | --- |
| `repo` | **Required.** Format `owner/repo`. |
| `showThumbnail` | **Optional.** Display Open Graph image. **Default:** `true` |

**Example: Repository preview with thumbnail**

```md
{{</* github repo="gohugoio/hugo" */>}}
```

{{< github repo="gohugoio/hugo" >}}

## Icon

The `icon` shortcode renders an inline SVG icon from the theme's icon library.

| Parameter | Description |
| --- | --- |
| `0` | **Required.** Icon name. |

**Example**

```md
{{</* icon "activity" */>}}
{{</* icon "arrow-left-circle" */>}}
{{</* icon "clock" */>}}
```

{{< icon "activity" >}} {{< icon "arrow-left-circle" >}} {{< icon "clock" >}}

See all available icons in [reference page](../../1000-reference-icon/index.md).

## Md Importer

The `mdimporter` shortcode fetches and renders remote Markdown content. With the `md` optional combines with the [markdown notation](../../80-advanced/900-markdown-and-hugo/index.md#hugo-shortcodes), and the imported markdown could render TOC.

| Parameter | Description                                                                   |
| --------- | ----------------------------------------------------------------------------- |
| `url`     | **Optional.** The absolute URL of the Markdown file.                          |
| `page`    | **Optional.** The logical path of the target internal page.                   |
| `md`      | **Optional.** Whether to render the imported the content to markdown.         |

**Example**

General import:

```md
{{</* mdimporter url="https://github.com/ZhenShuo2021/hugo-yore/raw/refs/heads/main/README.md" */>}}
```

Render content TOC:

```md
{{%/* mdimporter url="https://github.com/ZhenShuo2021/hugo-yore/raw/refs/heads/main/README.md" md=false */%}}
```

Include an internal page:

```md
{{%/* mdimporter page="/docs/shortcodes/40-math/index.md" */%}}
```

## Video

The `video` shortcode embeds a HTML5 video player.

| Parameter | Description |
| --- | --- |
| `src` | **Required.** Video URL or local path. Local lookup order: page resource → `assets/` → `static/`. |
| `poster` | **Optional.** Poster image URL or local path. If omitted, the shortcode attempts a same-name image in the page bundle. |
| `caption` | **Optional.** Markdown caption shown below the video. |
| `autoplay` | **Optional.** Enables autoplay when `true`. **Default:** `false` |
| `loop` | **Optional.** Loops when `true`. **Default:** `false` |
| `muted` | **Optional.** Mutes when `true`. **Default:** `false` |
| `controls` | **Optional.** Shows the browser's default playback controls when `true`. **Default:** `true` |
| `playsinline` | **Optional.** Inline playback on mobile when `true`. **Default:** `true` |
| `preload` | **Optional.** `metadata` (load info), `none` (save bandwidth), or `auto` (preload more). **Default:** `metadata` |
| `start` | **Optional.** Start time in seconds. |
| `end` | **Optional.** End time in seconds. |
| `ratio` | **Optional.** Reserved aspect ratio for the player. Supports `16/9`, `4/3`, `1/1`, or custom `W/H`. **Default:** `16/9` |
| `fit` | **Optional.** How the video fits the ratio: `contain` (no crop), `cover` (crop to fill), `fill` (stretch). **Default:** `contain` |

**Example: Autoplay muted video**

```md
{{</* video
    src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
    poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
    caption="**Public domain demo** — CC0 video and poster."
    loop=true
    muted=true
*/>}}
```

{{< video
  src="https://upload.wikimedia.org/wikipedia/commons/5/5a/CC0_-_Public_Domain_Dedication_video_bumper.webm"
  poster="https://upload.wikimedia.org/wikipedia/commons/e/e0/CC0.jpg"
  caption="**Public domain demo** — CC0 video and poster."
  loop=true
  muted=true
>}}

## YouTube

The `youtubeLite` shortcode embeds an optimized YouTube video player.

| Parameter | Description |
| --- | --- |
| `id` | **Optional.** YouTube video ID. |
| `params` | **Optional.** URL parameters. |

**Example: Specific video with start time**

```md
{{</* youtubeLite id="ldX1Ii0MofQ" params="start=30" */>}}
```

{{< youtubeLite id="ldX1Ii0MofQ" params="start=30" >}}

## TypeIt

The `typeit` shortcode creates dynamic typewriter animations.

| Parameter | Description |
| --- | --- |
| `initialString` | **Optional.** Text shown before animation. |
| `speed` | **Optional.** Typing speed in ms. **Default:** `100` |
| `loop` | **Optional.** Whether to restart. **Default:** `false` |
| `tag` | **Optional.** HTML tag for wrapping. **Default:** `div` |

**Example: Looping animation with custom speed**

```md
{{</* typeit speed="50" loop="true" tag="h2" */>}}
Yore - A Simple Yet Powerful Hugo Theme
{{</* /typeit */>}}
```

{{< typeit speed="50" loop="true" tag="h2" >}}
Yore - A Simple Yet Powerful Hugo Theme
{{< /typeit >}}