title: Boas práticas de Markdown description: Estrutura de documentação, normas de conteúdo, exemplos de código e boas práticas para produzir documentação técnica de alta qualidade.

Boas práticas

Depois de dominar a sintaxe, como escrever documentação técnica de alta qualidade e fácil manutenção? Este guia cobre normas básicas e técnicas avançadas.

Desenho da estrutura

Organização de diretórios

project/
├── README.md                 # Visão geral do projeto
├── docs/
│   ├── index.md             # Página inicial da documentação
│   ├── getting-started/
│   │   ├── installation.md  # Guia de instalação
│   │   ├── quick-start.md   # Início rápido
│   │   └── examples.md      # Exemplos de código
│   ├── api/
│   │   ├── overview.md      # Visão geral da API
│   │   ├── authentication.md # Autenticação
│   │   └── endpoints/       # Endpoints da API
│   ├── guides/
│   │   ├── best-practices.md # Boas práticas
│   │   └── troubleshooting.md # Resolução de problemas
│   └── changelog.md         # Registo de alterações
└── assets/
    └── images/              # Recursos de imagem

内容层级结构

# Título de nível 1 — tema do documento

Introdução breve aos objetivos e ao conteúdo do documento.

## Título de nível 2 — secções principais

### Título de nível 3 — tópico específico

Conteúdo detalhado e explicações…

#### Título de nível 4 — sub‑tópico

Detalhes de implementação…

##### Título de nível 5 — notas adicionais

Avisos e dicas…

> **Nota**: evita usar mais de cinco níveis de títulos para não tornar a estrutura excessivamente complexa.

Normas de redação

Estilo

✅ Recomenda‑se:

1. **Linguagem simples e clara**
   - Evita frases longas
   - Prefere voz ativa
   - Minimiza jargão

2. **Tom consistente**
   - Formal e amigável
   - Orientado ao utilizador
   - Evita excesso de tecnicismo

3. **Orientação concreta**
   - Números e exemplos específicos
   - Passos claros
   - Resultados esperados

❌ Evitar:

- Ambiguidade
- Voz passiva em excesso
- Falta de contexto
- Assumir conhecimento prévio

Parágrafos e formatação

<!-- ✅ Boa estrutura de parágrafos -->
## Instalar o Node.js

Para começar a usar a nossa ferramenta, instala o Node.js. É um runtime de JavaScript que permite executar JS no servidor.

### Requisitos do sistema

Antes de instalar, garante que o teu sistema cumpre:

- SO: Windows 10+, macOS 10.12+ ou Linux
- RAM: 4 GB ou mais
- Armazenamento: 1 GB livre

### Passos de instalação

1. Visita o [site oficial](https://nodejs.org/)
2. Descarrega o instalador para o teu SO
3. Executa e segue os passos
4. No terminal, verifica:

Se mostra a versão, a instalação foi concluída.

instalar nodejs va ao site e instale ver a versao para sucesso

## Exemplos de código

### Boas práticas para blocos de código

Criar conta de utilizador

Exemplo de criação de um novo utilizador via API:

// Importar dependências
const axios = require('axios');

// Configurar endpoint
const API_BASE_URL = 'https://api.example.com';
const API_KEY = 'your-api-key';

// Função para criar utilizador
async function createUser(userData) {
  try {
    const response = await axios.post(`${API_BASE_URL}/users`, userData, {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
      }
    });
    
    console.log('Utilizador criado:', response.data);
    return response.data;
  } catch (error) {
    console.error('Falha ao criar utilizador:', error.response?.data);
    throw error;
  }
}

// Exemplo de uso
const newUser = {
  name: '张三',
  email: 'zhangsan@example.com',
  role: 'user'
};

createUser(newUser);

Saída esperada:

{
  "id": "12345",
  "name": "张三",
  "email": "zhangsan@example.com",
  "role": "user",
  "created_at": "2024-01-15T10:30:00Z"
}

Notas importantes:

• Substitui your-api-key pela tua chave real
• Garante conectividade de rede
• Nunca commits chaves em VCS

// 创建用户
axios.post('/users', data)

Isto cria um utilizador sem validações nem tratamento de erros.

### Exemplos de linha de comando

Deploy do projeto

1. Construir

# Instalar dependências
npm install

# Executar testes
npm test

# Build de produção
npm run build

2. Deploy para o servidor

# Ligar ao servidor
ssh user@server.example.com

# Entrar no diretório do projeto
cd /var/www/myproject

# Obter últimas alterações
git pull origin main

# Reiniciar serviço
sudo systemctl restart myproject

3. Validar deploy

# Verificar estado do serviço
sudo systemctl status myproject

# Ver logs
sudo journalctl -u myproject -f

Resultados esperados:

• Estado: active (running)
• https://yoursite.com mostra a versão mais recente

## Gestão de ligações e referências

### Ligações internas

Para instalação detalhada, vê o guia de instalação.

Para autenticação de API, consulta a documentação de autenticação.

Se tiveres problemas, abre o guia de resolução.

Clica aqui para ver como instalar. Ver: ./index.md

### Ligações externas

A nossa API segue o estilo REST e os status HTTP.

Para saber mais sobre JWT, consulta Documentação JWT e RFC 7519.

• Repositório GitHub 🔗
• Demo online 🌐
• Documentação oficial 📚

### Ligações por referência

Suportamos vários métodos de autenticação, incluindo API keys, OAuth 2.0 e JWT.

Consulta o guia de configuração e as FAQ.

## Otimização de imagens e media

### Boas práticas para imagens

Visão geral da interface

A figura abaixo mostra o layout principal da aplicação:

Descrição:

1. Barra superior com entradas principais
2. Sidebar à esquerda para navegação rápida
3. Área principal com o conteúdo da página
4. Barra inferior com informações do sistema

Arquitetura do sistema

Figura: arquitetura — relações entre componentes

Vê a imagem:

### 图片组织和命名

assets/ ├── images/ │ ├── ui/ │ │ ├── dashboard-overview.png │ │ ├── user-profile-edit.png │ │ └── settings-general.png │ ├── diagrams/ │ │ ├── system-architecture.svg │ │ ├── data-flow-diagram.png │ │ └── user-workflow.png │ └── screenshots/ │ ├── installation-step-1.png │ ├── installation-step-2.png │ └── installation-complete.png

assets/ ├── images/ │ ├── img1.png │ ├── pic2.jpg │ ├── screenshot.png │ └── diagram.svg

## Tabelas — princípios de design

### Tabelas de dados

Lista de endpoints da API

Método	Endpoint	Descrição	Auth	Parâmetros
GET	/api/users	Listar utilizadores	✅	page, limit, sort
POST	/api/users	Criar utilizador	✅	name, email, role
GET	/api/users/{id}	Obter utilizador	✅	id (path)
PUT	/api/users/{id}	Atualizar utilizador	✅	id, name, email
DELETE	/api/users/{id}	Remover utilizador	✅	id (path)

Notas:

• ✅ requer autenticação
• Inclui API key no header
• Parâmetros de path na URL
• Query em ?key=value&key2=value2

Planos e preços

Funcionalidade	Grátis	Pro	Enterprise
Utilizadores	até 5	até 50	ilimitado
Armazenamento	1GB	100GB	1TB
Chamadas API	1 000/mês	10 000/mês	ilimitado
Suporte	Comunidade	Email	24/7 dedicado
Preço	Grátis	Pago	Custom

Atualizar | Contactar vendas

### 复杂数据展示

服务器配置要求

服务器规格	推荐配置
	小型部署 (<1K 用户)	中型部署 (1K-10K 用户)	大型部署 (>10K 用户)
CPU	2 cores	4 cores	8+ cores
内存	4GB	8GB	16GB+
存储	50GB SSD	200GB SSD	500GB+ SSD
网络	100Mbps	1Gbps	10Gbps

```

Controlo de versões e colaboração

Gestão de versões da documentação

<!-- ✅ Adiciona versão no front matter -->
---
title: Guia de utilização da API
version: 2.1.0
last_updated: 2024-01-15
author: Equipa de documentação técnica
---

# Guia de utilização da API

> **Versões**: Este documento aplica‑se à API v2.1.0+.
> Para versões antigas, vê a [documentação de arquivo](./archive/).

## Registo de alterações

### v2.1.0 (2024-01-15)
- Gestão de grupos de utilizadores
- Otimização de autenticação
- Correções diversas

### v2.0.0 (2024-01-01)
- Reestruturação da API
- Atualização do mecanismo de auth
- Endpoints de operações em lote

Convenções de commits Git

<!-- ✅ Mensagens de commit claras -->
docs: atualizar docs de autenticação da API

- adicionar exemplo OAuth 2.0
- corrigir exemplo de código
- atualizar links

closes #123

<!-- ✅ Tipos comuns -->
Prefixos:
- docs: atualização de docs
- feat: nova funcionalidade
- fix: correção
- style: formatação
- refactor: reestruturação
- test: testes
- chore: tooling/infra

Normas de colaboração

<!-- Guia de contribuição -->
## Guia de contribuição

### Fluxo de submissão

1. **Faz fork** do repositório
2. **Cria branch** para as alterações
   ```bash
   git checkout -b docs/update-api-guide

3. Escreve conteúdo seguindo as normas
4. Testa localmente a renderização
5. Commit com mensagens claras
6. Abre PR com descrição das mudanças

Checklist de revisão

• [ ] Exatidão do conteúdo
• [ ] Clareza de linguagem
• [ ] Formatação consistente
• [ ] Validade dos links
• [ ] Exemplos executam
• [ ] Imagens corretas

## Acessibilidade e internacionalização

### Design para acessibilidade

<!-- ✅ 考虑可访问性的文档设计 -->
### Cores e contraste

Quando usares cores para transmitir informação, fornece alternativas:

::: tip 成功
✅ 成功： 操作已完成
:::

::: danger 错误
❌ 错误：操作失败
:::

### Texto alternativo

Fornece texto alternativo significativo para todas as imagens:

![Arquitetura do sistema: fluxo entre cliente, API gateway, microserviços e base de dados](/assets/images/main-interface.png)

### Navegação por teclado

Garante que a estrutura suporta navegação por teclado:

- Hierarquia de títulos
- Ligações para índice/TOC
- Links importantes fáceis de encontrar

### Internacionalização

project/ ├── docs/ │ ├── en/ # Inglês │ │ ├── README.md │ │ └── api/ │ ├── zh/ # Chinês │ │ ├── README.md │ │ └── api/ │ └── ja/ # Japonês │ ├── README.md │ └── api/

Idiomas

• English
• 中文
• 日本語

Última atualização: 15 de janeiro de 2024 (pt-PT) Last updated: January 15, 2024 (en-US) 最終更新日：2024年1月15日 (ja-JP)

## Otimização de desempenho

### Otimização de carregamento

<!-- ✅ Paginação -->
### Dividir documentos grandes

Divide documentos longos em partes:

1. [Visão geral](./overview.md) — conceitos
2. [Início rápido](./quickstart.md) — 5 minutos
3. [Tutorial](./tutorial.md) — percurso completo
4. [Referência da API](./api-reference.md)
5. [Exemplos](./examples.md)

🔍 Ver opções de configuração detalhadas

Configuração avançada

# Exemplo detalhado de configuração
server:
  host: 0.0.0.0
  port: 8080
  ssl:
    enabled: true
    cert_file: /path/to/cert.pem
    key_file: /path/to/key.pem

Estas opções destinam‑se a controlo fino em produção…

SEO para documentação

<!-- ✅ SEO em front matter e conteúdo -->
---
title: "Guia de autenticação de API — solução completa"
description: "Aprende a usar OAuth 2.0, JWT e API keys com segurança. Inclui exemplos e boas práticas."
keywords: ["autenticação", "OAuth", "JWT", "segurança", "API"]
---

# Guia de autenticação de API

Como validar e autorizar pedidos à API com segurança…

## Conteúdos deste capítulo

Este guia cobre:

1. [API keys](#api-密钥认证) — simples e rápido
2. [OAuth 2.0](#oauth-20) — padrão do setor
3. [JWT](#jwt-令牌) — autenticação stateless

Garantia de qualidade

Checklist de revisão de conteúdo

<!-- 📋 Checklist de qualidade -->
## Antes de publicar

### Qualidade do conteúdo
- [ ] Informação exata e completa
- [ ] Linguagem clara
- [ ] Estrutura lógica
- [ ] Exemplos executáveis
- [ ] Capturas atualizadas

### Verificações técnicas
- [ ] Links válidos
- [ ] Realce de sintaxe correto
- [ ] Imagens a mostrar
- [ ] Tabelas bem formatadas
- [ ] Fórmulas a renderizar

### Experiência do utilizador
- [ ] Navegação clara
- [ ] Pesquisa funcional
- [ ] Mobile responsivo
- [ ] Performance aceitável
- [ ] Acessibilidade

### Manutenibilidade
- [ ] Versões atualizadas
- [ ] Changelog mantido
- [ ] Docs relacionadas em sincronia
- [ ] Funcionalidades descontinuadas marcadas
- [ ] Guias de migração

Recolha de feedback

<!-- ✅ Mecanismos de feedback -->
## Ajuda‑nos a melhorar

### Feedback de documentação

Se encontrares erros ou tiveres sugestões:

1. **Feedback rápido**: [Abrir issue](https://github.com/example/docs/issues/new?template=doc-feedback.md)
2. **Discussão**: [Participar](https://github.com/example/docs/discussions)
3. **Editar**: [Editar esta página](https://github.com/example/docs/edit/main/docs/api/authentication.md)

### Avalia esta página

Esta página foi útil?

👍 Útil | 👎 A melhorar | 💡 Sugestões

### Contactos

- 📧 Equipa de docs: docs@example.com
- 💬 Suporte técnico: support@example.com
- 🐦 Social: [@ExampleDocs](https://twitter.com/ExampleDocs)

Sintaxe relacionada

• HTML embutido
• Fórmulas
• Diagramas
• Ferramentas e plugins

Ferramentas e recursos

Qualidade de documentação

• textlint: revisão de texto e estilo
• markdownlint: lint de Markdown
• alex: linguagem inclusiva
• Hemingway Editor: legibilidade

Plataformas de colaboração

• GitBook: colaboração de docs
• Notion: docs e gestão de conhecimento
• Confluence: colaboração enterprise
• Slab: plataforma moderna de docs

Ferramentas de análise

• Google Analytics: analytics de acesso
• Hotjar: comportamento do utilizador
• Mixpanel: interação
• FullStory: sessões completas

Automação

• GitHub Actions: build/deploy de docs
• Zapier: automação de workflows
• IFTTT: regras simples
• n8n: automação open‑source

Ao seguir estas boas práticas, criarás documentação técnica de alta qualidade e centrada no utilizador, sustentando o sucesso do projeto.