Manual do Projeto FlatForge

Manual do Projeto FlatForge (anteriormente `mauroreis_site_jinja2`)

Bem-vindo ao manual do FlatForge! Este documento detalha o funcionamento do gerador de sites estáticos (SSG) personalizado, construído com Python e Jinja2, e a suíte de ferramentas desenvolvidas para construir, analisar e manter o site pessoal de Mauro Sandro dos Reis.

Mascote Forgey, o Castor Engenheiro
Forgey, o Castor Engenheiro, mascote do FlatForge!

1. Objetivo do Projeto FlatForge

O FlatForge foi desenvolvido com os seguintes propósitos centrais:

  • Geração de Site Estático: Utilizar Python e o motor de templates Jinja2 para criar um site HTML estático, garantindo performance, segurança e facilidade de hospedagem.
  • Controle e Simplicidade: Oferecer um sistema de build leve, customizável e totalmente controlado, sem a complexidade de frameworks SSG mais pesados.
  • Automação de Conteúdo: Simplificar a adição e gerenciamento de novas páginas através de uma estrutura de templates e um script de build inteligente que detecta novo conteúdo.
  • Manutenção e Qualidade: Fornecer um conjunto integrado de ferramentas de linha de comando (CLI) para auxiliar na manutenção da qualidade do site, incluindo:
    • Verificação ortográfica.
    • Auditoria de metadados (SEO, Open Graph, Twitter Cards).
    • Detecção de links quebrados.
    • Identificação de páginas órfãs e sugestão de links.
    • Verificação da cadeia de redirecionamentos de URLs.
    • Comparação de sincronia entre o conteúdo local e o site publicado.
  • Segurança de Conteúdo: Embutir um hash de integridade do conteúdo principal nas páginas geradas para auxiliar na verificação de modificações não intencionais.

2. Estrutura Detalhada do Projeto

A organização dos arquivos e pastas é crucial para o funcionamento do FlatForge:

  • templates/: Diretório principal para todos os templates Jinja2.
    • base.html: O template mestre que define a estrutura HTML comum (doctype, head, header, footer, navegação).
    • header.html, footer.html: Templates parciais.
    • *_content.html: Arquivos com o conteúdo específico de cada página, estendendo o base.html.
    • templates/includes/ (Opcional): Para snippets HTML reutilizáveis (ex: `analytics.html`).
  • public_html/: Diretório de saída para os arquivos HTML finais, sitemap e manifesto de hashes. Este é o conteúdo a ser publicado.
  • build.py: O coração do FlatForge. Orquestra o processo de build, descobre conteúdo, renderiza templates, embute hashes e pode chamar outras ferramentas.
  • build_one.py: Script auxiliar para gerar uma única página HTML rapidamente.
  • sitemap.py: Gera o arquivo `sitemap.xml`.
  • Ferramentas de Análise (Scripts Python CLI):
    • link_checker.py: Verifica links quebrados.
    • metadata_checker.py: Audita metadados.
    • find_orphaned_pages.py: Identifica páginas órfãs.
    • suggest_internal_link_opportunities.py: Sugere links internos.
    • check_redirects.py: Verifica cadeias de redirecionamento.
    • check_site_sync.py: Compara conteúdo local com o site publicado.
    • spell_checker.py: Verifica a ortografia dos templates de conteúdo.
  • requirements.txt: Especifica as dependências Python.
  • README.md: Documentação principal do projeto no repositório GitHub.

3. Guia de Uso Detalhado

Para informações sobre configuração do ambiente e instalação de dependências, consulte o README.md no GitHub. Este manual foca no fluxo de trabalho e no uso das ferramentas.

3.1. Criando e Modificando Conteúdo

  • Novas páginas são criadas adicionando arquivos NOME_DA_PAGINA_content.html na pasta templates/.
  • Cada arquivo de conteúdo deve estender base.html e definir os blocos Jinja necessários, especialmente:
    • {% block page_title %}Título da Página{% endblock %}
    • {% block page_description %}Descrição para SEO.{% endblock %}
    • {% block page_path %}/caminho/para/pagina.html{% endblock %} (Crucial para a descoberta automática e URLs canônicas!)
    • {% block page_keywords %}keyword1, keyword2{% endblock %}
    • {% block content %}...CONTEÚDO HTML DA PÁGINA...{% endblock %}

3.2. Gerando o Site Completo (build.py)

Execute python build.py para construir todo o site. Ele processará páginas definidas em `manual_pages_data` (se houver) e descobrirá automaticamente novos conteúdos baseando-se no `page_path` interno dos templates.

python build.py

O script também embute um hash de integridade do conteúdo <main> em cada página e gera o `manifest_content_hashes.json`.

3.3. Gerando uma Página Individual (build_one.py)

Para regenerar rapidamente uma única página:

python build_one.py nome_do_template_content.html [caminho/de/saida.html]

Exemplo: python build_one.py pesquisa_content.html pesquisa/index.html

3.4. Utilizando as Ferramentas de Análise e Manutenção (CLI)

Após gerar o site em public_html/, use as ferramentas conforme necessário:

  • Sitemap: python sitemap.py
  • Verificador de Redirecionamentos: python check_redirects.py <URL_COMPLETA>
  • Verificador de Links Quebrados: python link_checker.py public_html --site-url https://mauroreis.app
  • Verificador de Metadados: python metadata_checker.py public_html
  • Localizador de Páginas Órfãs: python find_orphaned_pages.py public_html
  • Sugeridor de Links Internos: python suggest_internal_link_opportunities.py public_html
  • Verificador de Sincronia: python check_site_sync.py public_html https://mauroreis.app
  • Verificador Ortográfico (nos templates): python spell_checker.py templates

Use a flag --help com cada script para ver todas as suas opções (ex: python link_checker.py --help).

4. Publicação

O conteúdo da pasta public_html/ está pronto para ser publicado em qualquer serviço de hospedagem de sites estáticos (ex: Cloudflare Pages, GitHub Pages, Netlify).

5. Futuras Melhorias

O FlatForge é um projeto em constante evolução. Ideias para o futuro incluem a integração mais profunda das ferramentas de análise no fluxo do build.py com relatórios consolidados e a otimização da performance do build para sites muito grandes.