Hugo даёт стандартные shortcodes. Blowfish добавляет свои — для типичных задач блога.

Alert

#

alert выводит стилизованный блок-уведомление. Нужен когда важную информацию нельзя пропустить.

Внутри — Markdown, форматируй как угодно.

Пример 1: Без параметров

{{< alert >}}
**Внимание!** Это действие необратимо!
{{< /alert >}}

Пример 2: Безымянный параметр

{{< alert "twitter" >}}
Не забудь [подписаться](https://twitter.com/nunocoracao) в Twitter.
{{< /alert >}}

Пример 3: Именованные параметры

{{< alert icon="fire" cardColor="#e63946" iconColor="#1d3557" textColor="#f1faee" >}}
Это ошибка!
{{< /alert >}}

Admonition

#

Admonition — визуальные блоки-выноски для акцентирования внимания.

Работает как alert, но через render hooks Hugo. Ключевое отличие — синтаксис Markdown, переносимый между платформами. Shortcodes — специфика Hugo. Синтаксис похож на GitHub alerts:

> [!TIP]
> Admonition типа Tip.

> [!TIP]+ Свой заголовок + Своя иконка
> Сворачиваемый admonition с кастомным заголовком.
{icon="twitter"}

Знак alert (+ или -) — опционален, управляет сворачиванием. Работает только в Obsidian.

Accordion

#

accordion — сворачиваемые панели. Элементы задаются через accordionItem. Параметр mode управляет одновременным открытием нескольких элементов.

Параметры accordionItem:

Пример 1: mode="open" (несколько элементов открыты) + separated=true

{{< accordion mode="open" separated=true >}}
  {{< accordionItem title="Пример Markdown" icon="code" open=true >}}
  Этот элемент демонстрирует рендеринг Markdown:
  - **Жирный текст**
  - Списки
  - `inline code`
  {{< /accordionItem >}}

  {{< accordionItem title="Пример shortcode" md=false >}}
  Этот элемент демонстрирует рендеринг shortcode с <code>md=false</code>:
  
  {{< alert >}}Это inline alert.{{< /alert >}}
  {{< /accordionItem >}}
{{< /accordion >}}

Пример 2: mode="collapse" (только один элемент открыт)

{{< accordion mode="collapse" >}}
  {{< accordionItem title="Первый элемент" open=true >}}
  Этот элемент использует Markdown с коротким списком:
  1. Один
  2. Два
  3. Три
  {{< /accordionItem >}}

  {{< accordionItem title="Второй элемент" md=false >}}
  Этот элемент включает другой shortcode:
  {{< badge >}}Tip{{< /badge >}}
  {{< /accordionItem >}}
{{< /accordion >}}

Article

#

article встраивает статью в markdown-файл. Параметр link — .RelPermalink встраиваемой статьи. Shortcode не отображает родительскую страницу. Важно: если сайт в подпапке (например, /blowfish/), включай этот путь в ссылку.

Пример:

{{< article link="/docs/welcome/" showSummary=true compactSummary=true >}}

Badge

#

badge — стилизованный бейдж для метаданных.

Пример:

{{< badge >}}
Новая статья!
{{< /badge >}}

Button

#

button — стилизованная кнопка для основного действия. Три опциональных параметра: href, target, rel — URL, target и relation ссылки.

Пример:

{{< button href="#button" target="_self" >}}
Призыв к действию
{{< /button >}}

Carousel

#

carousel — интерактивная карусель изображений. Адаптивная, занимает место одного изображения по вертикали. Все изображения на полную ширину родительского контейнера с заданным соотношением сторон (по умолчанию 16:9).

Подписи сопоставляются по ключу. Для локальных — имя файла (например, 01.jpg). Для внешних — полный URL.

Пример 1: Соотношение 16:9, явный список изображений

{{< carousel images="{gallery/03.jpg,gallery/01.jpg,gallery/02.jpg,gallery/04.jpg}" >}}

Previous Next

Пример 2: Соотношение 21:9, regex для изображений

{{< carousel images="gallery/*" aspectRatio="21-9" interval="2500" >}}

Previous Next

Пример 3: Подписи к изображениям

{{< carousel images="gallery/*" captions="{01.jpg:Первое изображение с *форматированием*,02.jpg:Второе изображение со [ссылкой](https://example.com)}" >}}

Previous Next

Chart

#

chart — графики через библиотеку Chart.js. Поддерживает разные типы диаграмм. Параметры — между тегами shortcode, Chart.js делает остальное.

Синтаксис и типы диаграмм — в официальной документации Chart.js.

Пример:

{{< chart >}}
type: 'bar',
data: {
  labels: ['Tomato', 'Blueberry', 'Banana', 'Lime', 'Orange'],
  datasets: [{
    label: '# of votes',
    data: [12, 19, 3, 5, 3],
  }]
}
{{< /chart >}}

Еще примеры диаграмм:

Bar chart

#

Line chart

#

Doughnut chart

#

Code Importer

#

Импорт кода из внешних источников без копипасты.

Пример:

{{< codeimporter url="https://raw.githubusercontent.com/nunocoracao/blowfish/main/layouts/shortcodes/mdimporter.html" type="go" >}}

{{ $url := .Get "url" }}
{{ with resources.GetRemote (urls.Parse $url) }}
  {{ .Content | markdownify }}
{{ else }}
  {{ warnf "mdimporter shortcode: unable to fetch %q: %s" $url .Position }}
{{ end }}

{{< codeimporter url="https://raw.githubusercontent.com/nunocoracao/blowfish/main/config/_default/hugo.toml" type="toml" startLine="11" endLine="18" >}}

enableRobotsTXT = true
summaryLength = 0

buildDrafts = false
buildFuture = false

enableEmoji = true

Codeberg Card

#

codeberg — карточка репозитория Codeberg через API. Показывает актуальную статистику: звёзды, форки.

Пример:

{{< codeberg repo="forgejo/forgejo" >}}

Figure

#

figure — вставка изображений. Заменяет базовый Hugo figure, добавляет оптимизацию производительности.

Если изображение — page resource, Hugo Pipes оптимизирует и масштабирует его под разные разрешения. Статические ассеты и внешние URL вставляются как есть.

Blowfish автоматически конвертирует изображения в стандартном Markdown-синтаксисе:

![Alt text](image.jpg "Image caption")

Пример:

{{< figure
    src="abstract.jpg"
    alt="Abstract purple artwork"
    caption="Photo by [Jr Korpa](https://unsplash.com/@jrkorpa) on [Unsplash](https://unsplash.com/)"
    >}}

<!-- ИЛИ -->

![Abstract purple artwork](abstract.jpg "Photo by [Jr Korpa](https://unsplash.com/@jrkorpa) on [Unsplash](https://unsplash.com/)")

Forgejo Card

#

forgejo — карточка репозитория Forgejo через API. Актуальная статистика: звёзды, форки.

Пример:

{{< forgejo server="https://v11.next.forgejo.org" repo="a/mastodon" >}}

Gallery

#

gallery — адаптивная галерея с разнообразными компоновками.

Для изображений используй img теги с классом class="grid-wXX" — ширина колонки. Доступные ширины: от 10% до 100% с шагом 5%. Пример: 65% → grid-w65. Также доступны 33% и 66% для галерей в 3 колонки. Tailwind-индикаторы для адаптивной сетки.

Для подписей — figure shortcode внутри gallery. Ширину задавай через figureClass, текст — через caption.

Пример 1: Обычная галерея

{{< gallery >}}
  <img src="gallery/01.jpg" class="grid-w33" />
  <img src="gallery/02.jpg" class="grid-w33" />
  <img src="gallery/03.jpg" class="grid-w33" />
  <img src="gallery/04.jpg" class="grid-w33" />
  <img src="gallery/05.jpg" class="grid-w33" />
  <img src="gallery/06.jpg" class="grid-w33" />
  <img src="gallery/07.jpg" class="grid-w33" />
{{< /gallery >}}

Пример 2: Адаптивная галерея

{{< gallery >}}
  <img src="gallery/01.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
  <img src="gallery/02.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
  <img src="gallery/03.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
  <img src="gallery/04.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
  <img src="gallery/05.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
  <img src="gallery/06.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
  <img src="gallery/07.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
{{< /gallery >}}

Пример 3: Галерея с подписями (через figure)

{{< gallery >}}
  {{< figure src="gallery/01.jpg" alt="Gallery image 1" caption="Первая подпись" figureClass="grid-w33" >}}
  {{< figure src="gallery/02.jpg" alt="Gallery image 2" caption="Вторая подпись" figureClass="grid-w33" >}}
  {{< figure src="gallery/03.jpg" alt="Gallery image 3" caption="Третья подпись" figureClass="grid-w33" >}}
{{< /gallery >}}

Gist

#

gist — встраивание GitHub Gist: пользователь, ID, опционально — конкретный файл.

Пример 1: Весь Gist

{{< gist "octocat" "6cad326836d38bd3a7ae" >}}

Пример 2: Конкретный файл из Gist

{{< gist "rauchg" "2052694" "README.md" >}}

Gitea Card

#

gitea — карточка репозитория Gitea через API. Актуальная статистика: звёзды, форки.

Пример:

{{< gitea server="https://git.fsfe.org" repo="FSFE/fsfe-website" >}}

GitHub Card

#

github — карточка GitHub-репозитория с актуальной статистикой: звёзды, форки.

Пример:

{{< github repo="nunocoracao/blowfish" showThumbnail=true >}}

nunocoracao/blowfish

Personal Website & Blog Theme for Hugo

HTML

2627

684

GitLab Card

#

gitlab — карточка GitLab Project (репозитория в терминологии GitLab). Актуальная статистика: звёзды, форки. В отличие от github, не показывает основной язык проекта. Поддерживает кастомный URL инстанса GitLab — если доступен endpoint api/v4/projects/, работает с self-hosted и enterprise.

Пример:

{{< gitlab projectID="278964" >}}

Hugging Face Card

#

huggingface — карточка модели или датасета Hugging Face. Актуальная информация: лайки, загрузки, тип и описание.

Важно: Используй либо model, либо dataset — не оба.

Пример 1 (Модель):

{{< huggingface model="google-bert/bert-base-uncased" >}}

Пример 2 (Датасет):

{{< huggingface dataset="stanfordnlp/imdb" >}}

Icon

#

icon — SVG-иконка, масштабируется под текущий размер текста. Единственный параметр — имя иконки.

Пример:

{{< icon "github" >}}

Результат:

Иконки загружаются через Hugo pipelines — максимальная гибкость. Blowfish включает набор встроенных иконок для соцсетей, ссылок и прочего.

Свои иконки: положи SVG в assets/icons/ проекта. В shortcode используй имя файла без .svg.

KaTeX

#

katex — математические выражения через KaTeX. Синтаксис — в справочнике TeX-функций.

Shortcode достаточно вставить один раз на странице — KaTeX автоматически отрендерит всю разметку. Поддерживаются inline и block нотации.

Inline: оберни выражение в \( и \). Block: используй $$.

Пример:

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

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

Keyword

#

keyword — визуальное выделение важных слов и фраз (например, профессиональных навыков). keywordList — группировка нескольких keyword.

Внутри — Markdown.

Пример 1:

{{< keyword >}} *Супер* навык {{< /keyword >}}

Пример 2:

{{< keywordList >}}
{{< keyword icon="github" >}} Lorem ipsum dolor. {{< /keyword >}}
{{< keyword icon="code" >}} **Важный** навык {{< /keyword >}}
{{< /keywordList >}}

{{< keyword >}} *Отдельный* навык {{< /keyword >}}

Lead

#

lead — акцент на начало статьи. Введение или важная информация. Оберни любой Markdown-контент.

Пример:

{{< lead >}}
Когда жизнь даёт тебе лимоны — делай лимонад.
{{< /lead >}}

List

#

list — список последних статей. Обязательный параметр limit ограничивает количество. where и value фильтруют статьи по параметрам. Shortcode не отображает родительскую страницу, но учитывает её в limit.

Пример 1:

{{< list limit=2 >}}

Недавние

Git Workflow для Hugo блога

23 февраля 2026·5 минут· loading · loading

Шпаргалки Git Workflow Hugo Cheatsheet

Пример 2:

{{< list title="Samples" cardView=true limit=6 where="Type" value="sample" >}}

Samples

LTR/RTL

#

ltr и rtl — смешивание направлений текста. Пользователи RTL-языков могут вставлять LTR-фрагменты. С % как внешним разделителем — Markdown внутри рендерится нормально (см. Hugo shortcodes).

Пример:

- Это markdown-список.
- Направление по умолчанию — LTR
{{% rtl %}}
- هذه القائمة باللغة العربية
- من اليمين الى اليسار
{{% /rtl %}}

• This is an markdown list.
• Its per default a LTR direction

Markdown Importer

#

Импорт markdown-файлов из внешних источников без копипасты.

Пример:

{{< mdimporter url="https://raw.githubusercontent.com/nunocoracao/nunocoracao/master/README.md" >}}

Hi there 👋

#

🧠 Principal PM @ Docker (AI, agents, infra) · Creator of Blowfish · Ex-founder · Mentor & advisor

• 🚀 Personal blog - n9o.xyz

• 🐡 Creator and maintainer of Blowfish @ Blowfish page

• 🐳 Principal Product Manager @ Docker - working on cagent

• 📚 mentoring @ mentorcruise

Mermaid

#

mermaid — диаграммы и визуализации через текст. Под капотом Mermaid — широкий набор диаграмм, графиков и форматов.

Пиши синтаксис Mermaid внутри shortcode — плагин сделает остальное.

Синтаксис и типы диаграмм — в официальной документации Mermaid.

Пример:

{{< mermaid >}}
graph LR;
A[Lemons]-->B[Lemonade];
B-->C[Profit]
{{< /mermaid >}}

graph LR;
A[Lemons]-->B[Lemonade];
B-->C[Profit]

Swatches

#

swatches — набор до трёх цветов для демонстрации палитры. Параметры — HEX-коды.

Пример:

{{< swatches "#64748b" "#3b82f6" "#06b6d4" >}}

Результат:

Tabs

#

tabs — вкладки для вариантов одного шага. Пример: инструкции по установке VS Code на разных платформах.

Пример 1: Базовое использование

{{< tabs >}}

    {{< tab label="Windows" >}}
    Установка через Chocolatey:

    ```pwsh
    choco install vscode.install
    ```

    или через WinGet

    ```pwsh
    winget install -e --id Microsoft.VisualStudioCode
    ```
    {{< /tab >}}

    {{< tab label="macOS" >}}
    ```bash
    brew install --cask visual-studio-code
    ```
    {{< /tab >}}

    {{< tab label="Linux" >}}
    См. [документацию](https://code.visualstudio.com/docs/setup/linux#_install-vs-code-on-linux).
    {{< /tab >}}

{{< /tabs >}}

Результат:

choco install vscode.install

winget install -e --id Microsoft.VisualStudioCode

brew install --cask visual-studio-code

Пример 2: С Group, Default и Icon

{{< tabs group="lang" default="Python" >}}
    {{< tab label="JavaScript" icon="code" >}}
    ```javascript
    console.log("Hello");
    ```
    {{< /tab >}}

    {{< tab label="Python" icon="sun" >}}
    ```python
    print("Hello")
    ```
    {{< /tab >}}

    {{< tab label="Go" icon="moon" >}}
    ```go
    fmt.Println("Hello")
    ```
    {{< /tab >}}
{{< /tabs >}}

{{< tabs group="lang" default="Python" >}}
    {{< tab label="JavaScript" icon="code" >}}
    ```javascript
    const add = (a, b) => a + b;
    ```
    {{< /tab >}}

    {{< tab label="Python" icon="sun" >}}
    ```python
    def add(a, b): return a + b
    ```
    {{< /tab >}}

    {{< tab label="Go" icon="moon" >}}
    ```go
    func add(a, b int) int { return a + b }
    ```
    {{< /tab >}}
{{< /tabs >}}

Результат:

console.log("Hello");

print("Hello")

fmt.Println("Hello")

const add = (a, b) => a + b;

def add(a, b): return a + b

func add(a, b int) int { return a + b }

Обе группы вкладок имеют одинаковый group="lang" — клик по любой вкладке синхронизирует обе группы. default="Python" делает Python активной вкладкой по умолчанию, icon="code" добавляет иконку перед текстом.

Timeline

#

timeline — визуальная хронология: профессиональный опыт, достижения проекта и т.д. Элементы — через timelineItem.

Пример:

{{< timeline >}}

{{< timelineItem icon="github" header="header" badge="badge test" subheader="subheader" >}}
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus non magna ex. Donec sollicitudin ut lorem quis lobortis. Nam ac ipsum libero. Sed a ex eget ipsum tincidunt venenatis quis sed nisl. Pellentesque sed urna vel odio consequat tincidunt id ut purus. Nam sollicitudin est sed dui interdum rhoncus. 
{{< /timelineItem >}}


{{< timelineItem icon="code" header="Another Awesome Header" badge="date - present" subheader="Awesome Subheader" >}}
With html code
<ul>
  <li>Coffee</li>
  <li>Tea</li>
  <li>Milk</li>
</ul>
{{< /timelineItem >}}

{{< timelineItem icon="star" header="Shortcodes" badge="AWESOME" >}}
With other shortcodes
{{< gallery >}}
  <img src="gallery/01.jpg" class="grid-w33" />
  <img src="gallery/02.jpg" class="grid-w33" />
  <img src="gallery/03.jpg" class="grid-w33" />
  <img src="gallery/04.jpg" class="grid-w33" />
  <img src="gallery/05.jpg" class="grid-w33" />
  <img src="gallery/06.jpg" class="grid-w33" />
  <img src="gallery/07.jpg" class="grid-w33" />
{{< /gallery >}}
{{< /timelineItem >}}

{{< timelineItem icon="code" header="Another Awesome Header">}}
{{< github repo="nunocoracao/blowfish" >}}
{{< /timelineItem >}}

{{< /timeline >}}

1. header

   badge test

   subheader

   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus non magna ex. Donec sollicitudin ut lorem quis lobortis. Nam ac ipsum libero. Sed a ex eget ipsum tincidunt venenatis quis sed nisl. Pellentesque sed urna vel odio consequat tincidunt id ut purus. Nam sollicitudin est sed dui interdum rhoncus.
2. Another Awesome Header

   date - present

   Awesome Subheader

   With html code

   • Coffee
   • Tea
   • Milk
3. Shortcodes

   AWESOME

   With other shortcodes

   
4. Another Awesome Header

   

   nunocoracao/blowfish

   Personal Website & Blog Theme for Hugo

   HTML

   2627

   684

TypeIt

#

TypeIt — самый универсальный JS-инструмент для эффекта печатной машинки. Простая конфигурация: одна или несколько строк, переносы, удаление и замена, сложный HTML.

Blowfish реализует подмножество функций TypeIt через shortcode. Текст — внутри typeit, поведение — через параметры.

Пример 1:

{{< typeit >}}
Lorem ipsum dolor sit amet 
{{< /typeit >}}

Пример 2:

{{< typeit 
  tag=h1
  lifeLike=true
>}}
Lorem ipsum dolor sit amet, 
consectetur adipiscing elit. 
{{< /typeit >}}

Пример 3:

{{< typeit 
  tag=h3
  speed=50
  breakLines=false
  loop=true
>}}
"Frankly, my dear, I don't give a damn." Gone with the Wind (1939)
"I'm gonna make him an offer he can't refuse." The Godfather (1972)
"Toto, I've a feeling we're not in Kansas anymore." The Wizard of Oz (1939)
{{< /typeit >}}

Video

#

video — встраивание локальных и внешних видео. Shortcode рендерит <figure> с адаптивным плеером и опциональной подписью.

Если браузер не воспроизводит видео — плеер покажет fallback-сообщение со ссылкой на скачивание.

Пример:

{{< 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 Lite

#

Лёгкое встраивание YouTube через lite-youtube-embed. Библиотека быстрее и эффективнее стандартных embed.

Пример 1:

{{< youtubeLite id="SgXhGb-7QbU" label="Blowfish-tools demo" >}}

Пример 2:

Все параметры плеера YouTube для params:

Это видео начнётся с 130 секунды (2м10с)

{{< youtubeLite id="SgXhGb-7QbU" label="Blowfish-tools demo" params="start=130" >}}

Это видео без элементов управления, начнётся с 130 секунды и остановится через 10 секунд.

Для объединения нескольких параметров — символ & между ними:

{{< youtubeLite id="SgXhGb-7QbU" label="Blowfish-tools demo" params="start=130&end=10&controls=0" >}}

Подробнее — в репозитории youtubeLite и на странице параметров плеера YouTube.