Como Aplicar Temas CSS Personalizados a uma Instância Mastodon

Muitos administradores de instâncias Mastodon desejam dar à sua comunidade uma aparência única que se destaque da interface padrão. O tema padrão do Mastodon usa um design azul e branco limpo, mas pode não combinar com sua marca ou preferência pessoal. Temas CSS personalizados permitem alterar cores, fontes, espaçamento e elementos de layout em toda a interface web. Este artigo explica como aplicar temas CSS personalizados a uma instância Mastodon usando o sistema de temas integrado e o painel Admin.

Visão geral das opções de personalização de temas do Mastodon

O Mastodon usa um framework CSS construído sobre os estilos da aplicação. O tema padrão é chamado “mastodon-light” e está no diretório app/javascript/styles/mastodon. Você pode modificar a aparência da sua instância de duas maneiras: adicionando CSS personalizado através da interface Admin ou criando um novo arquivo de tema diretamente no código-fonte.

O método da interface Admin é o mais simples, pois não requer acesso a arquivos do servidor nem recompilação de ativos. Você cola regras CSS em uma caixa de texto, e o Mastodon as injeta em todas as páginas. O método do código-fonte é mais poderoso, pois permite definir paletas de cores e variáveis de layout totalmente novas. Ambos os métodos exigem que você entenda os seletores CSS usados pelo Mastodon.

Antes de começar, certifique-se de ter acesso de administrador à sua instância Mastodon. Você também precisa de um conhecimento básico de sintaxe CSS. Se planeja modificar arquivos de código-fonte, precisa de acesso SSH ao servidor e familiaridade com a linha de comando.

Passos para aplicar CSS personalizado através do painel Admin

Este método funciona para qualquer instância Mastodon rodando versão 3.0 ou superior. Nenhuma edição de arquivo ou reinicialização do servidor é necessária.

1. Faça login como administrador
   Use uma conta que tenha o papel de Admin. Se você controla a instância, sua conta provavelmente é a primeira criada e tem permissões totais.
2. Abra o menu Administração
   Clique no ícone de hambúrguer no canto superior esquerdo da interface web do Mastodon. Selecione Preferências no menu. Na tela de Preferências, clique em Administração na barra lateral esquerda.
3. Vá para Configurações do Servidor > Aparência
   Em Administração, clique em Configurações do Servidor. Em seguida, clique na aba Aparência. Esta página contém campos para título do site, descrição, logotipo e CSS personalizado.
4. Cole seu código CSS personalizado
   Encontre a área de texto rotulada como CSS personalizado. Cole suas regras CSS aqui. Por exemplo, para alterar a cor de fundo da coluna principal, você pode usar:
   body { background-color: #f0f0f0; }
   Você pode adicionar quantas regras quiser, mas mantenha o tamanho total abaixo de 100 KB.
5. Salve as alterações
   Clique no botão Salvar alterações na parte inferior da página Aparência. O novo CSS entra em vigor imediatamente para todos os usuários. Atualize seu navegador para ver as alterações.

Passos para criar um novo tema no código-fonte

Este método é para administradores que desejam oferecer vários temas aos seus usuários. Requer acesso direto ao diretório de instalação do Mastodon no servidor.

1. Conecte-se via SSH ao seu servidor Mastodon
   Abra um terminal e conecte-se ao servidor: ssh usuario@ip-do-servidor. Navegue até o diretório do Mastodon, geralmente /home/mastodon/live.
2. Crie um novo arquivo de tema
   Vá para app/javascript/styles/mastodon. Copie o arquivo de tema existente mastodon-light.scss e renomeie-o, por exemplo, meu-tema-personalizado.scss. Abra o novo arquivo em um editor de texto como nano ou vim.
3. Edite as variáveis de cor
   No topo do arquivo SCSS, você encontrará variáveis como $ui-base-color, $primary-color e $secondary-color. Altere esses valores para suas cores preferidas. Por exemplo:
   $primary-color: #ff6600;
   Salve o arquivo após fazer as alterações.
4. Registre o tema na aplicação
   Abra app/lib/theme.rb ou config/themes.yml dependendo da sua versão do Mastodon. Adicione uma nova entrada para seu tema. Por exemplo:
   meu_tema_personalizado: Meu Tema Personalizado
   Salve o arquivo.
5. Recompile os ativos
   Execute o seguinte comando no diretório do Mastodon:
   RAILS_ENV=production bundle exec rails assets:precompile
   Isso compila os arquivos SCSS em CSS. O processo pode levar alguns minutos.
6. Reinicie os serviços do Mastodon
   Execute systemctl restart mastodon-web e systemctl restart mastodon-sidekiq para aplicar o novo tema. Os usuários agora podem selecionar seu tema em Preferências > Aparência > Tema.

Erros comuns e o que evitar

Regras CSS não aplicando após salvar no painel Admin

A causa mais comum é um erro de sintaxe CSS. Faltando ponto e vírgula, colchetes não fechados ou valores de propriedade inválidos podem quebrar todo o bloco. Use uma ferramenta de validação CSS antes de colar. Além disso, verifique se seus seletores correspondem à estrutura HTML do Mastodon. Use as ferramentas de desenvolvedor do seu navegador (F12) para inspecionar elementos e encontrar os nomes de classe ou ID corretos.

Tema não aparecendo nas preferências do usuário após alterações no código-fonte

Isso geralmente acontece quando o tema não é registrado corretamente no arquivo de configuração. Verifique se a chave em theme.rb ou themes.yml corresponde exatamente ao nome do arquivo, sem a extensão .scss. Além disso, certifique-se de ter recompilado os ativos e reiniciado o serviço web. Verifique os logs do servidor em busca de erros de compilação.

CSS personalizado afetando apenas a visualização do admin

Alguns seletores CSS são específicos da interface de administração. Para estilizar páginas públicas, use seletores que visam o layout público, como .public-layout ou .landing-page. Teste seu CSS enquanto desconectado ou usando uma janela anônima para ver a experiência pública.

CSS do painel Admin vs Tema do código-fonte: Comparação

Item	CSS do painel Admin	Tema do código-fonte
Dificuldade de configuração	Baixa: colar e salvar	Alta: edição de arquivos e recompilação de ativos
Alterações entram em vigor	Imediatamente após salvar	Após recompilação de ativos e reinicialização do serviço
Selecionável pelo usuário	Não: aplica-se a todos os usuários globalmente	Sim: usuários escolhem nas Preferências
Requer acesso ao servidor	Não	Sim: SSH e permissões de arquivo
Escopo do CSS	Apenas substituições; limitado pela especificidade	Controle total de variáveis e layout

Use o método do painel Admin para ajustes rápidos e branding. Use o método do código-fonte quando precisar oferecer vários temas ou personalizar profundamente o design.