Pular navegação

Integração com Hugo

Atualizado: 07.04.2026
Abrir como Markdown

Hugo é um gerador de sites estáticos rápido e moderno escrito em Go. O Kinescope fornece um shortcode pronto para incorporar convenientemente vídeos e playlists na documentação e blogs Hugo.

Quando você vai precisar da integração com Hugo

Use a integração com Hugo se:

  • Documentação no Hugo — você quer incorporar vídeo na sua documentação
  • Blog no Hugo — você precisa adicionar vídeo a posts de blog
  • Incorporação uniforme — todos os vídeos e playlists são incorporados da mesma forma via um shortcode simples
  • Responsivo — os players se adaptam automaticamente à largura do contêiner
  • Desempenho — lazy loading para tempos de carregamento de página otimizados

Se você usa Hugo para documentação ou blog — continue lendo. Abaixo você encontrará como configurar a integração em alguns minutos.

Como o shortcode funciona (4 passos)

  1. Instale o shortcode — adicione o arquivo de shortcode ao seu tema ou projeto
  2. Use o shortcode no Markdown — insira um comando simples em vez de código HTML
  3. Hugo processa o shortcode — durante a construção do site, gera o HTML correto com um iframe
  4. O vídeo é exibido na página — o player responsivo se adapta automaticamente ao contêiner

Agora vamos ver como configurar isso.

Configuração: passo 1 — instalar o shortcode

O shortcode kinescope já está incluído no tema de documentação do Kinescope. Se você estiver usando seu próprio tema ou quiser adicioná-lo a um projeto Hugo existente:

  1. Crie o arquivo de shortcode no diretório do seu tema:
themes/seu-tema/layouts/shortcodes/kinescope.html

Ou na raiz do projeto (se você não estiver usando um tema):

layouts/shortcodes/kinescope.html
  1. Crie o arquivo com o seguinte conteúdo:
{{- /* 
  Shortcode para incorporar players do Kinescope (vídeos e playlists)
*/ -}}

{{- $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;" -}}

{{- /* Validação: url ou id devem ser especificados */ -}}
{{- if and (not $url) (not $id) -}}
  {{- errorf "kinescope shortcode: either 'url' or 'id' parameter is required" -}}
{{- end -}}

{{- /* Determinar URL de incorporação */ -}}
{{- $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: unsupported URL format: %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 -}}

{{- /* Construir parâmetros de 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 -}}

{{- /* Determinar modo: responsivo ou fixo */ -}}
{{- $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 -}}

Configuração: passo 2 — adicionar estilos CSS

Adicione estilos CSS para exibição correta (opcional, se não estiverem no seu tema):

/* Estilos de incorporação do Kinescope */
.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;
}

Usando o shortcode

Incorporação básica de vídeo

A abordagem mais simples — especifique a URL completa do vídeo:

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

Ou use apenas o ID do vídeo:

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

Exemplo de incorporação de vídeo:

Incorporação de playlists

Para playlists, use a URL com o prefixo /pl/:

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

Ou especifique o tipo e o ID:

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

Exemplo de incorporação de playlist:

Tamanho fixo do player

Por padrão, o player é responsivo e se adapta à largura do contêiner. Para tamanho fixo, especifique width e height:

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

Parâmetros de reprodução

O shortcode suporta a passagem de parâmetros via query string. Por exemplo, para reproduzir um segmento de vídeo:

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

Este exemplo inicia o vídeo a partir do 60º segundo e reproduz apenas os próximos 30 segundos.

Exemplo com parâmetros:

Usando diferentes templates de player

Para aplicar um template de player específico, use o parâmetro player_id:

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

Definindo a proporção de aspecto

Para formatos de vídeo não padrão, você pode alterar a proporção de aspecto (o padrão é 16:9, correspondendo a padding-top: 56.25%):

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

O valor de ratio é especificado como porcentagem. Por exemplo:

  • 56.25 — proporção padrão 16:9
  • 75 — proporção 4:3
  • 100 — vídeo quadrado 1:1

Exemplos de uso no conteúdo

Na documentação

Adicione vídeo a um artigo de documentação:

## Configurando a integração

Para começar com a integração, assista ao vídeo tutorial:

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

Após assistir ao vídeo, passe para o próximo passo...

Em um blog

Incorpore vídeo em posts de blog:

---
title: "Novo Recurso do Kinescope"
date: 2025-12-25
---

O vídeo abaixo mostra o novo recurso da plataforma. Assista à demo:

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

Após o vídeo, adicione uma breve descrição e um link para o artigo detalhado, se necessário.

Em cursos online

Use playlists para aprendizado sequencial:

## Lição 1: Primeiros Passos

Assista a todos os vídeos na playlist:

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

Como funciona (em detalhes)

Validação e tratamento de erros

O shortcode verifica automaticamente a correção dos parâmetros durante a construção do site:

  • Se nem url nem id for especificado, o Hugo retornará um erro durante a construção
  • Se a URL tiver um formato não suportado, a construção falhará com um erro
  • Todos os erros são mostrados no console ao executar hugo ou hugo server

Exemplo de erro para uso incorreto:

ERROR: kinescope shortcode: either 'url' or 'id' parameter is required

O que a integração oferece

  • Incorporação uniforme: vídeos e playlists são incorporados da mesma forma — via shortcode.
  • Responsivo: o player se adapta à largura do contêiner.
  • Parâmetros: configurações de reprodução podem ser passadas (seek, duration, player_id, etc.).
  • Verificações em tempo de construção: erros de parâmetros são visíveis imediatamente durante a construção do site.
  • Lazy loading: o iframe carrega de forma lazy para evitar sobrecarregar a página.

Lazy loading

Todos os iframes carregam automaticamente com o atributo loading="lazy", melhorando o desempenho da página.

Suporte a todos os parâmetros do Kinescope

O shortcode suporta todos os parâmetros que podem ser passados na URL do player:

  • seek — posição inicial de reprodução (em segundos)
  • duration — duração do segmento (em segundos)
  • player_id — ID do template do player
  • autoplay — reprodução automática do vídeo
  • E outros parâmetros da API do Kinescope

Basta adicioná-los como parâmetros do shortcode:

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

Compatibilidade

O shortcode funciona com:

  • Hugo versão 0.100.0 e superior
  • Qualquer tema Hugo
  • Conteúdo em Markdown e HTML
  • Renderizadores Goldmark e Blackfriday (quando unsafe = true está habilitado na configuração)

Para o shortcode funcionar, habilite o seguinte em config.toml:

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

Isso permite que o Hugo processe o código HTML gerado pelo shortcode.

Suporte

Se você tiver perguntas sobre a integração com Hugo ou o uso do shortcode, entre em contato com o chat de suporte na interface do Kinescope — os especialistas vão ajudá-lo a configurar a incorporação de vídeo na sua documentação ou blog.

A documentação do Hugo está disponível no site oficial .

Pronto! Agora você pode incorporar vídeos e playlists do Kinescope na sua documentação ou blog Hugo.

O que fazer a seguir?

Após configurar a integração com Hugo, recomendamos:

  1. Incorporação — princípios gerais de incorporação de vídeo
  2. Personalizar o player — adapte a aparência do player à sua marca
  3. Configurar proteção de conteúdo — ative a criptografia DRM e marcas d’água para proteger o vídeo
  4. Restringir acesso por domínio — permita a visualização de vídeo apenas no seu site

Se tiver alguma dúvida, escreva para o chat de suporte na interface do Kinescope — nossos especialistas vão ajudar!

Artigos relacionados

  • Configuração de Login SSO

    Configurando Single Sign-On (SSO) no Kinescope via Keycloak ou AD FS: criação de clientes, configuração de funções e regras de transformação para integração corporativa.

  • Integração com Zoom

    Integração do Kinescope com Zoom: streaming via RTMP, importação automática de gravações, expansão do público e coleta de analytics de visualização.

  • Incorporação no WordPress

    Plugin do Kinescope para WordPress: instalação, configuração e uso de shortcodes para adicionar players de vídeo protegidos a páginas e posts do site.