Guias

Seu próprio HTML

Use a shell da página padrão, acrescente a ela, substitua partes ou escreva o documento inteiro.

Cada rota decide o próprio HTML. A maioria das rotas usa a shell da página padrão, [#html#], e a preenche com seu próprio markup. Quando uma página precisa de mais controle, você pode acrescentar à shell, substituir partes dela ou escrever o documento inteiro.

A shell padrão

Uma rota que termina com [#html#] ganha um documento completo:

  • o <head> com o título, a meta description, o endereço canônico, as tags de compartilhamento e os favicons,
  • a folha de estilo e os scripts do projeto,
  • os header.tpl, main.tpl e footer.tpl da pasta da rota,
  • para editores autenticados: edição na página, as ações da página e a barra do Nimbly,
  • o chat da equipe para usuários com acesso, e o link de armadilha para bots.

A shell é HTML simples em volta dos seus templates. Ela não acrescenta markup nem classes ao seu conteúdo além de <header>, <main> e <footer>.

Variáveis da página

Defina-as antes de [#html#]:

[#set page-title="[#project.title#]"#]
[#set page-description="Wayfinding for a working port."#]
[#set og-image=[#project.cover#]#]
[#set og-type=article#]
[#set body-classes="bg-stone-50 text-stone-900"#]
[#html#]
Variável Efeito
page-title O <title> e o título de compartilhamento
page-description A meta description; senão, a descrição do site
og-image, og-type A imagem de compartilhamento (um UUID de mídia, um caminho ou uma URL) e o tipo
page-canonical-url O endereço canônico, quando difere do pedido
body-classes Classes no <body>
head Markup extra no final do <head>
page-actions off esconde as ações da página para editores nesta página

Acrescente à shell

Carregue uma fonte, uma folha de estilo ou uma biblioteca numa página com head:

[#set head="<link rel='stylesheet' href='https://unpkg.com/leaflet@1.9.4/dist/leaflet.css'>"#]
[#html#]

Coloque o script próprio da página em index.js, ao lado do index.tpl; a shell o carrega só nessa rota. Para scripts que vários templates de uma página podem pedir, [#collect-script path#] acrescenta um script uma única vez, no final da página.

Substitua parte da shell para o site inteiro

A shell é feita de pequenos templates em core/tpl/html/: meta.tpl, fonts.tpl, stylesheets.tpl, scripts.tpl, favicon.tpl e outros. Um arquivo com o mesmo nome em ext/tpl/html/ substitui um deles e mantém o resto. Por exemplo, ext/tpl/html/fonts.tpl define as fontes do site, e ext/tpl/html/stylesheets.tpl pode acrescentar uma folha de estilo ao lado da padrão:

<link rel="stylesheet" href="[#base-url#]/app.css?v=[#app-modified#]">
<link rel="stylesheet" href="[#base-url#]/brand/brand.css">

O admin usa a mesma shell. Mantenha app.css e app.js no que você substituir, senão o admin e a edição na página perdem seus estilos e comportamento.

Para mudar a estrutura do próprio documento, copie core/tpl/html/index.tpl para ext/tpl/html/index.tpl e edite-o. As partes continuam vindo do core. Sua cópia deixa de acompanhar as atualizações da shell no core, então prefira substituir uma parte quando isso bastar.

Escreva o documento inteiro

Uma rota não precisa usar a shell. O index.tpl dela pode ser um documento completo:

<!doctype html>
<html lang="[#detect-language#]">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Annual report 2026</title>
  <link rel="stylesheet" href="[#base-url#]/report/report.css">
</head>
<body>
  [#data chapters sort=sort_order|numeric|asc#]
  [#repeat data.chapters tpl=card-chapter#]
  <script type="module" src="[#base-url#]/report/report.js"></script>
</body>
</html>

Shortcodes, dados, templates e permissões funcionam exatamente como em qualquer outra página. A rota abre mão do que a shell oferece: as meta tags, os assets padrão, a edição na página, as ações da página, o chat da equipe e o link de armadilha para bots. Acrescente de volta o que precisar, por exemplo [#bot-tripwire-link#] antes de </body>.

Use isso para uma landing page com design system próprio, um widget incorporado, um layout de impressão, uma single-page application ou uma página para um quiosque.

Leia a seguir

Ver esta página em Markdown