Plataforma open-source para criação de sites focados em geo-narrativas e documentação de direitos humanos
Crie narrativas digitais interativas com mapas, dados, documentos e multimídia.
A Documental é uma plataforma open source para criação de sites voltados à documentação, memória, pesquisa e joralismo em casos de defesa de direitos humanos e ambientais. Ela reúne edição visual de conteúdo, mapas interativos e uma arquitetura moderna para que equipes possam publicar projetos complexos sem precisar desenvolver toda a infraestrutura do zero.
A Documental nasceu para resolver um problema comum entre jornalistas, pesquisadores, organizações da sociedade civil e instituições culturais: como publicar narrativas digitais ricas, interativas e visualmente atraentes sem precisar desenvolver uma plataforma própria.
Ao invés de criar apenas páginas estáticas, o Documental permite combinar diferentes formas de conteúdo em uma única experiência:
- mapas interativos;
- textos e documentos;
- imagens e galerias;
- vídeos incorporados;
- visualizações de dados;
- ⏳ linhas do tempo;
- indicadores e destaques;
- componentes reutilizáveis.
Tudo isso utilizando uma arquitetura moderna, aberta e baseada em arquivos, permitindo hospedar os projetos em qualquer serviço compatível com sites estáticos.
A Documental é composto por diferentes projetos que trabalham juntos para oferecer uma experiência completa, desde a criação até a publicação de um site.
A principal forma de utilizar a plataforma.
O Desktop transforma o Documental em uma experiência semelhante a um aplicativo de edição, eliminando praticamente toda a complexidade técnica.
Com ele é possível:
- autenticar utilizando sua conta GitHub;
- criar novos projetos em poucos cliques;
- abrir projetos existentes;
- gerenciar múltiplos ambientes de trabalho;
- sincronizar automaticamente com o GitHub;
- editar conteúdo através do CMS integrado;
- trabalhar completamente offline;
- publicar alterações quando desejar.
Para a maioria dos usuários, esta será a única ferramenta necessária.
O Template é o ponto de partida para novos projetos.
Ao criar um novo repositório a partir dele, você obtém uma estrutura pronta para começar a produzir conteúdo imediatamente.
O Template abstrai praticamente todo o código da plataforma e utiliza o Documental Core como dependência NPM, mantendo o repositório do projeto focado apenas em:
- conteúdo;
- configurações;
- identidade visual;
- dados;
- arquivos de mídia.
Dessa forma, atualizar a plataforma passa a ser tão simples quanto atualizar uma dependência.
Você está aqui.
Este repositório contém toda a infraestrutura compartilhada da plataforma.
É nele que são desenvolvidos:
- componentes visuais;
- sistema de temas;
- layouts;
- CMS;
- integração com mapas;
- animações;
- internacionalização;
- sistema de páginas;
- funcionalidades reutilizadas pelos demais projetos.
Na maioria dos casos você não precisará modificar este repositório diretamente. Ele existe principalmente para a evolução da plataforma e para contribuições da comunidade.
A Documental foi projetado para qualquer projeto que combine narrativa, documentos e informação geográfica.
Alguns exemplos:
- Reportagens investigativas
- Documentação de direitos humanos
- Atlas digitais
- Projetos de memória
- Mapeamentos territoriais
- Projetos socioambientais
- Relatórios institucionais
- Pesquisas acadêmicas
- Diagnósticos urbanos
- Exposições digitais
- Centros de documentação
- Portais de transparência
- Projetos educacionais
- Observatórios temáticos
Gerencie praticamente todo o conteúdo através de uma interface administrativa intuitiva.
Você pode editar páginas, textos, imagens, mapas e componentes sem precisar alterar arquivos manualmente ou escrever código.
A Documental foi desenvolvido para que mapas não sejam apenas um elemento complementar, mas parte central da experiência.
É possível criar narrativas geográficas utilizando:
- múltiplas camadas;
- filtros;
- marcadores;
- estilos personalizados;
- integração entre mapas e conteúdo editorial.
Monte páginas utilizando dezenas de componentes reutilizáveis, incluindo:
- textos ricos;
- galerias;
- vídeos;
- linhas do tempo;
- gráficos;
- indicadores;
- comparadores de imagens;
- cards;
- layouts responsivos;
- blocos HTML;
- mapas.
Cada projeto possui sua própria identidade visual.
Personalize facilmente:
- cores;
- tipografia;
- espaçamentos;
- animações;
- componentes.
Estruture projetos em diferentes idiomas utilizando uma arquitetura preparada para internacionalização.
Os projetos são publicados como sites estáticos modernos, oferecendo:
- carregamento rápido;
- excelente SEO;
- alta segurança;
- baixo custo de hospedagem;
- compatibilidade com GitHub Pages, Cloudflare Pages e outros provedores.
Todos os componentes foram desenvolvidos para funcionar em computadores, tablets e dispositivos móveis.
A Documental foi pensado para equipes que precisam comunicar informações complexas de forma acessível.
Entre elas:
- organizações da sociedade civil;
- jornalistas;
- pesquisadores;
- universidades;
- instituições públicas;
- centros de memória;
- museus;
- arquivos;
- coletivos;
- organizações culturais;
- laboratórios de inovação.
No entanto, qualquer projeto que combine conteúdo editorial, mapas e dados pode se beneficiar da plataforma.
Existem diferentes maneiras de utilizar o Documental, dependendo do seu perfil.
Utilize o Documental Desktop.
Ele oferece a experiência mais simples para criar, editar e publicar projetos, sem necessidade de configurar um ambiente de desenvolvimento.
Você está no repositório correto.
O Documental Core concentra todo o desenvolvimento da plataforma, incluindo componentes, arquitetura, integrações e funcionalidades compartilhadas.
Esta seção é destinada a desenvolvedores, mantenedores e contribuidores do Documental Core.
Se você deseja apenas criar um projeto utilizando a plataforma, recomendamos utilizar o Documental Desktop ou o Documental Template, apresentados na seção anterior.
O Core contém toda a infraestrutura compartilhada do ecossistema Documental e é responsável por fornecer os componentes, layouts, integrações e funcionalidades utilizadas pelos demais projetos.
A Documental segue uma arquitetura modular baseada em JAMStack, priorizando desempenho, simplicidade de hospedagem e baixo custo de manutenção.
┌─────────────────────────┐
│ Documental Desktop │
│ (Aplicação principal) │
└────────────┬────────────┘
│
│
┌────────────▼────────────┐
│ Documental Template │
│ Projeto do usuário │
└────────────┬────────────┘
│
npm install @documental/core
│
┌────────────▼────────────┐
│ Documental Core │
│ Componentes e Engine │
└────────────┬────────────┘
│
Astro • Svelte • Mapbox • CMS
O fluxo recomendado é:
- O usuário cria um projeto utilizando o Template.
- O Template instala automaticamente o Documental Core como dependência.
- O desenvolvimento do conteúdo acontece dentro do Template.
- O Core evolui independentemente e pode ser atualizado via NPM.
- O Desktop automatiza toda essa experiência.
Essa separação permite que projetos sejam atualizados sem copiar código entre repositórios.
A Documental foi desenvolvido seguindo alguns princípios fundamentais.
Projetos não precisam conter centenas de arquivos de infraestrutura.
O objetivo é manter cada repositório focado apenas em:
- conteúdo;
- configuração;
- identidade visual.
Toda a lógica permanece no Core.
Toda funcionalidade deve ser implementada como um componente reutilizável.
Isso reduz duplicação de código e facilita manutenção.
O conteúdo é armazenado em arquivos versionáveis, facilitando:
- Git;
- revisão de alterações;
- colaboração;
- histórico;
- backup.
Toda a plataforma é construída como software livre.
Novos componentes, melhorias e correções são sempre bem-vindos.
O Core utiliza tecnologias modernas focadas em desempenho e experiência de desenvolvimento.
| Tecnologia | Finalidade |
|---|---|
| Astro | Framework principal |
| Svelte | Componentes interativos |
| TypeScript | Tipagem |
| JavaScript | Scripts |
| SCSS | Sistema de estilos |
| Vite | Build |
| Mapbox GL JS | Mapas |
| Sveltia CMS | Gerenciamento de conteúdo |
src/
│
├── components/
│ ├── content/
│ ├── layout/
│ ├── maps/
│ ├── charts/
│ ├── gallery/
│ └── ...
│
├── layouts/
│
├── pages/
│
├── content/
│
├── assets/
│
├── lib/
│
└── styles/
public/
├── admin/
├── uploads/
└── assets/
scripts/
package.json
astro.config.mjs
vite.config.js
- Node.js 20+
- npm
git clone https://github.com/documental-xyz/core.git
cd corenpm installInicie o servidor local.
npm run devO projeto ficará disponível em:
http://localhost:4321
npm run buildOs arquivos serão gerados em:
dist/
npm run preview| Comando | Descrição |
|---|---|
| npm install | Instala dependências |
| npm run dev | Desenvolvimento |
| npm run build | Build de produção |
| npm run preview | Preview local |
| npm run serve | Servidor da build |
Caso não queira configurar um ambiente local, o projeto pode ser executado diretamente no navegador.
Ambiente completo de desenvolvimento em poucos segundos.
Ideal para testes rápidos e exploração do código.
Toda a interface do Documental é construída a partir de componentes independentes.
Os componentes são organizados por domínio de responsabilidade.
Exemplos:
- Conteúdo
- Layout
- Mapas
- Gráficos
- Galerias
- Navegação
- Utilidades
Essa organização facilita:
- manutenção;
- testes;
- reutilização;
- evolução da plataforma.
O Core possui um sistema completo de temas.
Cada projeto pode definir sua própria identidade visual sem alterar componentes internos.
É possível personalizar:
- tipografia;
- paleta de cores;
- espaçamentos;
- animações;
- estilos globais.
O gerenciamento de conteúdo é realizado através do Sveltia CMS.
Toda a configuração do CMS está localizada em:
public/admin/
Através dele é possível editar:
- páginas;
- componentes;
- mapas;
- imagens;
- conteúdo multilíngue;
- configurações do projeto.
Os recursos de geonarrativa são implementados utilizando Mapbox GL JS.
Entre as funcionalidades disponíveis:
- múltiplas camadas;
- filtros;
- marcadores;
- estilos customizados;
- integração entre mapas e conteúdo;
- parâmetros específicos para dispositivos móveis.
O Core possui suporte nativo para múltiplos idiomas.
Atualmente a plataforma oferece estrutura para:
- Português
- English
- Español
Novos idiomas podem ser adicionados facilmente.
Os projetos gerados pelo Documental podem ser publicados em qualquer hospedagem compatível com sites estáticos.
Entre elas:
- GitHub Pages
- Cloudflare Pages
- Netlify
- Vercel
- servidores próprios
O Core é distribuído como pacote NPM e utilizado pelo Documental Template.
Fluxo de publicação:
- Atualizar a versão no
package.json. - Criar uma tag Git.
- Enviar a tag para o GitHub.
- O GitHub Actions executará automaticamente:
- testes;
- build;
- publicação no NPM.
git tag v1.0.0
git push --tagsContribuições são muito bem-vindas.
Você pode colaborar através de:
- novos componentes;
- melhorias de performance;
- documentação;
- correções de bugs;
- testes;
- internacionalização.
Antes de abrir um Pull Request recomendamos:
- verificar se já existe uma Issue relacionada;
- seguir o padrão de código do projeto;
- adicionar documentação para novos componentes;
- manter compatibilidade com versões anteriores sempre que possível.
As próximas partes do README apresentam:
- Componentes disponíveis
- Roadmap
- Changelog
- Créditos
- Licença
Essas informações complementam a documentação técnica e acompanham a evolução contínua do ecossistema Documental.
Este projeto está licenciado sob a GPL 2.0 License - veja o arquivo LICENSE para detalhes.
Permitido uso comercial
Modificação e distribuição
Uso privado
Sem garantias