Lista de definições

A lista de definições é uma extensão do Markdown para criar termos e os respetivos significados. É útil para glossários, explicações de termos ou descrições de parâmetros.

Sintaxe básica

Formato básico

A forma básica é composta por um termo numa linha e a definição na linha seguinte iniciada por dois pontos:

Termo
: Conteúdo da definição

Resultado:

Termo : Conteúdo da definição

Múltiplos termos e definições

Markdown
: Uma linguagem de marcação leve
: Criada por John Gruber em 2004

HTML
: Linguagem de Marcação de Hipertexto
: Linguagem padrão para páginas web

Resultado:

Markdown : Uma linguagem de marcação leve : Criada por John Gruber em 2004

HTML : Linguagem de Marcação de Hipertexto : Linguagem padrão para páginas web

Uso avançado

Definições multilinha

O conteúdo pode ter várias linhas; as linhas seguintes devem estar indentadas:

Termo
: Esta é a primeira linha da definição
  Esta é a segunda linha; precisa de pelo menos um espaço de indentação
  
  Este é um novo parágrafo; precisa de pelo menos um espaço de indentação e uma linha em branco antes

Resultado:

Termo : Esta é a primeira linha da definição Esta é a segunda linha; precisa de pelo menos um espaço de indentação

Este é um novo parágrafo; precisa de pelo menos um espaço de indentação e uma linha em branco antes

Usar outros elementos Markdown na definição

Dentro da definição podes usar outros elementos Markdown, como ligações, ênfase, código, etc.:

Sintaxe Markdown
: **Markdown** suporta vários formatos de texto:
  - *itálico* e **negrito**
  - [ligações](https://www.markdownlang.com)
  - `código inline`
  - > bloco de citação
  - listas e outros elementos

Resultado:

Sintaxe Markdown : Markdown suporta vários formatos de texto:

• itálico e negrito
• ligações
• código inline

• bloco de citação

• listas e outros elementos

Listas de definições aninhadas

Em algumas implementações é possível aninhar listas de definições:

Termo externo
: Definição externa

  Termo interno
  : Definição interna
  : Outra definição interna

Resultado (em plataformas suportadas):

Termo externo : Definição externa

Termo interno : Definição interna : Outra definição interna

Compatibilidade e variações

Suporte em diferentes plataformas

Plataforma/Ferramenta	Suporte a DL	Sintaxe	Aninhado
GitHub Markdown	❌	-	-
GitLab Markdown	✅	Padrão	✅
Jekyll (kramdown)	✅	Padrão	✅
Hugo	✅	Padrão	✅
CommonMark	❌	-	-
VitePress	✅	Padrão	✅
Pandoc	✅	Padrão	✅

Saída HTML

A maioria dos processadores converte para <dl>, <dt> e <dd>:

<dl>
  <dt>Termo</dt>
  <dd>Conteúdo da definição</dd>
  
  <dt>Outro termo</dt>
  <dd>Outra definição</dd>
</dl>

Variações de sintaxe

Alguns processadores podem requerer variações:

<!-- Sintaxe padrão -->
Termo
: Definição

<!-- Sintaxe compacta (alguns processadores) -->
Termo: Definição

<!-- Espaço extra (alguns processadores) -->
Termo
  : Definição

Cenários de uso

Glossário

Listas de definições são ótimas para glossários:

## Glossário de programação

API
: Interface de Programação de Aplicações; um conjunto de regras para comunicação entre aplicações.

Framework
: Biblioteca com estrutura padronizada para desenvolvimento de aplicações.

Git
: Sistema de controlo de versões distribuído para registar alterações ao longo do desenvolvimento.

IDE
: Ambiente de Desenvolvimento Integrado com editor de código e ferramentas.

Resultado:

Glossário de programação

API : Interface de Programação de Aplicações; um conjunto de regras para comunicação entre aplicações.

Framework : Biblioteca com estrutura padronizada para desenvolvimento de aplicações.

Git : Sistema de controlo de versões distribuído para registar alterações ao longo do desenvolvimento.

IDE : Ambiente de Desenvolvimento Integrado com editor de código e ferramentas.

Documentação de API

Listas de definições em documentação de API para explicar parâmetros/opções:

## Parâmetros de pedido

user_id
: **Obrigatório** — Identificador único do utilizador.
: Tipo: `integer`

name
: **Opcional** — Nome de exibição do utilizador.
: Tipo: `string`
: Valor por omissão: `null`

status
: **Opcional** — Estado do utilizador.
: Tipo: `string`
: Valores permitidos: `active`, `inactive`, `suspended`
: Valor por omissão: `active`

Resultado:

Parâmetros de pedido

user_id : Obrigatório — Identificador único do utilizador. : Tipo: integer

name : Opcional — Nome de exibição do utilizador. : Tipo: string : Valor por omissão: null

status : Opcional — Estado do utilizador. : Tipo: string : Valores permitidos: active, inactive, suspended : Valor por omissão: active

Descrições de configuração

Também são úteis para explicar opções de configuração:

## Opções de configuração

debug
: Ativa/desativa o modo de depuração.
: Tipo: `boolean`
: Valor por omissão: `false`
: Exemplo: `debug: true`

log_level
: Nível de detalhe do registo.
: Tipo: `string`
: Valores permitidos: `error`, `warn`, `info`, `debug`
: Valor por omissão: `info`
: Exemplo: `log_level: debug`

max_connections
: Número máximo de ligações simultâneas.
: Tipo: `integer`
: Valor por omissão: `100`
: Exemplo: `max_connections: 500`

Boas práticas

Consistência de formato

✅ Recomendações:

1. **Manter estilo consistente entre termos e definições**:
   - Termos curtos (substantivo ou expressão)
   - Definições em frase, inicial maiúscula e ponto final
   - Em definições multilinha, manter indentação consistente

2. **Agrupamento lógico**:
   - Termos relacionados juntos
   - Usar títulos para separar categorias

3. **Para termos técnicos**:
   - Incluir tipo
   - Adicionar exemplos
   - Indicar obrigatório/opcional

❌ Evitar:

1. Termos longos (mais de uma linha)
2. Formatação excessiva no termo
3. Falta de categorização
4. Informação irrelevante na definição

Alternativas

Em plataformas sem suporte, podes simular com outras estruturas:

<!-- Negrito + indentação -->
**Termo**
  Conteúdo da definição

**Outro termo**
  Outra definição

<!-- Usar tabela -->
| Termo | Definição |
|-------|-----------|
| API | Interface de Programação de Aplicações |
| IDE | Ambiente de Desenvolvimento Integrado |

<!-- Título + parágrafo -->
### Termo
Conteúdo da definição

### Outro termo
Outra definição

Exemplos práticos

Documentação de software

## Requisitos do sistema

Sistema operativo
: **Windows**: Windows 10 ou superior
: **macOS**: macOS 10.14 (Mojave) ou superior
: **Linux**: Ubuntu 18.04+, Debian 10+, CentOS 7+

Hardware
: **Processador**: Quad‑core 2.0 GHz ou superior
: **Memória**: Mínimo 8 GB RAM, recomendado 16 GB
: **Armazenamento**: Pelo menos 10 GB livres; SSD recomendado

Rede
: Ligação banda larga (mín. 10 Mbps)
: Saídas permitidas nas portas 80, 443, 22

Documentação académica

## Termos de pesquisa

Conjunto de dados
: Conjunto usado para análise/avaliação.
: Este estudo usa amostras de repositório público (n=1000).

Variáveis
: **Independente**: fator de entrada controlado pelo investigador.
  Neste estudo, é a temperatura ambiente.
  
: **Dependente**: fator de saída medido.
  Neste estudo, é a velocidade de processamento.
  
: **De controlo**: fatores mantidos constantes.
  Incluem humidade e carga do processador.

Nível de significância
: Limite probabilístico para avaliar significância.
: Usamos p < 0.05 como critério.

Resolução de problemas

Lista de definições não aparece

Se a lista de definições não renderiza corretamente:

1. Verifica se a plataforma suporta a sintaxe
2. Garante que não há linha em branco entre termo e definição
3. Confirma espaços corretos antes dos dois pontos (alguns exigem específico)
4. Aumenta a indentação ou usa outra variação de sintaxe

Problemas com aninhamento

Listas aninhadas podem falhar em alguns processadores:

1. Aumenta a indentação (p.ex., 4 ou 8 espaços no termo interno)
2. Garante linhas em branco apropriadas entre níveis
3. Se persistir, considera usar listas normais

Problemas de formatação

Se a formatação estiver errada dentro da definição:

1. Verifica indentação correta de parágrafos e elementos
2. Garante linhas em branco entre elementos de bloco (código, listas)
3. Tenta aumentar a indentação

Sintaxe relacionada

• Listas - sintaxe básica de listas
• Tabelas - dados estruturados
• Blocos de código cercados - sintaxe de código

Ferramentas e plugins

• markdown-it-deflist: adiciona suporte a listas de definições ao markdown-it
• kramdown: parser Markdown com suporte nativo a listas de definições
• remark-definition-list: plugin de listas de definições para remark

---

As listas de definições são uma poderosa extensão do Markdown, ideais para documentação de termos, parâmetros e configurações. Embora nem todos os processadores suportem esta sintaxe, nas plataformas compatíveis fornecem um formato claro e estruturado que torna a informação complexa mais fácil de compreender e consultar.