O que este blog consegue renderizar

Uma referência para o meu eu futuro. Tudo abaixo foi verificado no código do tema, não deduzido da documentação. Cada seção mostra a marcação e o que ela produz.

Callouts

Sintaxe de alertas do GitHub / Obsidian. Cinco tipos: NOTE, TIP, IMPORTANT, WARNING, CAUTION. Use + Título para um cabeçalho próprio.

> [!NOTE]
> Plain note.

> [!WARNING] Cuidado com este
> Um aviso com título personalizado.

Existe também um shortcode {{< callout >}}, mas o tema o marca como deprecated em favor da sintaxe acima. Não usar.

Mermaid

Bloco de código com mermaid como linguagem. O script só carrega em páginas que realmente contêm um diagrama.

```mermaid
sequenceDiagram
    Browser->>Pages: GET /en/blog/
    Pages-->>Browser: static HTML
    Browser->>Remark42: GET /api/v1/find
```

Fluxogramas também funcionam:

Markmap

Mapas mentais a partir de uma lista aninhada. Aceita o atributo height.

```markmap {height="300px"}
- Root
  - Branch
    - Leaf
```

- Backend
  - Services
    - APIs
    - Event-driven
  - Data
    - PostgreSQL
    - MongoDB
- Infrastructure
  - AWS
    - CDK
    - CloudFormation
  - Azure
    - Terraform
- Practice
  - CI/CD
  - Observability
  - Incident response

Math

KaTeX. Carrega quando a página tem math: true no front matter, um shortcode math, ou a flag global do site. Inline com $...$, bloco com $$...$$.

Inline: $O(n \log n)$

$$
p_{99} = \inf\{x : F(x) \ge 0.99\}
$$

Inline: $O(n \log n)$ é o limite.

Código

Blocos de código padrão, destacados pelo Chroma embutido no Hugo. Números de linha vêm desligados no site, mas podem ser ligados por bloco.

```python {linenos=true, hl_lines=[2]}
def charge(rate_kw: float) -> float:
    return min(rate_kw, MAX_KW)
```

1def charge(rate_kw: float) -> float:
2    return min(rate_kw, MAX_KW)  # clamp to the connector limit

Passos

Envolve cabeçalhos ###. Cada um vira um passo numerado.

{{< steps >}}
### Primeira coisa
Faça isto.
### Segunda coisa
Depois isto.
{{< /steps >}}

Spoilers

{{< spoiler text="Clique para expandir" >}}
Conteúdo escondido.
{{< /spoiler >}}

Botões

{{< button url="/pt/about/" >}}Sobre mim{{< /button >}}

Charts

Plotly. Aponte data para um arquivo JSON na pasta da página, sem a extensão. Aqui o demo-chart.json está ao lado deste index.md.

{{< chart data="demo-chart" >}}

Tabelas CSV

Mesma ideia: um .csv na pasta da página. Atenção: o parâmetro é path, não src. A documentação dentro do próprio shortcode diz src, mas o código lê .Get "path". Usar src quebra o build com erro de ponteiro nulo.

{{< table path="demo-table.csv" caption="Latência por serviço" >}}

Tabelas Markdown normais também funcionam:

Imagens

Markdown puro. O render hook procura primeiro na pasta da página, depois em assets/media/, e gera um srcset responsivo com vários tamanhos.

![Texto alternativo](authors/me.webp)

Vídeo e áudio

{{< video src="clip.mp4" controls="yes" >}}
{{< audio src="episode.mp3" >}}

Ambos procuram na pasta da página, depois em assets/media/, depois numa URL remota.

Ícones

{{< icon name="brands/github" >}} no meio de uma frase.

no meio de uma frase.

Notebooks Jupyter

{{< notebook path="analysis.ipynb" >}}

Renderiza um .ipynb inline, útil para posts com muitos dados.

Includes

{{< include "snippets/shared-warning.md" >}}

Inclui outro arquivo Markdown, com caminho relativo a content/.

O que não é suportado

PlantUML. Não existe render hook nem script de PlantUML em lugar nenhum deste tema. Verifiquei os layouts e o bundle JS. Opções, se eu precisar:

1. Usar Mermaid. Cobre sequência, fluxograma, classe, estado, ER e Gantt, que é a maior parte do que se usa PlantUML para fazer.
2. Renderizar o .puml para SVG offline, commitar o SVG e embutir como imagem normal. Sem dependência em tempo de build, sem servidor externo.

Um render hook de PlantUML teriam umas vinte linhas em layouts/_markup/render-codeblock-plantuml.html, mas precisaria chamar um servidor de renderização em tempo de build, por isso prefiro não ter.

Front matter que importa

---
title: "Título do post"
summary: "Aparece nas listagens e na meta description."
date: 2026-08-08
translationKey: alguma-chave # liga as versões pt/en/ja
authors: [me]
tags: [meta, markdown]
math: true                   # carrega KaTeX nesta página
commentable: true            # já herdado de blog/_index.md
draft: false
---

translationKey é o que mais importa: é ele que faz o seletor de idioma pular para o mesmo artigo em vez de voltar para a home.