Template MkDocs ¶

Um template simples para criar documentações usando MkDocs com tema Material Design e deploy automático no GitHub Pages.

Como usar este template¶

1. Criar novo repositório¶

Clique em "Use this template" no repositório no GitHub
Nomeie seu novo repositório
Clone o repositório para sua máquina local

2. Configuração inicial¶

Edite o arquivo mkdocs.yml e altere as seguintes configurações:

site_name: Seu Nome da Documentação # Altere aqui

3. Instalação local (opcional)¶

Para testar localmente antes do deploy:

# Criar ambiente virtual (recomendado)
python -m venv .venv

# Ativar ambiente virtual
# No Linux/macOS:
source .venv/bin/activate
# No Windows:
# .venv\Scripts\activate

# Instalar dependências
pip install --upgrade pip
pip install -r requirements.txt

# Servir localmente
mkdocs serve

A documentação estará disponível em http://127.0.0.1:8000

Nota: O uso de ambiente virtual é altamente recomendado para evitar conflitos de dependências.

Estrutura do projeto¶

template-mkdocs/
├── docs/                 # Arquivos de documentação
│   └── index.md         # Página inicial
├── .github/workflows/   # GitHub Actions
│   └── ci.yml          # Deploy automático
├── mkdocs.yml          # Configuração do MkDocs
├── requirements.txt    # Dependências Python
└── README.md           # Este arquivo

Criando conteúdo¶

Adicionando páginas¶

Crie novos arquivos .md na pasta docs/
Adicione as páginas no mkdocs.yml:

nav:
  - Início: index.md
  - Sobre: sobre.md
  - Guias: guias.md

Formatação suportada¶

Este template inclui diversas extensões para formatação avançada:

Extensões Markdown básicas:¶

Admonitions: Caixas de aviso, dica, erro, etc.
Syntax highlighting: Destaque de código com Pygments
Tables: Tabelas com suporte a alinhamento
Footnotes: Notas de rodapé
Abbreviations: Abreviações com tooltips
Definition lists: Listas de definição

Extensões PyMdown:¶

Tabbed: Abas para organizar conteúdo
Details: Seções recolhíveis
Emoji: Suporte a emojis
Keys: Representação de teclas Ctrl+C
Math: Fórmulas matemáticas com MathJax
Task lists: Listas de tarefas com checkboxes
Superfences: Code blocks avançados com anotações

Plugins adicionais:¶

Search: Busca integrada
Git revision date: Data de criação e modificação dos arquivos

Exemplo de admonition:

!!! note "Nota"
Este é um exemplo de caixa de nota.

!!! warning "Atenção"
Cuidado com esta configuração!

Exemplo de abas:

=== "Python"
`python
    print("Hello World")
    `

=== "JavaScript"
`javascript
    console.log("Hello World");
    `

Deploy no GitHub Pages¶

O deploy é automático! Sempre que você fizer push para a branch main:

O GitHub Actions será executado
A documentação será construída usando ambiente virtual
Os arquivos serão publicados na branch gh-pages
Sua documentação estará disponível em: https://seuusuario.github.io/nome-do-repo

Ativando o GitHub Pages¶

Vá em Settings → Pages no seu repositório
Em "Source", selecione "Deploy from a branch"
Escolha a branch gh-pages
Clique em "Save"

Personalização¶

Cores e tema¶

Edite o mkdocs.yml para personalizar:

theme:
  palette:
    - scheme: default
      primary: green # Mude a cor aqui

Cores disponíveis: red, pink, purple, blue, cyan, teal, green, yellow, orange

Extensões disponíveis¶

O template já vem configurado com as seguintes extensões:

Markdown Extensions:

abbr: Abreviações com tooltips
admonition: Caixas de aviso, nota, dica
attr_list: Atributos personalizados para elementos
def_list: Listas de definição
footnotes: Notas de rodapé
toc: Índice automático com links permanentes

PyMdown Extensions:

pymdownx.arithmatex: Fórmulas matemáticas
pymdownx.betterem: Melhor formatação de ênfase
pymdownx.caret: Texto sobrescrito
pymdownx.details: Seções recolhíveis
pymdownx.emoji: Suporte a emojis
pymdownx.highlight: Destaque de sintaxe avançado
pymdownx.inlinehilite: Código inline destacado
pymdownx.keys: Representação de teclas
pymdownx.magiclink: Links automáticos
pymdownx.mark: Texto marcado
pymdownx.smartsymbols: Símbolos inteligentes
pymdownx.superfences: Code blocks com anotações
pymdownx.tabbed: Sistema de abas
pymdownx.tasklist: Listas de tarefas
pymdownx.tilde: Texto subscrito e riscado

Plugins:

search: Busca integrada na documentação
git-revision-date-localized: Datas de criação e modificação automáticas

Uso de MathJax e KaTeX¶

Este template já inclui suporte a fórmulas matemáticas com MathJax e KaTeX. Os arquivos necessários de JavaScript e CSS são adicionados automaticamente via as opções extra_javascript e extra_css no mkdocs.yml.

Assim, você pode usar sintaxe LaTeX diretamente nos arquivos Markdown para exibir fórmulas matemáticas, sem necessidade de configuração adicional.

Exemplo de uso:

A equação de Euler é $e^{i\pi} + 1 = 0$.

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

Dicas¶

Use headers (#, ##, ###) para organizar o conteúdo
Coloque imagens na pasta docs/images/
Use ambiente virtual para desenvolvimento local
Teste localmente com mkdocs serve antes de fazer commit
O deploy leva alguns minutos para aparecer online
As datas de criação/modificação são adicionadas automaticamente

Solução de problemas¶

Deploy falhou?

Verifique se o mkdocs.yml está com sintaxe correta
Confira se todas as páginas referenciadas no nav existem
Verifique se o requirements.txt tem todas as dependências

Página não carrega?

Aguarde alguns minutos após o deploy
Verifique se o GitHub Pages está ativado nas configurações do repositório

Problemas com ambiente virtual?

Certifique-se de ativar o ambiente virtual antes de instalar dependências
Use pip install --upgrade pip para atualizar o pip
No Windows, use python -m pip se houver problemas com pip

Extensões não funcionam?

Verifique se todas as dependências estão instaladas
Confirme se a extensão está listada no mkdocs.yml

Feito usando MkDocs e Material for MkDocs

Template MkDocs¶