Configuração

config.yaml fica na raiz do projeto e é lido uma vez por processo. Valores string podem interpolar variáveis de ambiente com ${NOME_DA_VARIAVEL}; uma variável ausente interrompe o carregamento com o caminho da configuração. As chaves conhecidas são validadas antes do build, enquanto chaves adicionais são preservadas para extensões.

Use php blog config:lint para validar o arquivo sem renderizar o site.

Chave	Tipo esperado	Default	Consumidores
`server.port`	inteiro/string de porta	`8000`	`dev`, `serve`
`site.domain`	string de host	`localhost`	canonical, social, JSON-LD, sitemap, robots, llms, capas
`site.basePath`	string	`""`	links, assets e todas as URLs públicas
`site.name`	string	`Blog Engine`	título, Open Graph, JSON-LD
`site.locale`	string	`pt_BR`	`og:locale`
`site.themeColor`	string	`#ffffff`	`theme-color`
`content.dates.policy`	`mtime`, `fail` ou `explicit`	`mtime`	datas de Collections, `lastModified` e sitemap sem histórico Git
`content.reading.wordsPerMinute`	inteiro positivo	`250`	tempo de leitura automático de MDX e seus summaries
`site.twitter.site`	string	`@blogblade`	Twitter Card
`site.twitter.creator`	string	`@barboza`	Twitter Card
`site.fonts.families`	mapa de famílias	ausente	cache, `@font-face` e assets locais de fontes
`site.fonts.google.stylesheets`	lista de URLs	legado	compatibilidade com a configuração antiga de Google Fonts
`feature.remixicon`	booleano	`false`	publicação da webfont do Remix Icon
`feature.pagefind`	booleano	`false`	índice estático e modal nativo de busca
`feature.revealjs`	booleano	`false`	publicação dos assets Reveal.js e apresentações MDX
`feature.mermaid`	booleano	`false`	conversão de fences Mermaid para SVG no build
`feature.shiki`	booleano	`false`	syntax highlighting Shiki de fences no build
`mermaid.theme`	string	`neutral`	tema base do Mermaid
`mermaid.securityLevel`	string	`strict`	nível de segurança do Mermaid
`mermaid.background`	string	`transparent`	cor do canvas e dos rótulos Mermaid
`mermaid.fontFamily`	string	ausente	família tipográfica do Mermaid
`mermaid.fontSize`	inteiro positivo	ausente	tamanho base da tipografia Mermaid
`mermaid.themeVariables`	mapa	ausente	variáveis do tema Mermaid
`mermaid.options`	mapa	ausente	opções avançadas por tipo de diagrama
`shiki.theme`	string	`gruvbox-dark-medium`	tema Shiki aplicado aos fences conhecidos
`llms.about`	string ou null	ausente	prosa do `llms.txt`
`llms.external_resources`	lista	lista vazia	links externos do `llms.txt`

O gerador de llms usa localhost como nome próprio quando site.name está ausente, diferentemente do default Blog Engine usado pelo título.

As features globais ficam no mapa raiz feature. As chaves atualmente suportadas são remixicon, pagefind, revealjs, mermaid e shiki; cada valor deve ser um booleano. Chaves desconhecidas ou valores de outro tipo são rejeitados por config:lint.

As opções Mermaid ficam no mapa raiz mermaid. Além das opções curadas, o mapa mermaid.options é repassado ao Mermaid para configurações avançadas, como flowchart.curve ou opções de sequence. startOnLoad e deterministicIds são protegidos pelo engine para manter a saída estática e os IDs namespaced.

O fundo do canvas e dos rótulos usa mermaid.background. O padrão é transparent; também são aceitos nomes de cores CSS e cores hexadecimais, como #f5f5f5.

Para ajustes visuais que não pertencem ao tema Mermaid, crie o arquivo opcional Content/assets/css/mermaid.css. Ele é compilado e publicado depois do CSS principal, podendo estilizar .mermaid-diagram e os elementos internos do SVG. Esse arquivo não deve fixar o fundo dos rótulos: o valor de mermaid.background é aplicado pelo renderer e pode ser substituído conforme a configuração do site.

Estrutura completa:

server:
  port: 8000
site:
  domain: example.com
  basePath: ""
  name: Meu site
  locale: pt_BR
  themeColor: "#4C1D95"
content:
  dates:
    # mtime mantém compatibilidade; fail exige Git; explicit exige `date` no front matter.
    policy: mtime
  reading:
    wordsPerMinute: 250
  twitter:
    site: "@meusite"
    creator: "@autor"
  fonts:
    families:
      mono:
        provider: google
        family: JetBrains Mono
        weights: [400, 500, 600]
        styles: [normal]
        display: swap
      brand:
        provider: local
        family: Space Mono
        files:
          - path: Content/assets/fonts/space-mono-700.woff2
            weight: 700
            style: normal
feature:
  remixicon: true
  pagefind: true
  revealjs: true
  mermaid: true
  shiki: false
shiki:
  theme: gruvbox-dark-medium
llms:
  about: "Descrição adicional."
  external_resources:
    - title: Repositório
      url: https://example.com/repo
      description: Código-fonte.

site.domain deve conter somente o host, sem protocolo. A engine acrescenta https://. site.basePath fica vazio quando o site ocupa a raiz do host; em um GitHub Pages de projeto, use por exemplo /BlogBlade. O valor deve começar com /, não pode terminar em / nem conter segmentos vazios. Rotas públicas sempre terminam em /; assets mantêm o nome do arquivo. site.locale controla og:locale no formato configurado e o hreflang em formato BCP47 (pt_BR → pt-BR, por exemplo).

Cada família nova exige provider e family. Google aceita weights, styles (normal ou italic) e display; local aceita uma lista files, cada uma com path, weight e style. Pesos devem estar entre 1 e 1000 e display pode ser auto, block, swap, fallback ou optional. A engine rejeita famílias duplicadas, providers desconhecidos, arquivos fora de Content/assets/fonts/ e formatos diferentes de WOFF2.

O formato legado site.fonts.google.stylesheets continua funcionando durante a transição, mas a configuração nova e a legada não podem coexistir. Em ambos os casos, a engine combina as faces, materializa os WOFF2, publica somente referências locais e usa cache sem rede quando válido; consulte Assets para cache, atualização e saída.

feature.remixicon liga a publicação opt-in da webfont do Remix Icon. O padrão é false: nenhum arquivo é publicado e nenhum <link> é emitido. Quando true, o build exige node_modules/remixicon instalado; a ausência do pacote ou de alguma fonte referenciada aborta o build com um erro acionável. Valores não booleanos são rejeitados por config:lint.

feature.pagefind liga a busca estática opt-in. O padrão é false. Quando true, o build exige node_modules/.bin/pagefind, renderiza o modal Pagefind no cabeçalho e indexa o conteúdo de páginas normais em dist/pagefind/. Apresentações, covers e páginas de erro não recebem o marcador de indexação. O componente usa o caminho público completo, incluindo site.basePath, e o atalho padrão é mod+k. O servidor dev não publica esse bundle porque ele serve a aplicação dinâmica; valide a integração com build ou build-fast.

feature.revealjs liga a publicação opt-in de Reveal.js e habilita MDX com type: presentation. O padrão é false; sem essa chave, nenhum asset Reveal.js é publicado. Quando true, o build exige node_modules/reveal.js instalado e publica as entradas lógicas js/reveal.js e css/reveal.css. Se uma página presentation existir com o recurso desabilitado, o build falha informando que é necessário habilitar Reveal.js. Valores não booleanos são rejeitados por config:lint.

Essa feature controla a disponibilidade global do runtime; ela não configura transições ou controles por página. O guia Criar e personalizar apresentações documenta o layout, o manifest, a personalização atual e a proposta de uma futura configuração local.

feature.mermaid habilita a conversão de blocos fenced com identificador mermaid para SVG durante o build. O SVG é embutido no HTML final; nenhum runtime Mermaid ou CDN é publicado. O padrão é false. Quando true, o build exige node_modules/.bin/mmdc e Chromium disponíveis. Um diagrama inválido interrompe o build informando o arquivo e o número do diagrama.

feature.shiki habilita syntax highlighting para fences Markdown/MDX durante o build. O tema padrão é gruvbox-dark-medium e pode ser trocado em shiki.theme, por exemplo github-dark. Shiki devolve <pre><code> com os estilos inline do tema; nenhum JavaScript, CDN ou asset Shiki é publicado em dist/. Fences sem linguagem e linguagens que Shiki não reconhece mantêm o HTML CommonMark normal, sem interromper o build. O servidor dev não executa Shiki; confira o resultado destacado com build ou build-fast.

Se llms.about terminar em .md, ele é tratado como caminho absoluto ou relativo à raiz. O conteúdo do arquivo é usado quando ele existe; caso contrário, a string permanece literal. Cada item de external_resources usa title, url e description opcional.

Na imagem builder, o arquivo interno fornece defaults. Monte um override em /app/config.yaml:ro para o site do cliente.