Интеграция с Hugo

Обновлено: 28.12.2025

Hugo — быстрый и современный генератор статических сайтов, написанный на Go. Kinescope предоставляет готовый shortcode для удобного встраивания видео и плейлистов в документацию и блоги на Hugo.

Когда вам пригодится интеграция с Hugo

Используйте интеграцию с Hugo, если:

Документация на Hugo — хотите встраивать видео в вашу документацию
Блог на Hugo — нужно добавлять видео в посты блога
Единообразное встраивание — все видео и плейлисты встраиваются одинаково через простой shortcode
Адаптивность — плееры автоматически подстраиваются под ширину контейнера
Производительность — lazy loading для оптимизации загрузки страниц

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

Как работает shortcode (4 шага)

Устанавливаете shortcode — добавляете файл shortcode в вашу тему или проект
Используете shortcode в Markdown — вставляете простую команду вместо HTML-кода
Hugo обрабатывает shortcode — при сборке сайта генерирует правильный HTML с iframe
Видео отображается на странице — адаптивный плеер автоматически подстраивается под контейнер

Теперь разберём, как это настроить.

Настройка: шаг 1 — установка shortcode

Shortcode kinescope уже включён в тему документации Kinescope. Если вы используете свою тему или хотите добавить его в существующий проект Hugo:

Создайте файл shortcode в директории вашей темы:

themes/your-theme/layouts/shortcodes/kinescope.html

Или в корне проекта (если не используете тему):

layouts/shortcodes/kinescope.html

Создайте файл со следующим содержимым:

{{- /* 
  Shortcode для встраивания плееров Kinescope (видео и плейлисты)
*/ -}}

{{- $url := .Get "url" -}}
{{- $id := .Get "id" -}}
{{- $type := .Get "type" | default "" -}}
{{- $width := .Get "width" -}}
{{- $height := .Get "height" -}}
{{- $ratio := .Get "ratio" | default "56.25" -}}
{{- $allow := .Get "allow" | default "autoplay; fullscreen; picture-in-picture; encrypted-media; gyroscope; accelerometer; clipboard-write; screen-wake-lock;" -}}

{{- /* Валидация: должен быть указан либо url, либо id */ -}}
{{- if and (not $url) (not $id) -}}
  {{- errorf "kinescope shortcode: необходимо указать либо 'url', либо 'id' параметр" -}}
{{- end -}}

{{- /* Определяем embed URL */ -}}
{{- $embedUrl := "" -}}
{{- if $url -}}
  {{- if strings.HasPrefix $url "https://kinescope.io/embed/" -}}
    {{- $embedUrl = $url -}}
  {{- else if strings.HasPrefix $url "https://kinescope.io/pl/" -}}
    {{- $embedUrl = strings.Replace $url "https://kinescope.io/pl/" "https://kinescope.io/embed/pl/" 1 -}}
  {{- else if strings.HasPrefix $url "https://kinescope.io/" -}}
    {{- $embedUrl = strings.Replace $url "https://kinescope.io/" "https://kinescope.io/embed/" 1 -}}
  {{- else -}}
    {{- errorf "kinescope shortcode: неподдерживаемый формат URL: %s" $url -}}
  {{- end -}}
{{- else if $id -}}
  {{- if eq $type "pl" -}}
    {{- $embedUrl = printf "https://kinescope.io/embed/pl/%s" $id -}}
  {{- else -}}
    {{- $embedUrl = printf "https://kinescope.io/embed/%s" $id -}}
  {{- end -}}
{{- end -}}

{{- /* Собираем query параметры */ -}}
{{- $queryParams := slice -}}
{{- $serviceParams := slice "url" "id" "type" "width" "height" "ratio" "allow" "title" -}}
{{- range $key, $value := .Params -}}
  {{- if and (ne $key "_") (not (in $serviceParams $key)) -}}
    {{- $encodedValue := $value | urlquery -}}
    {{- $queryParams = $queryParams | append (printf "%s=%s" $key $encodedValue) -}}
  {{- end -}}
{{- end -}}

{{- if gt (len $queryParams) 0 -}}
  {{- $queryString := delimit $queryParams "&" -}}
  {{- $embedUrl = printf "%s?%s" $embedUrl $queryString -}}
{{- end -}}

{{- /* Определяем режим: адаптивный или фиксированный */ -}}
{{- $isFixed := and $width $height -}}

{{- if $isFixed -}}
  <div class="kinescope-embed kinescope-embed-fixed">
    <iframe 
      src="{{ $embedUrl }}"
      allow="{{ $allow }}"
      frameborder="0"
      allowfullscreen
      width="{{ $width }}"
      height="{{ $height }}"
      loading="lazy">
    </iframe>
  </div>
{{- else -}}
  <div class="kinescope-embed kinescope-embed-responsive" style="position: relative; padding-top: {{ $ratio }}%; width: 100%;">
    <iframe 
      src="{{ $embedUrl }}"
      allow="{{ $allow }}"
      frameborder="0"
      allowfullscreen
      style="position: absolute; width: 100%; height: 100%; top: 0; left: 0;"
      loading="lazy">
    </iframe>
  </div>
{{- end -}}

Настройка: шаг 2 — добавление CSS стилей

Добавьте CSS стили для корректного отображения (опционально, если их нет в теме):

/* Kinescope embed styles */
.kinescope-embed {
    margin: 1.5em 0;
    border-radius: var(--radius-md);
    overflow: hidden;
    background: var(--color-bg-tertiary);
}

.kinescope-embed-responsive {
    position: relative;
    width: 100%;
}

.kinescope-embed-responsive iframe {
    position: absolute;
    width: 100%;
    height: 100%;
    top: 0;
    left: 0;
    border: none;
}

.kinescope-embed-fixed {
    display: inline-block;
    max-width: 100%;
}

.kinescope-embed-fixed iframe {
    display: block;
    border: none;
    max-width: 100%;
    height: auto;
}

Использование shortcode

Базовое встраивание видео

Самый простой способ — указать полный URL на видео:

{{< kinescope url="https://kinescope.io/pcFNnQGsD59CMKte2SQQaz" >}}

Или использовать только ID видео:

{{< kinescope id="pcFNnQGsD59CMKte2SQQaz" >}}

Пример встраивания видео:

Встраивание плейлистов

Для плейлистов используйте URL с префиксом /pl/:

{{< kinescope url="https://kinescope.io/pl/5ifZjJLLGYncrHYBdPNhKE" >}}

Или укажите тип и ID:

{{< kinescope type="pl" id="5ifZjJLLGYncrHYBdPNhKE" >}}

Пример встраивания плейлиста:

Фиксированный размер плеера

По умолчанию плеер адаптивный и подстраивается под ширину контейнера. Для фиксированного размера укажите width и height:

{{< kinescope id="pcFNnQGsD59CMKte2SQQaz" width="560" height="315" >}}

Параметры воспроизведения

Shortcode поддерживает передачу параметров через query string. Например, для воспроизведения фрагмента видео:

{{< kinescope url="https://kinescope.io/pcFNnQGsD59CMKte2SQQaz" seek="60" duration="30" >}}

Этот пример запустит видео с 60-й секунды и будет воспроизводить только следующие 30 секунд.

Пример с параметрами:

Использование разных шаблонов плеера

Для применения конкретного шаблона плеера используйте параметр player_id:

{{< kinescope id="9cdAfqbbPcwu9GJwyxZ6jA" player_id="1213d24d-4624-4764-bf40-0baaf743377d" >}}

Настройка соотношения сторон

Для нестандартных форматов видео можно изменить соотношение сторон (по умолчанию 16:9, что соответствует padding-top: 56.25%):

{{< kinescope id="..." ratio="75" >}}

Значение ratio указывается в процентах. Например:

56.25 — стандартное соотношение 16:9
75 — соотношение 4:3
100 — квадратное видео 1:1

Примеры использования в контенте

В документации

Добавьте видео в статью документации:

## Настройка интеграции

Для начала работы с интеграцией посмотрите обучающее видео:

{{< kinescope url="https://kinescope.io/pcFNnQGsD59CMKte2SQQaz" >}}

После просмотра видео перейдите к следующему шагу...

В блоге

Встраивайте видео в посты блога:

---
title: "Новая функция Kinescope"
date: 2025-12-25
---

В видео ниже представлена новая функция платформы. Посмотрите демонстрацию:

{{< kinescope id="pcFNnQGsD59CMKte2SQQaz" >}}

Эта функция позволяет...

В обучающих курсах

Используйте плейлисты для последовательного обучения:

## Урок 1: Основы работы

Пройдите все видео из плейлиста:

{{< kinescope url="https://kinescope.io/pl/iUsqhEMVWJCcUqg9Ay9gmD" >}}

Как это работает (подробнее)

Валидация и обработка ошибок

Shortcode автоматически проверяет корректность параметров при сборке сайта:

Если не указан ни url, ни id, Hugo выдаст ошибку при сборке
Если URL имеет неподдерживаемый формат, сборка завершится с ошибкой
Все ошибки отображаются в консоли при выполнении hugo или hugo server

Пример ошибки при неправильном использовании:

ERROR: kinescope shortcode: необходимо указать либо 'url', либо 'id' параметр

Преимущества интеграции

Единообразное встраивание: все видео и плейлисты встраиваются одинаково через простой shortcode
Адаптивность: плееры автоматически подстраиваются под ширину контейнера
Поддержка параметров: можно передавать параметры для настройки воспроизведения (seek, duration, player_id и др.)
Валидация: ошибки в конфигурации обнаруживаются на этапе сборки сайта
Производительность: lazy loading для оптимизации загрузки страниц

Lazy loading

Все iframe автоматически загружаются с атрибутом loading="lazy", что улучшает производительность страниц.

Поддержка всех параметров Kinescope

Shortcode поддерживает все параметры, которые можно передать в URL плеера:

seek — начальная позиция воспроизведения (в секундах)
duration — длительность фрагмента (в секундах)
player_id — ID шаблона плеера
autoplay — автозапуск видео
И другие параметры API Kinescope

Просто добавьте их как параметры shortcode:

{{< kinescope id="..." seek="60" duration="30" autoplay="1" >}}

Совместимость

Shortcode работает с:

Hugo версии 0.100.0 и выше
Любыми темами Hugo
Markdown и HTML контентом
Goldmark и Blackfriday рендерерами (при включённом unsafe = true в конфигурации)

Для работы shortcode необходимо, чтобы в config.toml было включено:

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true

Это позволяет Hugo обрабатывать HTML-код, генерируемый shortcode.

Поддержка

Если у вас возникли вопросы по интеграции с Hugo или использованию shortcode, обратитесь в поддержку Kinescope — специалисты помогут настроить встраивание видео в вашу документацию или блог.

Документация по Hugo доступна на официальном сайте.

Всё! Теперь вы можете встраивать видео и плейлисты Kinescope в вашу документацию или блог на Hugo.

Что дальше?

После настройки интеграции с Hugo рекомендуем:

Встраивание — общие принципы встраивания видео
Кастомизировать плеер — настройте внешний вид плеера под ваш бренд
Настроить защиту контента — включите DRM-шифрование и водяные знаки для защиты видео
Ограничить доступ по доменам — разрешите просмотр видео только на вашем сайте

Остались вопросы? Напишите в чат поддержки — специалисты помогут!