Child themes na HubSpot: evoluir o site sem quebrar a produção

Todo site na HubSpot chega a um ponto em que o tema original não serve mais do jeito que veio. Uma cor de botão, um header diferente, um módulo a mais na home. E é nesse momento que muita equipe comete o erro mais caro do Content Hub: edita o tema direto, perde as atualizações do desenvolvedor e passa a manter um fork que ninguém documentou.

Child themes existem para evitar exatamente isso. Você cria uma camada por cima do tema original, muda só o que precisa e continua recebendo as atualizações do tema pai. Este guia explica como o mecanismo de herança funciona, como criar um child theme pela interface e pelo CLI, o que dá e o que não dá para sobrescrever, e como montar um fluxo de deploy que não derruba o site em produção.

Resposta direta: child theme é um tema que estende outro tema (o pai) por meio do campo extends no theme.json. Todo arquivo que não existir no child é herdado do pai; todo arquivo que existir no mesmo caminho substitui o do pai. Use child theme sempre que precisar customizar um tema do Marketplace, o tema padrão da HubSpot ou um tema próprio que outra equipe mantém.

Principais pontos

• A HubSpot define child theme como "a copy of an original parent theme" que você edita "without altering the parent theme". Na prática não é cópia: é herança por caminho de arquivo.
• Temas comprados no Marketplace e o tema Elevate, atual padrão da HubSpot, não podem ser clonados. O caminho oficial para customizá-los é o child theme.
• Limites por assinatura: 1 child theme no Starter e nas ferramentas gratuitas, 5 no Professional, 10 no Enterprise.
• Não existe child theme de child theme. A herança tem um nível só.
• Sobrescrever fields.json substitui o arquivo inteiro, não faz merge. Esse é o ponto onde mais gente quebra o tema.
• Atualizações do tema pai chegam ao child automaticamente. É o motivo principal para adotar o modelo.

O que é um child theme na HubSpot?

Child theme é um tema do Content Hub cujo theme.json declara um tema pai no campo extends. A partir dessa declaração, a HubSpot resolve cada arquivo do tema em duas etapas: procura primeiro no child e, se não encontrar, usa o do pai. Templates, módulos, CSS, JavaScript e o próprio fields.json seguem essa regra.

O resultado é um tema enxuto. Um child theme típico tem meia dúzia de arquivos: o theme.json com o extends, um child.css, um child.js e um ou dois templates que você precisou alterar de verdade. Todo o resto continua vindo do pai, inclusive quando o pai muda.

Isso é diferente de clonar. Um clone copia o tema inteiro para uma pasta nova e corta o vínculo com o original. Se o desenvolvedor do tema corrige um bug de acessibilidade no menu ou adapta o tema a uma mudança de plataforma, o clone não fica sabendo. O child theme fica.

A HubSpot permite child themes de três origens: os temas padrão da própria HubSpot (pasta @hubspot), temas do Template Marketplace (pasta @marketplace) e temas customizados que você ou sua agência mantêm. Para os dois primeiros, o child theme não é só recomendado, é o único caminho: a HubSpot bloqueia a clonagem de temas comprados no Marketplace e do Elevate, o tema padrão atual.

Se você está chegando agora no Content Hub como desenvolvedor, o nosso mapa completo do Content Hub para desenvolvedores situa onde os temas entram na arquitetura.

Como funciona a herança entre tema pai e child theme?

A regra é uma só e vale para qualquer arquivo: mesmo caminho relativo, o child vence. Se o tema pai tem templates/home.html e o child também tem templates/home.html, a HubSpot renderiza o do child. Se o child não tem, renderiza o do pai. Não existe merge de conteúdo entre os dois arquivos.

Isso tem três consequências práticas que valem a pena entender antes de começar.

1. A estrutura de pastas precisa espelhar a do pai. Um arquivo em css/main.css no child só sobrescreve css/main.css no pai. Se você salvar em styles/main.css, ele simplesmente não é usado. Na documentação de 2021, a HubSpot já avisava: "any theme files HubSpot doesn't find in the child theme folders automatically revert to parent theme files".

2. Sobrescrever fields.json é tudo ou nada. O arquivo de campos do tema (cores, fontes, espaçamentos que aparecem nas configurações do tema) não é mesclado. Se o child tiver um fields.json com três campos, o tema passa a ter três campos, e os templates do pai que dependiam dos outros quebram. Quem precisa adicionar um campo copia o fields.json inteiro do pai e acrescenta o novo no final.

3. As configurações do tema são independentes. O child tem os seus próprios valores de theme settings. Mudar a cor primária no child não altera o pai e vice-versa. É o que permite ter um child para o site institucional e outro para landing pages de campanha, cada um com sua paleta, sobre o mesmo código-base.

Quando o desenvolvedor do tema pai publica uma atualização no Marketplace, a HubSpot atualiza a pasta @marketplace e o child theme passa a herdar a versão nova de todo arquivo que você não sobrescreveu. Os arquivos que você sobrescreveu ficam como estavam. Por isso a recomendação é sobrescrever o mínimo possível: cada arquivo copiado para o child é um arquivo que você assume manter manualmente dali em diante.

Como criar um child theme na HubSpot?

Existem dois caminhos. O da interface resolve para quem vai mexer só em CSS e configurações. O do CLI é o certo para quem vai versionar o tema e trabalhar com mais de uma pessoa.

Pelo Design Manager (sem código local)

1. Acesse Conteúdo > Design Manager.
2. Abra a pasta @marketplace (temas comprados) ou @hubspot (temas padrão) e localize o tema pai.
3. Clique com o botão direito na pasta do tema e escolha Criar child theme.
4. Dê um nome. Em "Opções avançadas" você pode mudar a pasta de destino e os nomes dos arquivos CSS e JS.
5. Confirme.

A HubSpot cria uma pasta com o theme.json já apontando para o pai no campo extends, um child.css e um child.js vazios, e os templates que contêm a variável standard_header_includes, para que o CSS e o JS do child sejam carregados. Tudo que você escrever em child.css é aplicado depois do CSS do pai.

Pelo CLI (para versionar em Git)

O fluxo com o CLI da HubSpot é mais explícito e dá controle total sobre o que entra no child.

mkdir meu-child-theme hs fetch "@marketplace/nome-do-tema/theme.json" meu-child-theme/theme.json

Abra o theme.json baixado, troque o label e adicione o campo extends:

{   "label": "Insight Sales - Site 2026",   "extends": "@marketplace/nome-do-tema",   ... }

Para sobrescrever um arquivo, busque só ele, mantendo o mesmo caminho relativo:

hs fetch "@marketplace/nome-do-tema/templates/home.html" meu-child-theme/templates/home.html

Edite e suba:

hs upload meu-child-theme meu-child-theme

Durante o desenvolvimento, hs watch meu-child-theme meu-child-theme envia cada alteração salva automaticamente. Para temas padrão da HubSpot, o extends usa o prefixo @hubspot/, por exemplo @hubspot/elevate.

O fields.json merece atenção. A própria HubSpot orienta buscar o fields.json do pai antes do primeiro upload, mesmo que você não vá alterá-lo, para garantir que as configurações do tema apareçam completas no editor. Se não for mexer em campos, pode deixar de fora e o child herda o do pai.

O que dá e o que não dá para sobrescrever em um child theme?

Uma opinião que vem da prática: se o seu child theme está sobrescrevendo mais de um terço dos templates do pai, o modelo de child theme deixou de fazer sentido. Nesse ponto o tema pai não está mais servindo como base e talvez seja hora de um tema próprio. O nosso guia de módulos personalizados no Content Hub ajuda a decidir o que vira módulo e o que fica no template.

Child theme, clone ou editar o tema direto: qual escolher?

Editar o tema original só faz sentido quando o tema é seu, o código está em Git e ninguém mais depende dele. Clonar faz sentido quando você vai transformar o tema a ponto de o original virar apenas inspiração. Em todo o resto, child theme.

Como evoluir o site em produção sem quebrar nada?

Child theme resolve a metade do problema, que é não perder as atualizações do pai. A outra metade é processo. Este é o fluxo que usamos nos sites que mantemos no Content Hub.

1. O child theme vive em Git, não no Design Manager. Toda alteração passa por commit e revisão. O Design Manager fica como leitura. Se alguém editar lá direto, o próximo hs upload sobrescreve, e isso é um recurso, não um bug.

2. Sobrescreva o menor arquivo possível. Precisa mudar o header? Sobrescreva o partial do header, não o template base inteiro. Precisa mudar um estilo? child.css. Cada arquivo a mais no child é um arquivo que deixa de receber atualização.

3. Documente o que foi sobrescrito e por quê. Um README.md na raiz do child com a lista de arquivos e a razão de cada um. Quando o tema pai atualizar, essa lista é o seu checklist de teste.

4. Teste em sandbox antes de subir. Contas Enterprise têm sandbox do Content Hub. Sem sandbox, use um segundo child theme apontando para o mesmo pai, aplicado a uma página de teste não indexada. Dois child themes sobre o mesmo pai custam nada e evitam surpresas.

5. Use o histórico de versões da HubSpot como rede de segurança, não como estratégia. O Design Manager guarda versões de cada arquivo e permite reverter. Serve para um rollback rápido. Não substitui o Git.

6. Quando o tema pai atualizar, teste as páginas que usam os arquivos sobrescritos. A atualização do pai pode mudar uma classe CSS ou um nome de variável que o seu template sobrescrito ainda usa. Os arquivos herdados se atualizam sozinhos; os seus, não.

Se o site também é multi-idioma, vale um cuidado a mais: um único child theme para todos os idiomas, com as diferenças resolvidas em campos e conteúdo, nunca um child por idioma.

Por que child themes são uma decisão de RevOps, não só de desenvolvimento?

Porque o site é a maior máquina de conversão da operação e o tema é o que define quanto tempo leva para mudar alguma coisa nele. Um time de marketing que precisa abrir chamado para trocar a cor de um CTA está pagando o custo de um tema mal estruturado. Um child theme bem feito coloca essas decisões nas configurações do tema, onde marketing mexe sozinho, e deixa para o desenvolvedor só o que é estrutural.

O segundo ponto é continuidade. Agências trocam, desenvolvedores saem. Um site montado sobre um tema do Marketplace com child theme e Git tem um caminho claro para quem chega depois: o tema pai está documentado pelo autor, o child lista o que foi alterado, o histórico está no repositório. Um site montado sobre um tema editado direto no Design Manager por três anos é uma caixa preta.

E o terceiro é velocidade de campanha. Com dois ou três child themes sobre o mesmo pai, a equipe lança uma landing page com identidade de evento em uma tarde, sem tocar no site institucional. É esse tipo de autonomia que faz o Content Hub render como plataforma de geração de leads, e não só como hospedagem.

Perguntas frequentes

O que é um child theme na HubSpot?

É um tema que estende outro tema por meio do campo extends no theme.json. Arquivos que existem no child substituem os do pai no mesmo caminho; arquivos que não existem são herdados. Serve para customizar um tema sem perder as atualizações do original.

Quantos child themes posso criar?

Depende do plano: 1 nas ferramentas gratuitas e no Starter, 5 no Professional e 10 no Enterprise. Todos podem apontar para o mesmo tema pai.

Posso criar um child theme de um tema do Marketplace?

Pode, e é o único caminho para customizar esses temas, já que a HubSpot bloqueia a clonagem de temas comprados no Marketplace e do tema Elevate. No Design Manager, clique com o botão direito no tema dentro da pasta @marketplace e escolha "Criar child theme".

Posso criar um child theme de outro child theme?

Não. A herança tem um nível só. Se precisa de variações, crie vários child themes apontando para o mesmo pai.

O child theme recebe as atualizações do tema pai?

Sim, em todos os arquivos que você não sobrescreveu. Os arquivos que você copiou para o child ficam como estão e passam a ser responsabilidade sua.

Como adicionar um campo novo nas configurações do tema em um child theme?

Copie o fields.json completo do tema pai para o child, no mesmo caminho, e acrescente o campo. O arquivo não é mesclado: se o child tiver um fields.json parcial, os campos que faltarem somem do tema.

Child theme afeta a velocidade do site?

Não de forma relevante. A resolução de arquivos acontece no build da página, não no navegador. O que pesa é o CSS e o JS que você adiciona em child.css e child.js, então vale a mesma disciplina de qualquer tema.

Dá para versionar um child theme em Git?

Dá e é o recomendado. O child é uma pasta pequena, com poucos arquivos, e sobe para a HubSpot com hs upload ou hs watch pelo CLI.

Pronto para levar sua operação ao próximo nível?

A Insight Sales constrói e mantém sites no Content Hub há 13 anos, com mais de 300 clientes e 25 certificações HubSpot. Se o seu site está preso a um tema que ninguém consegue atualizar, ou você quer estruturar child themes e um fluxo de deploy que o time de marketing consiga operar, fale com a gente. A conversa começa pelo diagnóstico do tema atual, não pela proposta.