Pular para conteúdo

Aula 03 - Organização e Boas Práticas 📂

Objetivo

Objetivo: Aprender a estruturar projetos complexos com múltiplos arquivos Markdown, criar links internos inteligentes e desenvolver READMEs que chamam a atenção pela clareza e profissionalismo.

1. Estrutura de Documentação 🧱

À medida que um projeto cresce, um único arquivo .md não é suficiente. Devemos dividir o conteúdo logicamente.

Exemplo de Estrutura de Pastas

$ ls -R meu-projeto
docs/
├── intro.md
├── instalacao.md
└── configuracao.md
README.md

2. Arquivos Interligados 🔗

Para criar uma navegação fluida entre seus arquivos, use links relativos.

  • Link para arquivo na mesma pasta: [Instalação](instalacao.md)
  • Link para arquivo em pasta acima: [Início](../README.md)
  • Link para uma seção específica: [Pular para Configuração](#configuracao)

3. O README Profissional 🐙

O README.md é a primeira impressão do seu projeto no GitHub.

Elementos Essenciais:

  1. Título e Badges: Para status do projeto e versão.
  2. Descrição Curta: O que o projeto faz?
  3. Principais Funcionalidades: Em listas.
  4. Imagens ou GIFs: Demonstração visual.
  5. Instruções de Uso: Como rodar?

4. Blocos de Destaque e Admonitions 💡

O MkDocs suporta blocos especiais para atrair a atenção do leitor:

Nota

Isso é uma informação útil.

Atenção

Cuidado com este passo!

Important

Use emojis moderadamente para guiar o olhar do usuário, não para poluir o texto.

5. Visualização de Fluxo de Documentação 🧜‍♀️

mermaid graph LR R[README.md] --> I[Introdução] I --> G[Guia de Uso] G --> A[API Reference] G --> F[FAQ]

6. Simulação de Criação de README 🐚

$ echo "# Meu Projeto Incrível 🚀" > README.md
$ echo "## Funcionalidades" >> README.md
$ echo "- [x] Login rápido" >> README.md
$ cat README.md

7. Mini-Projeto: Documentando seu Projeto 🏗️

Sua tarefa hoje é criar a docs/ do seu repositório de estudos: 1. Crie um arquivo index.md (Página principal). 2. Crie um arquivo guia-rapido.md. 3. Adicione links no index.md que apontem para o guia-rapido.md. 4. Use pelo menos um bloco de "Dica" (!!! tip) ou "Aviso" (!!! warning).

8. Exercícios de Fixação 🧠

  1. Por que é importante dividir a documentação em múltiplos arquivos?
  2. Como se cria um link que aponta para uma seção específica (ID) de um arquivo?
  3. O que são Badges e qual sua utilidade no GitHub?

Próxima Aula: Vamos mergulhar no Markdown para Programação! 💻