Documentação web — MkDocs Material

Este repositório inclui site estático da pasta docs/ para a equipe de suporte (menu, busca, copiar comandos).

Por que MkDocs Material (e não Docsify/Jekyll)?

Critério	MkDocs Material	Docsify	Jekyll
Facilidade para suporte	⭐⭐⭐ Busca + menu fixo	⭐⭐ OK	⭐ Curva Ruby
Visual / UX	⭐⭐⭐ Profissional	⭐⭐ Simples	⭐⭐ depende do tema
Busca integrada	⭐⭐⭐ Nativa PT	⭐⭐ Plugin	⭐⭐ Plugin
Botão copiar comando	⭐⭐⭐ Sim	Manual	Manual
Build	mkdocs build → HTML	Só servir MD	jekyll build
Deploy VPS/nginx	Pasta site/ estática	Precisa JS runtime	_site/
Manutenção	mkdocs.yml + MD existentes	_sidebar.md + index.html	_config.yml + layouts

Recomendação: MkDocs Material — melhor custo/benefício para equipe que não quer navegar docs/ no terminal.

Comandos

# Instalar (uma vez — Python 3.10+)
pip install -r requirements-docs.txt

# Preview local (suporte treina no browser)
./scripts/serve-docs.sh

# Gerar HTML para publicar
./scripts/build-docs.sh
# Saída: site/ → copiar para nginx ou GitHub Pages

Publicar

Opções:

1. Subdomínio docs.orbitall.app ou lorentzdocs.orbitall.net.br — nginx serve site/
2. GitHub Pages — mkdocs gh-deploy (se repo público/interno)
3. Artefato no pacote dist — incluir site/ no tar.gz de suporte (offline)

Atualizar menu

Edite mkdocs.yml → seção nav: (espelha 00-indice.md).

Histórico

Data	Notas
2026-07-12	Adoção MkDocs Material + página SUPORTE-COMECE-AQUI