Esquema de Quadro Kanban Fancy

Uma especificação autocontida para o formato de quadro kanban baseado em markdown. Qualquer aplicativo que leia e escreva arquivos seguindo este esquema produzirá quadros compatíveis.

Visão Geral

Cada quadro reside dentro de um bloco de código com o identificador fancy-kanban. Isso significa:

Um quadro pode ser incorporado em qualquer lugar em uma nota, junto com prosa, links e outros conteúdos
Uma nota pode conter zero, um ou vários quadros
Um arquivo composto por um único bloco de quadro é um arquivo de quadro independente
Sem o plugin instalado, o bloco é renderizado como um bloco de código sem estilo — o texto bruto permanece totalmente legível

O bloco contém duas seções separadas por ---:

Uma seção de configuração (semelhante a YAML) definindo campos, fluxo de trabalho e opções de visualização
Uma tabela markdown contendo as linhas de dados

Exemplo Completo

```fancy-kanban
---
title: Meu Quadro
fields:
  - name: titulo,       type: Text,     label: Título
  - name: status,      type: Select,   options: inbox|fazendo|feito, label: Status, default: inbox
  - name: responsavel, type: Text,     label: Responsável
  - name: data_inicio,  type: Date,     label: Data de Início
  - name: notas,       type: Textarea, label: Notas
  - name: esforco,      type: Number,   label: Esforço
  - name: docs,        type: Link,     label: Documentos
  - name: equipe,      type: Select,   options: frontend|backend, label: Equipe
card_fields: responsavel, esforco
lanes: equipe
workflow: inbox→fazendo, inbox→feito, fazendo→feito, fazendo→inbox, feito→fazendo, feito→inbox
---

| _id    | Título        | Status | Responsável | Data de Início | Notas                      | Esforço | Documentos            | Equipe   |
|--------|----------------|--------|-------------|----------------|----------------------------|---------|-----------------------|----------|
| x7k2a1 | Corrigir bug de login | inbox  | Alice       | 2026-01-15     | Precisa de investigação     | 3       |                       | backend  |
| m3p9b2 | Refatorar auth  | fazendo  | Bob         |                | Conteúdo multi-linha\<br\>aqui | 5       | design.md             | backend  |
| q1r4c3 | Configurar CI   | feito   |             | 2026-01-01     |                            | 1       | setup.md\|guide.md    | frontend |
```

Estrutura do Bloco

O bloco de código contém exatamente duas seções divididas por uma linha ---:

```fancy-kanban
---
{config}
---
{tabela markdown}


Tudo antes do primeiro `---` é ignorado (reservado para uso futuro). Tudo entre as duas linhas `---` é a configuração. Tudo após o segundo `---` é a tabela.

## Seção de Configuração

Pares chave-valor no estilo YAML. Analisados linha por linha.

### Chaves

| Chave | Obrigatório | Padrão | Descrição |
|-------|-------------|--------|-----------|
| `title` | sim | — | Nome legível do quadro |
| `fields` | sim | — | Lista de definições de campo (veja abaixo) |
| `version` | não | `1` | Versão do formato escrita pelo plugin; quadros com versão superior à suportada pelo plugin atual abrem em modo somente leitura |
| `workflow` | não | todas as transições permitidas | Pares `de→para` separados por vírgula |
| `lanes` | não | nenhum | Nome do campo a ser usado como dimensão de agrupamento de raias |
| `card_title` | não | detecção automática | Nome do campo a ser usado como título do cartão; defina como string vazia para não mostrar título |
| `card_fields` | não | nenhum | Lista ordenada separada por vírgulas de campos secundários a serem exibidos abaixo do título do cartão |
| `card_labels` | não | `true` | Defina como `false` para ocultar o prefixo do rótulo em campos secundários do cartão |
| `card_limit` | não | `0` (sem limite) | Número máximo de cartões exibidos por coluna; cartões além deste limite são ocultados atrás de um botão "Mostrar mais" |

### `card_title`

```yaml
card_title: resumo

Controla qual campo é renderizado como título do cartão:

Ausente (padrão): o primeiro campo que não seja _id nem coluna é usado automaticamente
Definido como um nome de campo: o valor desse campo aparece como título
Definido como string vazia (card_title: ): nenhum título é exibido; o cartão mostra apenas campos secundários

`card_fields`

card_fields: prioridade, prazo, documentos

Uma lista ordenada, separada por vírgulas, de nomes de campos secundários a serem exibidos abaixo do título do cartão. Eles aparecem como linhas rotuladas abaixo do título.

Comportamento padrão: quando card_fields está ausente, o cartão mostra apenas o campo de título. Quadros existentes sem a chave card_fields não são afetados.

Nomes desconhecidos: nomes de campo que não correspondem a nenhum campo definido são ignorados silenciosamente durante a renderização. Remover um campo de fields: automaticamente o oculta da face do cartão sem erro de análise.

Campos de Link: quando um campo Link é incluído em card_fields, seus itens são renderizados como uma lista horizontal de links clicáveis na face do cartão. Caminhos de vault abrem em uma nova aba; URIs externos abrem no navegador.

`card_labels`

card_labels: false

Quando definido como false, o prefixo do rótulo é omitido das linhas de campo secundário na face do cartão — apenas o valor é exibido. O padrão é true (rótulos visíveis). A chave só é escrita na configuração quando seu valor é false.

`card_limit`

card_limit: 5

Quando definido como um inteiro positivo, cada coluna mostra no máximo esse número de cartões. Cartões além do limite são ocultados e um botão Mostrar mais (N) aparece na parte inferior da coluna. Clicar nele revela todos os cartões restantes sem recarregar o quadro. Definir card_limit: 0 ou omitir a chave desativa a limitação completamente.

Isso é particularmente útil para quadros onde a coluna feito acumula muitos cartões concluídos ao longo do tempo — os cartões adicionados mais recentemente permanecem visíveis de relance, enquanto o histórico mais antigo é recolhido.

`lanes`

Quando definido para um nome de campo (deve ser um campo Select), o quadro é renderizado como uma matriz:

Colunas — orientadas pela ordem options do campo status
Linhas de raias — orientadas pela ordem options do campo lanes

Cartões sem valor para o campo de raias aparecem em uma pseudo-raia Não atribuído na parte inferior. Alterar lanes é apenas uma mudança de configuração de visualização — nenhum dado de linha é afetado.

Definições de Campo

Cada entrada na lista fields é um conjunto de pares chave: valor separados por vírgula em uma única linha, prefixado com - :

fields:
  - name: titulo, type: Text, label: Título
  - name: status, type: Select, options: inbox|fazendo|feito, label: Status, default: inbox

Convenção de ordenação de campos: liste title primeiro, depois status, depois os campos adicionais. A ordem das colunas na tabela na seção de dados espelha a ordem de definição do campo, e o título do cartão detectado automaticamente resolve para o primeiro campo que não seja _id nem coluna — portanto, colocar title primeiro garante uma resolução previsível do título sem a necessidade de uma chave explícita card_title.

Propriedades do Campo

Propriedade	Obrigatório	Descrição
`name`	sim	Identificador interno. Minúsculas, sublinhados para espaços.
`type`	sim	Um de: `Text`, `Textarea`, `Date`, `Number`, `Select`, `Link`
`label`	sim	Cabeçalho de coluna legível. Deve corresponder exatamente ao cabeçalho da tabela markdown.
`options`	Apenas Select	Lista separada por pipe (`
`colors`	Select, opcional	Pares `nome=hex` separados por pipe atribuindo uma cor de fundo a cada opção (exemplo: `Alto=#e74c3c
`default`	não	Valor padrão para novos cartões

Tipos de Campo

Tipo	Formato de Armazenamento	Descrição
`Text`	String simples	Texto de linha única
`Textarea`	String com `<br>` para quebras de linha	Texto multilinha
`Date`	`YYYY-MM-DD`	Data de calendário
`Number`	String de inteiro ou decimal	Valor numérico
`Select`	Um dos valores `options`	Escolha restrita; opções podem carregar cores hex via a propriedade `colors`
`Link`	Lista de caminhos ou URIs separados por `<br>`	Caminhos relativos à raiz do vault (`notes/doc.pdf`) ou URIs externos (`https://…`, `ftp://…`, `mailto:…`)

Nomes de Campo Especiais

Nome	Função
`title`	Campo de exibição principal. Deve ser listado primeiro em `fields:`. Usado como título do cartão detectado automaticamente quando `card_title` não está definido.
`status`	Obrigatório. Campo de coluna Kanban. Deve ser `type: Select`. Os cartões são agrupados em colunas por este valor. A ordem das colunas segue a ordem `options`.

Todos os outros campos são secundários — exibidos como metadados do cartão quando listados em card_fields.

Identidade do Item

Cada cartão tem um ID oculto estável armazenado em uma coluna _id na tabela markdown. A IU nunca exibe esta coluna.

Gerado na criação do cartão: string alfanumérica curta aleatória (exemplo: 8 caracteres: x7k2a1b3)
Preservado em todas as idas e vindas de serialização
Sobrevive a reordenação, arrastar e soltar e renomeação de campos
Usado internamente para todas as operações do cartão (mover, editar, excluir)

Como a identidade é baseada em ID e não derivada do conteúdo, renomear o título de um cartão não tem efeito sobre sua identidade.

Fluxo de Trabalho

Define quais transições de status são permitidas na IU:

workflow: inbox→fazendo, inbox→feito, fazendo→feito, fazendo→inbox, feito→fazendo, feito→inbox

Lista separada por vírgulas de pares de→para (seta: →, U+2192)
Se workflow for omitido, todas as transições entre opções de status são permitidas
Usado para restringir as escolhas da IU (exemplo: um menu "Mover para" mostra apenas destinos válidos)
Edições manuais na tabela bruta ignoram a validação do fluxo de trabalho por natureza de serem texto simples

Modelos de Quadro

Ao criar um novo quadro, um conjunto de modelos predefinidos fornece conjuntos comuns de opções de status. Os modelos apenas preenchem previamente as opções do campo status e o workflow — todos os outros campos são adicionados pelo usuário.

Modelo	Opções de status	Fluxo de trabalho padrão
Básico	`inbox \| fazendo \| feito`	Todas as transições
Software	`backlog \| a fazer \| em andamento \| revisão \| feito`	Avançar + um passo atrás
Conteúdo	`ideia \| rascunho \| revisão \| publicado`	Apenas avançar
Projeto	`planejamento \| ativo \| bloqueado \| concluído`	Todas exceto → planejamento
Personalizado	Definido pelo usuário	Definido pelo usuário

Selecionar Personalizado abre um editor de formulário livre para opções de status e transições de fluxo de trabalho.

Tabela Markdown

A tabela aparece imediatamente após o --- de fechamento da seção de configuração.

Estrutura

| _id    | Cabeçalho1 | Cabeçalho2 |
|--------|------------|------------|
| abc123 | valor      | valor      |

Linha de cabeçalho — a primeira coluna é sempre _id; as colunas restantes são rótulos de campo na ordem de definição do esquema
Linha separadora — separador de tabela markdown padrão
Linhas de dados — uma linha por cartão; a célula _id contém o ID estável do cartão

Regras

A ordem das colunas na tabela deve corresponder à ordem de definição do campo (após _id)
Células vazias são válidas (valor do campo = string vazia)
A ordem das linhas dentro de um grupo de status é a ordem de exibição
Uma tabela vazia (cabeçalho + separador, sem linhas de dados) é válida
A coluna _id é sempre a primeira e nunca é exibida no quadro renderizado

Escape

Caractere no valor	Escapado como
`\|` (pipe)	`\|` (barra invertida + pipe)
Nova linha	`<br>`
Retorno de carro	`<br>`

Ao ler: \| → |, <br> → nova linha. Ao escrever: | → \|, qualquer nova linha → <br>.

Algoritmo de Análise

Extrair a string bruta entre as cercas de abertura e fechamento do bloco fancy-kanban
Dividir na primeira linha --- para localizar o início da seção de configuração
Dividir na segunda linha --- para separar a configuração da tabela
Analisar a configuração linha por linha: extrair title, version, fields, workflow, lanes, card_title, card_fields, card_labels, card_limit
Para fields, coletar linhas começando com - e analisar cada uma como pares chave: valor separados por vírgula; colors é decodificado como tokens nome=hex separados por pipe
Encontrar linhas de tabela no corpo (linhas começando com |)
A primeira linha da tabela é a linha de cabeçalho — extrair rótulos de coluna; _id é sempre o primeiro
Mapear os rótulos de cabeçalho restantes para nomes de campo via pesquisa de rótulo sem distinção entre maiúsculas e minúsculas
Analisar cada linha de dados: dividir em | não escapados, aparar células, desescapar \| e <br>
A primeira célula de cada linha de dados é o _id do cartão
Agrupar cartões pelo valor do campo status, semeando grupos na ordem options

Reconciliação de esquema (aplicada após a análise):

Campos presentes no esquema, mas ausentes dos dados de um cartão: preencher com o default do campo (ou string vazia)
Campos presentes nos dados do cartão, mas removidos do esquema: preservar como dados ocultos órfãos (não excluídos)

Algoritmo de Escrita

Reconstruir a seção de configuração a partir do esquema atual (preservar a formatação original quando possível)
Gerar linha de cabeçalho: _id primeiro, depois rótulos de campo na ordem de definição do esquema
Gerar linha separadora
Gerar uma linha de dados por cartão: _id primeiro, depois valores de campo na ordem do esquema, com pipes e novas linhas escapados
Gerar um novo _id de cartão usando uma string alfanumérica aleatória se o cartão não tiver um ID existente
Reconstruir o bloco completo: cerca de abertura, configuração, ---, linha em branco, tabela, cerca de fechamento

Princípio de write-back: apenas o intervalo de texto do bloco afetado é corrigido no arquivo de origem — o conteúdo circundante nunca é reescrito.

Quadro Mínimo Viável

```fancy-kanban
---
title: Meu Quadro
fields:
  - name: titulo, type: Text, label: Título
  - name: status, type: Select, options: inbox|fazendo|feito, label: Status, default: inbox
workflow: inbox→fazendo, inbox→feito, fazendo→feito, fazendo→inbox, feito→fazendo, feito→inbox
---

| _id | Título | Status |
|-----|-------|--------|


## Notas de Compatibilidade

- Sem o plugin, o bloco é renderizado como um bloco de código simples — todos os dados ainda estão visíveis como texto simples
- A tabela markdown dentro do bloco é markdown válido e legível em qualquer editor de texto
- A seção de configuração segue as convenções YAML familiares aos geradores de sites estáticos e aplicativos de anotações
- Remover o plugin deixa todos os dados intactos e recuperáveis

## Funcionalidades Descontinuadas

Consulte [docs/deprecations.md](deprecations.md) para obter a lista de funcionalidades descontinuadas e notas de migração.

robertoallende/fancy-kanban

O que é fancy-kanban?

Perguntar na sua IA favorita

Documentação