Esquema del Tablero Fancy Kanban
Una especificación autocontenida para el formato de tablero kanban basado en Markdown. Cualquier aplicación que lea y escriba archivos siguiendo este esquema producirá tableros compatibles.
Vista general
Cada tablero reside dentro de un bloque de código delimitado con el identificador fancy-kanban. Esto significa:
- Un tablero puede incrustarse en cualquier lugar de una nota, junto con texto, enlaces y otro contenido.
- Una nota puede contener cero, uno o varios tableros.
- Un archivo que consiste en un solo bloque de tablero es un archivo de tablero independiente.
- Sin el plugin instalado, el bloque se renderiza como un bloque de código sin estilo; el texto sin formato sigue siendo completamente legible.
El bloque contiene dos secciones separadas por ---:
- Una sección de configuración (similar a YAML) que define campos, flujo de trabajo y opciones de vista.
- Una tabla Markdown que contiene las filas de datos.
Ejemplo completo
```fancy-kanban
---
title: Mi Tablero
fields:
- name: titulo, type: Text, label: Título
- name: estado, type: Select, options: pendiente|haciendo|hecho, label: Estado, default: pendiente
- name: responsable, type: Text, label: Responsable
- name: fecha_inicio, type: Date, label: Fecha de inicio
- name: notas, type: Textarea, label: Notas
- name: esfuerzo, type: Number, label: Esfuerzo
- name: docs, type: Link, label: Documentos
- name: equipo, type: Select, options: frontend|backend, label: Equipo
card_fields: responsable, esfuerzo
lanes: equipo
workflow: pendiente→haciendo, pendiente→hecho, haciendo→hecho, haciendo→pendiente, hecho→haciendo, hecho→pendiente
---
| _id | Título | Estado | Responsable | Fecha de inicio | Notas | Esfuerzo | Documentos | Equipo |
|--------|-----------------|------------|-------------|-----------------|-------------------------------|----------|----------------------|----------|
| x7k2a1 | Corregir error de inicio de sesión | pendiente | Alice | 2026-01-15 | Necesita investigación | 3 | | backend |
| m3p9b2 | Refactorizar autenticación | haciendo | Bob | | Contenido<br>multilínea aquí | 5 | design.md | backend |
| q1r4c3 | Configurar CI | hecho | | 2026-01-01 | | 1 | setup.md|guide.md | frontend |
```
Estructura del bloque
El bloque delimitado contiene exactamente dos secciones divididas por una línea ---:
```fancy-kanban
---
{config}
---
{tabla markdown}
Todo lo que está antes del primer `---` se ignora (reservado para uso futuro). Todo lo que está entre las dos líneas `---` es la configuración. Todo lo que está después del segundo `---` es la tabla.
## Sección de configuración
Pares clave-valor similares a YAML. Se analiza línea por línea.
### Claves
| Clave | Obligatorio | Valor por defecto | Descripción |
|-------|-------------|--------------------|-------------|
| `title` | sí | — | Nombre legible del tablero |
| `fields` | sí | — | Lista de definiciones de campo (ver más abajo) |
| `version` | no | `1` | Versión del formato escrita por el plugin; los tableros con una versión superior a la que soporta el plugin actual se abren en modo solo lectura |
| `workflow` | no | todas las transiciones permitidas | Pares `desde→hasta` separados por comas |
| `lanes` | no | ninguno | Nombre del campo a usar como dimensión de agrupación de carriles |
| `card_title` | no | detección automática | Nombre del campo a usar como encabezado de la tarjeta; establecer como cadena vacía para no mostrar encabezado |
| `card_fields` | no | ninguno | Lista ordenada separada por comas de campos secundarios para mostrar debajo del encabezado de la tarjeta |
| `card_labels` | no | `true` | Establecer en `false` para ocultar el prefijo de etiqueta en los campos secundarios de la tarjeta |
| `card_limit` | no | `0` (sin límite) | Número máximo de tarjetas mostradas por columna; las tarjetas que superan este límite se ocultan detrás de un botón "Mostrar más" |
### `card_title`
```yaml
card_title: resumen
Controla qué campo se renderiza como encabezado de la tarjeta:
- Ausente (por defecto): el primer campo que no sea
_idni de columna se usa automáticamente. - Establecido a un nombre de campo: el valor de ese campo aparece como encabezado.
- Establecido a cadena vacía (
card_title:): no se muestra ningún encabezado; la tarjeta muestra solo los campos secundarios.
card_fields
card_fields: prioridad, vencimiento, docs
Una lista ordenada separada por comas de nombres de campos secundarios para mostrar debajo del encabezado de la tarjeta. Aparecen como filas etiquetadas debajo del título.
Comportamiento por defecto: cuando card_fields está ausente, la tarjeta muestra solo el campo de encabezado. Los tableros existentes sin la clave card_fields no se ven afectados.
Nombres desconocidos: los nombres de campo que no coinciden con ningún campo definido se ignoran silenciosamente durante el renderizado. Eliminar un campo de fields: lo oculta automáticamente de la cara de la tarjeta sin error de análisis.
Campos de enlace: cuando un campo de tipo Link se incluye en card_fields, sus elementos se renderizan como una lista horizontal de enlaces en los que se puede hacer clic en la cara de la tarjeta. Las rutas de la bóveda se abren en una nueva pestaña; los URI externos se abren en el navegador.
card_labels
card_labels: false
Cuando se establece en false, el prefijo de etiqueta se omite de las filas de campos secundarios en la cara de la tarjeta; solo se muestra el valor. El valor por defecto es true (etiquetas visibles). La clave solo se escribe en la configuración cuando su valor es false.
card_limit
card_limit: 5
Cuando se establece en un entero positivo, cada columna muestra como máximo esa cantidad de tarjetas. Las tarjetas que superan el límite se ocultan y aparece un botón Mostrar más (N) en la parte inferior de la columna. Al hacer clic en él, se muestran todas las tarjetas restantes sin recargar el tablero. Establecer card_limit: 0 u omitir la clave desactiva el límite por completo.
Esto es particularmente útil para tableros donde la columna de hecho acumula muchas tarjetas completadas a lo largo del tiempo; las tarjetas añadidas más recientemente permanecen visibles de un vistazo, mientras que el historial anterior se colapsa para no estorbar.
lanes
Cuando se establece en un nombre de campo (debe ser un campo de tipo Select), el tablero se renderiza como una matriz:
- Columnas — impulsadas por el orden de
optionsdel campoestado - Filas de carril — impulsadas por el orden de
optionsdel campolanes
Las tarjetas sin valor para el campo de carril aparecen en un pseudo-carril Sin asignar en la parte inferior. Cambiar lanes es solo un cambio de configuración de vista; no se afectan los datos de las filas.
Definiciones de campo
Cada entrada en la lista fields es un conjunto de pares clave: valor separados por comas en una sola línea, con prefijo - :
fields:
- name: titulo, type: Text, label: Título
- name: estado, type: Select, options: pendiente|haciendo|hecho, label: Estado, default: pendiente
Convención de orden de campos: lista titulo primero, luego estado, luego los demás campos. El orden de las columnas en la tabla de datos refleja el orden de definición de los campos, y el encabezado de tarjeta detectado automáticamente se resuelve al primer campo que no sea _id ni de columna, por lo que colocar titulo primero asegura una resolución predecible del encabezado sin necesidad de una clave card_title explícita.
Propiedades del campo
| Propiedad | Obligatorio | Descripción |
|---|---|---|
name | sí | Identificador interno. Minúsculas, guiones bajos para espacios. |
type | sí | Uno de: Text, Textarea, Date, Number, Select, Link |
label | sí | Encabezado de columna legible. Debe coincidir exactamente con el encabezado de la tabla Markdown. |
options | Solo para Select | Lista separada por tubería (` |
colors | Select, opcional | Pares separados por tubería nombre=hex que asignan un color de fondo a cada opción (ej. `Alta=#e74c3c |
default | no | Valor por defecto para nuevas tarjetas |
Tipos de campo
| Tipo | Formato de almacenamiento | Descripción |
|---|---|---|
Text | Cadena simple | Texto de una sola línea |
Textarea | Cadena con <br> para saltos de línea | Texto multilínea |
Date | YYYY-MM-DD | Fecha del calendario |
Number | Cadena entera o decimal | Valor numérico |
Select | Uno de los valores de options | Elección restringida; las opciones pueden llevar colores hexadecimales mediante la propiedad colors |
Link | Lista separada por <br> de rutas o URI | Rutas relativas a la raíz de la bóveda (notes/doc.pdf) o URI externos (https://…, ftp://…, mailto:…) |
Nombres de campo especiales
| Nombre | Función |
|---|---|
titulo | Campo de visualización principal. Debe listarse primero en fields:. Se usa como encabezado de tarjeta detectado automáticamente cuando card_title no está configurado. |
estado | Obligatorio. Campo de columna Kanban. Debe ser type: Select. Las tarjetas se agrupan en columnas por este valor. El orden de las columnas sigue el orden de options. |
Todos los demás campos son secundarios, mostrados como metadatos de la tarjeta cuando se listan en card_fields.
Identidad del elemento
Cada tarjeta tiene un ID oculto estable almacenado en una columna _id en la tabla Markdown. La interfaz de usuario nunca muestra esta columna.
- Generado al crear la tarjeta: cadena alfanumérica corta y aleatoria (ej. 8 caracteres:
x7k2a1b3) - Conservado a través de todos los ciclos de serialización
- Sobrevive a reordenamientos, arrastrar y soltar, y cambios de nombre de campos
- Usado internamente para todas las operaciones de tarjetas (mover, editar, eliminar)
Debido a que la identidad se basa en el ID y no se deriva del contenido, renombrar el título de una tarjeta no tiene efecto en su identidad.
Flujo de trabajo
Define qué transiciones de estado están permitidas en la interfaz de usuario:
workflow: pendiente→haciendo, pendiente→hecho, haciendo→hecho, haciendo→pendiente, hecho→haciendo, hecho→pendiente
- Lista separada por comas de pares
desde→hasta(flecha:→, U+2192) - Si se omite
workflow, se permiten todas las transiciones entre las opciones de estado - Se usa para restringir las opciones de la interfaz de usuario (ej. un menú "Mover a" solo muestra destinos válidos)
- Las ediciones manuales de la tabla sin formato eluden la validación del flujo de trabajo por su naturaleza de texto plano
Plantillas de tablero
Al crear un nuevo tablero, un conjunto de plantillas predefinidas proporciona conjuntos comunes de opciones de estado. Las plantillas solo prellenan las opciones del campo estado y el workflow; todos los demás campos los añade el usuario.
| Plantilla | Opciones de estado | Flujo de trabajo predeterminado |
|---|---|---|
| Básico | pendiente | haciendo | hecho | Todas las transiciones |
| Software | backlog | por hacer | en progreso | revisión | hecho | Hacia adelante + un paso atrás |
| Contenido | idea | borrador | revisión | publicado | Solo hacia adelante |
| Proyecto | planificación | activo | bloqueado | completo | Todas excepto → planificación |
| Personalizado | Definido por el usuario | Definido por el usuario |
Seleccionar Personalizado abre un editor de formato libre para las opciones de estado y las transiciones del flujo de trabajo.
Tabla Markdown
La tabla aparece inmediatamente después del cierre --- de la sección de configuración.
Estructura
| _id | Encabezado1 | Encabezado2 |
|--------|-------------|-------------|
| abc123 | valor | valor |
- Fila de encabezados — la primera columna es siempre
_id; las columnas restantes son las etiquetas de los campos en el orden de definición del esquema. - Fila de separación — separador de tabla Markdown estándar.
- Filas de datos — una fila por tarjeta; la celda
_idcontiene el ID estable de la tarjeta.
Reglas
- El orden de las columnas en la tabla debe coincidir con el orden de definición de los campos (después de
_id) - Las celdas vacías son válidas (valor del campo = cadena vacía)
- El orden de las filas dentro de un grupo de estado es el orden de visualización
- Una tabla vacía (encabezado + separador, sin filas de datos) es válida
- La columna
_idsiempre es la primera y nunca se muestra en el tablero renderizado
Escapado
| Carácter en el valor | Escapado como |
|---|---|
| (tubería) | | (barra invertida + tubería) |
| Salto de línea | <br> |
| Retorno de carro | <br> |
Al leer: \| → |, <br> → salto de línea.
Al escribir: | → \|, cualquier salto de línea → <br>.
Algoritmo de análisis
- Extraer la cadena sin formato entre la apertura y el cierre del bloque
fancy-kanban. - Dividir en la primera línea
---para localizar el inicio de la sección de configuración. - Dividir en la segunda línea
---para separar la configuración de la tabla. - Analizar la configuración línea por línea: extraer
title,version,fields,workflow,lanes,card_title,card_fields,card_labels,card_limit. - Para
fields, recoger las líneas que comienzan con-y analizar cada una como paresclave: valorseparados por comas;colorsse decodifica como tokens separados por tuberíanombre=hex. - Encontrar líneas de tabla en el cuerpo (líneas que comienzan con
|). - La primera línea de tabla es la fila de encabezados: extraer las etiquetas de las columnas;
_idsiempre es la primera. - Mapear las etiquetas de encabezado restantes a nombres de campo mediante una búsqueda de etiquetas que no distingue entre mayúsculas y minúsculas.
- Analizar cada fila de datos: dividir por
|sin escapar, recortar celdas, desescapar\|y<br>. - La primera celda de cada fila de datos es el
_idde la tarjeta. - Agrupar tarjetas por el valor del campo
estado, sembrando grupos en el orden deoptions.
Reconciliación del esquema (aplicada después del análisis):
- Campos presentes en el esquema pero faltantes en los datos de una tarjeta: rellenar con el
defaultdel campo (o cadena vacía). - Campos presentes en los datos de la tarjeta pero eliminados del esquema: conservar como datos ocultos huérfanos (no se eliminan).
Algoritmo de escritura
- Reconstruir la sección de configuración a partir del esquema actual (conservar el formato original cuando sea posible).
- Generar la fila de encabezados:
_idprimero, luego las etiquetas de los campos en el orden de definición del esquema. - Generar la fila de separación.
- Generar una fila de datos por tarjeta:
_idprimero, luego los valores de los campos en el orden del esquema, con tuberías y saltos de línea escapados. - Generar un nuevo
_idde tarjeta usando una cadena alfanumérica aleatoria si la tarjeta no tiene un ID existente. - Reconstruir el bloque completo: apertura del delimitador, configuración,
---, línea en blanco, tabla, cierre del delimitador.
Principio de escritura: solo se modifica el rango de texto del bloque afectado en el archivo fuente; el contenido circundante nunca se reescribe.
Tablero mínimo viable
```fancy-kanban
---
title: Mi Tablero
fields:
- name: titulo, type: Text, label: Título
- name: estado, type: Select, options: pendiente|haciendo|hecho, label: Estado, default: pendiente
workflow: pendiente→haciendo, pendiente→hecho, haciendo→hecho, haciendo→pendiente, hecho→haciendo, hecho→pendiente
---
| _id | Título | Estado |
|-----|--------|--------|
## Notas de compatibilidad
- Sin el plugin, el bloque se renderiza como un bloque de código normal; todos los datos siguen siendo visibles como texto plano.
- La tabla Markdown dentro del bloque es Markdown válido y legible en cualquier editor de texto.
- La sección de configuración sigue las convenciones de YAML familiares para generadores de sitios estáticos y aplicaciones de toma de notas.
- Eliminar el plugin deja todos los datos intactos y recuperables.
## Funcionalidades obsoletas
Consulte [docs/deprecations.md](deprecations.md) para ver la lista completa de funcionalidades obsoletas y las guías de migración recomendadas.