# Integração com Hugo
[Hugo](https://gohugo.io/) é 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:
```bash
themes/seu-tema/layouts/shortcodes/kinescope.html
```
Ou na raiz do projeto (se você não estiver usando um tema):
```bash
layouts/shortcodes/kinescope.html
```
2. **Crie o arquivo com o seguinte conteúdo:**
```html
{{- /*
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 -}}
{{- else -}}
{{- end -}}
```
## **Configuração: passo 2 — adicionar estilos CSS**
Adicione estilos CSS para exibição correta (opcional, se não estiverem no seu tema):
```css
/* 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:
```markdown
{{}}
```
Ou use apenas o ID do vídeo:
```markdown
{{}}
```
Exemplo de incorporação de vídeo:
[Видео Kinescope]
### **Incorporação de playlists**
Para playlists, use a URL com o prefixo `/pl/`:
```markdown
{{}}
```
Ou especifique o tipo e o ID:
```markdown
{{}}
```
Exemplo de incorporação de playlist:
[Видео Kinescope]
### **Tamanho fixo do player**
Por padrão, o player é responsivo e se adapta à largura do contêiner. Para tamanho fixo, especifique `width` e `height`:
```markdown
{{}}
```
### **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:
```markdown
{{}}
```
Este exemplo inicia o vídeo a partir do 60º segundo e reproduz apenas os próximos 30 segundos.
Exemplo com parâmetros:
[Видео Kinescope]
### **Usando diferentes templates de player**
Para aplicar um template de player específico, use o parâmetro `player_id`:
```markdown
{{}}
```
### **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%`):
```markdown
{{}}
```
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:
```markdown
## Configurando a integração
Para começar com a integração, assista ao vídeo tutorial:
{{}}
Após assistir ao vídeo, passe para o próximo passo...
```
### **Em um blog**
Incorpore vídeo em posts de blog:
```markdown
---
title: "Novo Recurso do Kinescope"
date: 2025-12-25
---
O vídeo abaixo mostra o novo recurso da plataforma. Assista à demo:
{{}}
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:
```markdown
## Lição 1: Primeiros Passos
Assista a todos os vídeos na playlist:
{{}}
```
## **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:
```bash
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:
```markdown
{{}}
```
## **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`:
```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](https://gohugo.io/documentation/).
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](https://docs-br.kinescope.com/video-player/embedding/)** — princípios gerais de incorporação de vídeo
2. **[Personalizar o player](https://docs-br.kinescope.com/video-player/player-customization/)** — adapte a aparência do player à sua marca
3. **[Configurar proteção de conteúdo](https://docs-br.kinescope.com/content-protection/)** — ative a criptografia DRM e marcas d'água para proteger o vídeo
4. **[Restringir acesso por domínio](https://docs-br.kinescope.com/content-protection/access-restrictions/)** — 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!