{"id":28755718,"url":"https://github.com/gabriel04alves/template-mkdocs","last_synced_at":"2025-06-27T02:36:36.948Z","repository":{"id":299300477,"uuid":"998029770","full_name":"gabriel04alves/template-mkdocs","owner":"gabriel04alves","description":"Template simples para criar documentações usando MkDocs com tema Material Design e deploy automático no GitHub Pages.","archived":false,"fork":false,"pushed_at":"2025-06-23T14:49:27.000Z","size":592,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-23T15:45:20.594Z","etag":null,"topics":["documentation","gh-pages","mkdocs"],"latest_commit_sha":null,"homepage":"https://gabriel04alves.github.io/template-mkdocs/","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gabriel04alves.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-07T18:04:49.000Z","updated_at":"2025-06-23T14:49:04.000Z","dependencies_parsed_at":"2025-06-15T21:47:55.296Z","dependency_job_id":null,"html_url":"https://github.com/gabriel04alves/template-mkdocs","commit_stats":null,"previous_names":["gabriel04alves/template-mkdocs"],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/gabriel04alves/template-mkdocs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabriel04alves%2Ftemplate-mkdocs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabriel04alves%2Ftemplate-mkdocs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabriel04alves%2Ftemplate-mkdocs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabriel04alves%2Ftemplate-mkdocs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabriel04alves","download_url":"https://codeload.github.com/gabriel04alves/template-mkdocs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabriel04alves%2Ftemplate-mkdocs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262179161,"owners_count":23271176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","gh-pages","mkdocs"],"created_at":"2025-06-17T03:00:26.336Z","updated_at":"2025-06-27T02:36:36.908Z","avatar_url":"https://github.com/gabriel04alves.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Template MkDocs\n\nUm template simples para criar documentações usando MkDocs com tema Material Design e deploy automático no GitHub Pages.\n\n## Como usar este template\n\n### 1. Criar novo repositório\n\n1. Clique em \"Use this template\" no GitHub\n2. Nomeie seu novo repositório\n3. Clone o repositório para sua máquina local\n\n### 2. Configuração inicial\n\nEdite o arquivo `mkdocs.yml` e altere as seguintes configurações:\n\n```yaml\nsite_name: Seu Nome da Documentação # Altere aqui\n```\n\n### 3. Instalação local (opcional)\n\nPara testar localmente antes do deploy:\n\n```bash\n# Criar ambiente virtual (recomendado)\npython -m venv .venv\n\n# Ativar ambiente virtual\n# No Linux/macOS:\nsource .venv/bin/activate\n# No Windows:\n# .venv\\Scripts\\activate\n\n# Instalar dependências\npip install --upgrade pip\npip install -r requirements.txt\n\n# Servir localmente\nmkdocs serve\n```\n\nA documentação estará disponível em `http://127.0.0.1:8000`\n\n**Nota**: O uso de ambiente virtual é altamente recomendado para evitar conflitos de dependências.\n\n## Estrutura do projeto\n\n```\ntemplate-mkdocs/\n├── docs/                 # Arquivos de documentação\n│   └── index.md         # Página inicial\n├── .github/workflows/   # GitHub Actions\n│   └── ci.yml          # Deploy automático\n├── mkdocs.yml          # Configuração do MkDocs\n├── requirements.txt    # Dependências Python\n└── README.md           # Este arquivo\n```\n\n## Criando conteúdo\n\n### Adicionando páginas\n\n1. Crie novos arquivos `.md` na pasta `docs/`\n2. Adicione as páginas no `mkdocs.yml`:\n\n```yaml\nnav:\n  - Início: index.md\n  - Sobre: sobre.md\n  - Guias: guias.md\n```\n\n### Formatação suportada\n\nEste template inclui diversas extensões para formatação avançada:\n\n#### Extensões Markdown básicas:\n\n- **Admonitions**: Caixas de aviso, dica, erro, etc.\n- **Syntax highlighting**: Destaque de código com Pygments\n- **Tables**: Tabelas com suporte a alinhamento\n- **Footnotes**: Notas de rodapé\n- **Abbreviations**: Abreviações com tooltips\n- **Definition lists**: Listas de definição\n\n#### Extensões PyMdown:\n\n- **Tabbed**: Abas para organizar conteúdo\n- **Details**: Seções recolhíveis\n- **Emoji**: Suporte a emojis :smile:\n- **Keys**: Representação de teclas ++ctrl+c++\n- **Math**: Fórmulas matemáticas com MathJax\n- **Task lists**: Listas de tarefas com checkboxes\n- **Superfences**: Code blocks avançados com anotações\n\n#### Plugins adicionais:\n\n- **Search**: Busca integrada\n- **Git revision date**: Data de criação e modificação dos arquivos\n\nExemplo de admonition:\n\n```markdown\n!!! note \"Nota\"\nEste é um exemplo de caixa de nota.\n\n!!! warning \"Atenção\"\nCuidado com esta configuração!\n```\n\nExemplo de abas:\n\n```markdown\n=== \"Python\"\n`python\n    print(\"Hello World\")\n    `\n\n=== \"JavaScript\"\n`javascript\n    console.log(\"Hello World\");\n    `\n```\n\n## Deploy no GitHub Pages\n\nO deploy é **automático**! Sempre que você fizer push para a branch `main`:\n\n1. O GitHub Actions será executado\n2. A documentação será construída usando ambiente virtual\n3. Os arquivos serão publicados na branch `gh-pages`\n4. Sua documentação estará disponível em: `https://seuusuario.github.io/nome-do-repo`\n\n### Ativando o GitHub Pages\n\n1. Vá em Settings → Pages no seu repositório\n2. Em \"Source\", selecione \"Deploy from a branch\"\n3. Escolha a branch `gh-pages`\n4. Clique em \"Save\"\n\n## Personalização\n\n### Cores e tema\n\nEdite o `mkdocs.yml` para personalizar:\n\n```yaml\ntheme:\n  palette:\n    - scheme: default\n      primary: green # Mude a cor aqui\n```\n\nCores disponíveis: `red`, `pink`, `purple`, `blue`, `cyan`, `teal`, `green`, `yellow`, `orange`\n\n### Extensões disponíveis\n\nO template já vem configurado com as seguintes extensões:\n\n**Markdown Extensions:**\n\n- `abbr`: Abreviações com tooltips\n- `admonition`: Caixas de aviso, nota, dica\n- `attr_list`: Atributos personalizados para elementos\n- `def_list`: Listas de definição\n- `footnotes`: Notas de rodapé\n- `toc`: Índice automático com links permanentes\n\n**PyMdown Extensions:**\n\n- `pymdownx.arithmatex`: Fórmulas matemáticas\n- `pymdownx.betterem`: Melhor formatação de ênfase\n- `pymdownx.caret`: Texto sobrescrito\n- `pymdownx.details`: Seções recolhíveis\n- `pymdownx.emoji`: Suporte a emojis\n- `pymdownx.highlight`: Destaque de sintaxe avançado\n- `pymdownx.inlinehilite`: Código inline destacado\n- `pymdownx.keys`: Representação de teclas\n- `pymdownx.magiclink`: Links automáticos\n- `pymdownx.mark`: Texto marcado\n- `pymdownx.smartsymbols`: Símbolos inteligentes\n- `pymdownx.superfences`: Code blocks com anotações\n- `pymdownx.tabbed`: Sistema de abas\n- `pymdownx.tasklist`: Listas de tarefas\n- `pymdownx.tilde`: Texto subscrito e riscado\n\n**Plugins:**\n\n- `search`: Busca integrada na documentação\n- `git-revision-date-localized`: Datas de criação e modificação automáticas\n\n## Dicas\n\n- Use headers (`#`, `##`, `###`) para organizar o conteúdo\n- Coloque imagens na pasta `docs/images/`\n- Use ambiente virtual para desenvolvimento local\n- Teste localmente com `mkdocs serve` antes de fazer commit\n- O deploy leva alguns minutos para aparecer online\n- As datas de criação/modificação são adicionadas automaticamente\n\n## Solução de problemas\n\n**Deploy falhou?**\n\n- Verifique se o `mkdocs.yml` está com sintaxe correta\n- Confira se todas as páginas referenciadas no `nav` existem\n- Verifique se o `requirements.txt` tem todas as dependências\n\n**Página não carrega?**\n\n- Aguarde alguns minutos após o deploy\n- Verifique se o GitHub Pages está ativado nas configurações do repositório\n\n**Problemas com ambiente virtual?**\n\n- Certifique-se de ativar o ambiente virtual antes de instalar dependências\n- Use `pip install --upgrade pip` para atualizar o pip\n- No Windows, use `python -m pip` se houver problemas com `pip`\n\n**Extensões não funcionam?**\n\n- Verifique se todas as dependências estão instaladas\n- Confirme se a extensão está listada no `mkdocs.yml`\n\n---\n\nFeito usando [MkDocs](https://www.mkdocs.org/) e [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabriel04alves%2Ftemplate-mkdocs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabriel04alves%2Ftemplate-mkdocs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabriel04alves%2Ftemplate-mkdocs/lists"}