Pular para o conteúdo
Navegar na documentação
Nesta página

Gerenciar assets

Core/Assets/main.css é a entrada Tailwind nativa da engine e não deve ser editada pelo projeto de conteúdo. CSS de usuário fica em Content/assets/css/; app.css é apenas um nome convencional e opcional, tratado como qualquer outro arquivo CSS. mermaid.css é a exceção reservada para customizações visuais dos diagramas Mermaid e, quando existe, é carregado automaticamente pelos layouts.

A convenção de publicação é:

Core/Assets/main.css         → CSS Tailwind nativo, gerado sempre
Content/assets/css/*.css     → entradas CSS independentes do usuário
Content/assets/js/**/*       → JavaScript publicado com hash
Content/public/**/*          → arquivos literais copiados para dist/

Para customizar Mermaid, use Content/assets/css/mermaid.css. O arquivo recebe hash no build, é exposto pelo manifest como css/mermaid.css e é incluído pelos layouts depois do CSS principal. A configuração de tema e opções do Mermaid continua em mermaid no config.yaml.

Busca Pagefind

A busca nativa é opt-in e indexa os HTML produzidos pelo build. Ligue-a em config.yaml:

feature:
  pagefind: true

O pipeline executa Pagefind depois de renderizar as páginas e publica o bundle em dist/pagefind/. O layout normal já inclui o modal no cabeçalho e o marcador data-pagefind-body; não é preciso manter um JSON ou endpoint. O componente é excluído de covers, apresentações e páginas de erro. O índice é estático e precisa ser enviado junto com dist/; site.basePath é aplicado automaticamente às URLs.

Customizar o visual do modal

O tema do modal fica no CSS do site, normalmente em Content/assets/css/app.css. O CSS oficial do Pagefind é carregado antes do CSS nativo e dos CSSs do projeto, então as variáveis abaixo podem reutilizar a paleta e as fontes da identidade visual:

:root {
    --pf-background: var(--color-pb-surface);
    --pf-text: var(--color-pb-ink);
    --pf-text-secondary: var(--color-pb-text-secondary);
    --pf-text-muted: var(--color-pb-text-secondary);
    --pf-border: var(--color-pb-line);
    --pf-border-focus: var(--color-pb-purple-500);
    --pf-outline-focus: var(--color-pb-purple-500);
    --pf-hover: color-mix(in srgb, var(--color-pb-purple-300) 18%, var(--color-pb-surface));
    --pf-mark: var(--color-pb-purple-900);
    --pf-font: var(--font-body);
    --pf-border-radius: 0px;
    --pf-modal-backdrop: rgb(23 18 31 / 0.72);
}

Os tokens mais úteis são --pf-background, --pf-border, --pf-border-focus, --pf-hover, --pf-mark, --pf-font, --pf-border-radius, --pf-modal-backdrop, --pf-modal-max-width, --pf-modal-max-height e --pf-modal-top. Eles afetam tanto o modal quanto os resultados, o campo de entrada, o trigger e as teclas de atalho.

Para ajustes que não têm um token — por exemplo, zerar o raio fixo do dialog ou usar Space Mono somente no trigger — use os elementos Pagefind e as classes pf-*:

pagefind-modal-trigger .pf-trigger-btn {
    border-color: var(--color-pb-line) !important;
    color: var(--color-pb-text-secondary) !important;
    font-family: var(--font-mono) !important;
    text-transform: uppercase;
}

pagefind-modal dialog.pf-modal {
    border: 1px solid var(--color-pb-ink) !important;
    border-radius: 0 !important;
}

pagefind-modal .pf-result-link:hover {
    color: var(--color-pb-purple-700) !important;
}

O !important nesses exemplos é intencional: o stylesheet distribuído pelo Pagefind usa seletores de alta especificidade para evitar que estilos genéricos do site quebrem os componentes. Use-o somente nos elementos que precisam vencer essa proteção; prefira os tokens para o restante.

Não edite dist/pagefind/pagefind-component-ui.css: esse arquivo é gerado novamente a cada build. Também não remova a folha do Pagefind nem a mova para depois do CSS de customização, pois a ordem atual é o que permite que os tokens do site prevaleçam. Mantenha o tamanho da fonte do input em pelo menos 16px para evitar zoom automático em iOS e preserve --pf-outline-focus para que o modal continue navegável por teclado. O layout mobile transforma o modal em uma tela inteira; teste overrides de dimensões dentro de @media(max-width: 640px).

Depois de alterar o tema, execute just build-fast e valide a saída estática com just serve. O build deve continuar publicando dist/pagefind/ junto com o CSS do site; o servidor dev não carrega o bundle estático.

Não é necessário registrar esses arquivos no config.yaml. O caminho das views deve ser resolvido pelo manifest $assets, para que o hash não fique codificado no template. O layout só inclui app.css quando esse arquivo existe; outros CSS devem ser referenciados explicitamente pelo layout ou componente.

Fontes são declaradas por família em site.fonts.families. O provider google recebe a família, pesos, estilos e display; o provider local recebe arquivos WOFF2 explícitos em Content/assets/fonts/:

site:
  fonts:
    families:
      inter:
        provider: google
        family: Inter
        weights: [400, 500, 600, 700]
        styles: [normal]
        display: swap
      brand:
        provider: local
        family: Minha Marca
        display: swap
        files:
          - path: Content/assets/fonts/minha-marca-700.woff2
            weight: 700
            style: normal

Os dois providers produzem o mesmo resultado: @font-face local, CSS com hash e WOFF2 com hash. O cache em storage/framework/fonts/ pode ser reutilizado offline; --refresh-fonts força uma nova resolução. A configuração legada site.fonts.google.stylesheets continua aceita durante a migração, mas não pode aparecer junto com site.fonts.families.

Para usar o Remix Icon sem CDN, ligue feature.remixicon: true em config.yaml. O build lê node_modules/remixicon, valida as referências, publica a webfont e o CSS em um namespace local com nomes hashados e registra css/remixicon.css no manifest. No modo dev, o mesmo namespace usa um CSS estável.

Em covers sociais, o manifest também fica disponível. Como a cover é rasterizada fora do servidor normal, carregue o stylesheet pelo contexto da cover:

@if ($assets->has('css/remixicon.css'))
    <link rel="stylesheet" href="{{ $cover->asset($assets->path('css/remixicon.css')) }}">
@endif

<i class="ri-database-2-line" aria-hidden="true"></i>

$assets->has() torna o link condicional ao recurso habilitado e $assets->path() resolve o nome lógico para o CSS hashado no build. Nunca escreva dist/assets/remixicon/remixicon.<hash>.css no template. Durante o build, o renderer serve temporariamente os assets publicados por HTTP local; como o documento da cover é carregado por file://, esse servidor libera CORS para CSS, fontes e demais assets. Assim, as fontes relativas ao CSS continuam sendo resolvidas sem CDN. O helper $cover->asset() preserva site.basePath, inclusive quando a cover é gerada em CI ou em paralelo com outras covers.

O stylesheet local das fontes configuradas também fica disponível como $fontStylesheet; quando houver um valor, carregue-o com $cover->asset('/'.$fontStylesheet). A lista $fontPreloads contém os WOFF2 publicados e pode ser usada para emitir links de preload. Sem site.fonts.families ou a configuração legada equivalente, $fontStylesheet é null e $fontPreloads fica vazia.

Use as classes ri-* diretamente em Blade ou MDX:

<i class="ri-home-line" aria-hidden="true"></i>
<i class="ri-github-fill" aria-hidden="true"></i>
<i class="ri-settings-3-line ri-2x" aria-hidden="true"></i>

A convenção oficial é ri-{nome}-{estilo}, com as variantes -line e -fill. Use aria-hidden="true" quando o ícone for decorativo; para um controle cujo significado dependa apenas do ícone, forneça um nome acessível no controle.

Classes que aparecerem somente em MDX exigem um @source explícito na entrada CSS correspondente, como já acontece com qualquer outra classe Tailwind. O recurso é desligado por padrão; sites desativados não publicam nem referenciam nenhum asset do Remix Icon. Publicações entram no registro de colisões e não sobrescrevem arquivos de Content/public.

Garanta que cada entrada Tailwind examine os templates que contêm classes utilizadas. A entrada nativa inclui Content/Views/**/*.blade.php e Content/Pages/**/*.blade.php; se classes existirem somente em documentos MDX, acrescente uma fonte adequada com @source na entrada CSS correspondente.

As views MDX geradas ainda não existem quando o estágio de assets começa. Por isso, depender apenas do diretório de views geradas não inclui classes que aparecem somente no Markdown.

Mantenha estes três arquivos:

Content/assets/favicon.ico
Content/assets/icon.svg
Content/assets/apple-touch-icon.png

Se algum favicon estiver ausente, o build informa todos os ausentes e não copia nenhum. Arquivos fora de css/, js/ e dos favicons devem ser colocados em Content/public/ quando a intenção for publicá-los literalmente.

Consulte Assets para nomes e comportamento exatos e Saída gerada para o resultado do build.