laiss-docs

Gera documentos PDF em A4 a partir de um ficheiro JSON, com um design fixo: tipografia, paleta, capa e grelha iguais em todos os documentos. O corpo é escrito em blocos JSON, nunca em LaTeX, e o motor compõe e verifica o PDF.

Instalação

pip install laiss-docs

O pacote não tem dependências Python, mas precisa de três coisas do sistema que o pip não instala: LuaLaTeX, pdftotext e pdfinfo.

A primeira compilação verifica o que falta na máquina e mostra o plano antes de mexer no sistema. Se houver terminal, instala o que falta (o sudo pede a password). Num sítio sem terminal, como um pipeline de CI, não instala nada e diz o que instalar. Para tratar disto antes do primeiro documento:

laiss-docs deps --dry-run    # o que falta e que comandos seriam corridos
laiss-docs deps              # instala, depois de perguntar
laiss-docs deps -y           # instala sem perguntar (CI)
laiss-docs doctor            # confirma o que está pronto

O deps reconhece Debian, Ubuntu, Arch, Fedora, openSUSE, Alpine, macOS e NixOS. Em CI, a instalação automática só acontece com LAISSDOCS_AUTO_INSTALL=1.

Requisitos de sistema

• Python 3.9 ou mais recente, para correr o programa.
• LuaLaTeX (TeX Live, MacTeX ou MiKTeX), para compor o PDF. Não é opcional e não pode ser trocado por Tectonic, que usa outro motor: a razão está em docs/porque-lualatex.md, no repositório.
• pdftotext e pdfinfo (poppler), para verificar o PDF produzido.

O deps instala os três. Instala também, se os pedires, o Graphviz e o mermaid-cli, que só são necessários para diagramas.

Início rápido

laiss-docs new relatorio --title "Relatório Técnico" --lang pt-PT
laiss-docs build relatorio
laiss-docs preview relatorio

O new cria a pasta com o doc.json e o src/. O build compila e verifica:

a compilar /caminho/relatorio ...
  ✓ pages        3 paginas
  ✓ a4           A4
  ✓ text-layer   sem glifos colados
  ✓ refs         todas as referencias resolvidas
  ✓ toc          1 entradas conferidas

/caminho/relatorio/out/relatorio-tecnico.pdf

Um documento criado assim tem só uma caixa a dizer que está vazio. Para ter texto, escreve o doc.json (secção seguinte) e compila de novo. Se alguma verificação falhar, o comando sai com código 1, e é isso que o torna utilizável em CI.

Os comandos

Todos aceitam --json, que imprime o resultado em JSON em vez de texto.

Sem nome de documento, build, check, preview, outline, add, read e generate usam o documento da pasta actual, ou a única pasta que ali tenha um doc.json.

Como se escreve um documento

O doc.json tem os metadados e as secções. Cada secção tem um title e uma lista de blocks. Este ficheiro compila e produz quatro páginas:

{
  "title": "Relatório de Novembro",
  "subtitle": "O que mudou no motor de compilação.",
  "language": "pt-PT",
  "sections": [
    {
      "title": "Estado actual",
      "label": "PARTE 1",
      "blocks": [
        {"type": "p", "text": "O motor compila três vezes e verifica o PDF no fim. Um **parágrafo** aceita `código` e *ênfase*."},
        {"type": "h", "level": 2, "text": "O que foi feito"},
        {"type": "ul", "items": ["Blocos passaram a JSON", "Design fixo", "Cinco idiomas"]},
        {"type": "note", "title": "Uma nota", "text": "As fontes vão dentro do pacote."},
        {"type": "chart", "caption": "Tempo por passagem", "unit": " s", "labels": ["1ª", "2ª", "3ª"], "values": [3, 2, 2]}
      ]
    }
  ]
}

Guarda-o e corre laiss-docs new relatorio --from-json modelo.json, seguido de laiss-docs build relatorio. Os campos de topo mais usados são title (obrigatório), subtitle, language, date (AAAA-MM-DD), classification, coverFrom, coverTo, keywords, toc (índice, ligado por omissão) e colophon (página final, desligada por omissão).

Os blocos disponíveis:

Dentro dos blocos de texto há quatro marcas: **forte**, *ênfase*, `código` e [[caminho/ficheiro]]. Tudo o resto é texto literal, incluindo _, % e #. Não escrevas comandos LaTeX: apareceriam no PDF como texto.

O caption das quatro famílias de figura é obrigatório. Um documento também pode ter abstract (resumo, depois do índice e sem número) e appendices (anexos numerados ANEXO A, B). A referência completa está em docs/blocos.md, no repositório.

Figuras e diagramas

Para saber o que está disponível nesta máquina antes de escrever o bloco, usa a ferramenta laiss_diagrams do servidor MCP, ou simplesmente escolhe chart, que funciona sempre.

Os caminhos das figuras são relativos à pasta do documento. Quando há figuras, o índice de figuras é gerado automaticamente; "listOfFigures": false desliga-o.

Idiomas

laiss-docs locales

O idioma muda a hifenização, a data por extenso, o título do índice, as etiquetas da capa e os títulos por omissão das caixas. Não muda o design: a tipografia e a paleta são as mesmas em todos os idiomas.

Uso por agentes AI

O laiss-docs mcp arranca um servidor MCP sobre stdio, sem dependências. No Cursor, cria .cursor/mcp.json:

{
  "mcpServers": {
    "laiss-docs": {
      "command": "laiss-docs",
      "args": ["mcp"]
    }
  }
}

O servidor expõe 22 ferramentas: criar documento, ler e editar secções e blocos, gerir resumo e anexos, compilar e verificar. A primeira que o agente deve chamar é laiss_guide, que devolve o processo inteiro, os tipos de bloco, a marcação permitida e os erros comuns. Sem ela, um agente tenta escrever LaTeX e conclui que a ferramenta está avariada. O resto do ciclo é laiss_outline (que id existe), laiss_add_section, laiss_add_blocks e laiss_build, que devolve as verificações e os erros no formato ficheiro:linha: mensagem. O contrato completo está em docs/mcp.md, no repositório.

Também podes gerar texto com um modelo, por endpoint compatível com a API de chat completions (OpenAI, Ollama, LM Studio, vLLM, llama.cpp):

export LAISSDOCS_BASE_URL="http://localhost:1234/v1"
export LAISSDOCS_MODEL="o-modelo-que-usas"
laiss-docs ai
laiss-docs generate relatorio --section introducao --instruction "acrescenta um exemplo"

Limites conhecidos

• Só A4 retrato. Outros formatos e orientação não estão previstos.
• O corpo são blocos JSON, não Markdown livre. A estrutura é escolhida num campo type; um ficheiro Markdown não se converte.
• Sem índice remissivo nem bibliografia. Há lista de referências num anexo, formatada como texto, sem citações numeradas no corpo.
• O design não se edita num documento. Um aspecto diferente é um parâmetro do doc.json, ou não é possível.

Licença

MIT, Laiss Labs. As fontes mantêm as suas licenças: Inter e JetBrains Mono, OFL 1.1.