normordis-pdf

Pure-Rust institutional PDF generation for the NORMAXIS mini-app framework.

This repository now contains the standalone normordis-pdf library crate along with two helper tools:

• tools/dotx2ndt
• tools/ndt-tools

A backup/restore helper is also available in scripts/.

Documentação bilingue / Bilingual documentation

Este repositório oferece documentação em português e inglês.

• Português: introdução e início rápido abaixo.
• English: see the English sections below.
• Manual: MANUAL.md é atualmente em português; MANUAL.en.md fornece um ponto de entrada em inglês.

Português (pt-PT)

normordis-pdf gera documentos formais — relatórios, cartas, certificados e formulários — diretamente em Rust, sem dependências externas (sem LaTeX, sem Typst, sem Chromium). Está orientado para padrões de administração pública portuguesa e inclui Liberation Sans para renderização pronta a usar.

Três modelos de composição, todos combináveis num único documento:

Início rápido

# Cargo.toml
[dependencies]
normordis-pdf = "1.0.0"

Documento Flow

use normordis_pdf::{DocumentBuilder, Paragraph, Section, Spacer, TextAlign};

let pdf = DocumentBuilder::new("Relatório Mensal")
    .push(Section::new("1. Introdução", 1))
    .push(Paragraph::new("Este relatório descreve…").align(TextAlign::Justify))
    .push(Spacer::new(6.0))
    .render_to_bytes()?;

std::fs::write("output.pdf", pdf)?;

English

Overview

normordis-pdf generates formal documents — reports, letters, certificates, forms — directly from Rust, with no external binary dependency (no LaTeX, no Typst, no Chromium). It targets Portuguese public administration document standards and embeds Liberation Sans for out-of-the-box rendering with real glyph metrics.

Three composition models, all mixable in a single document:

Quick Start

# Cargo.toml
[dependencies]
normordis-pdf = "1.0.0"

Flow document

use normordis_pdf::{DocumentBuilder, Paragraph, Section, Spacer, TextAlign};

let pdf = DocumentBuilder::new("Relatório Mensal")
    .push(Section::new("1. Introdução", 1))
    .push(Paragraph::new("Este relatório descreve…").align(TextAlign::Justify))
    .push(Spacer::new(6.0))
    .render_to_bytes()?;

std::fs::write("output.pdf", pdf)?;

NCRTF rich text

use normordis_pdf::DocumentBuilder;

let ncrtf = r#"{
  "ncrtf": "1.0",
  "blocks": [
    {"type":"heading","level":1,"children":[{"type":"text","text":"Título","marks":[]}]},
    {"type":"paragraph","alignment":"justify","children":[
      {"type":"text","text":"Texto com ","marks":[]},
      {"type":"text","text":"negrito","marks":["bold"]},
      {"type":"text","text":" e itálico.","marks":["italic"]}
    ]}
  ]
}"#;

let pdf = DocumentBuilder::new("Documento")
    .push_ncrtf(ncrtf)?
    .render_to_bytes()?;

NDT template

use normordis_pdf::DocumentBuilder;

const TEMPLATE: &str = include_str!("templates/oficio-nacional.ndt.json");

let data = serde_json::json!({
    "ndt_data": "1.0.0",
    "data": {
        "entidade": "Câmara Municipal de Exemplo",
        "numero": "2025/001",
        "data": "25 de Abril de 2025",
        "assunto": "Resposta a pedido de informação",
        "mensagem": "{\"ncrtf\":\"1.0\",\"blocks\":[{\"type\":\"paragraph\",\"alignment\":\"justify\",\"children\":[{\"type\":\"text\",\"text\":\"Informamos que o pedido foi recebido.\",\"marks\":[]}]}]}"
    }
}).to_string();

let pdf = DocumentBuilder::new("Ofício")
    .push_ndt(TEMPLATE, &data)?
    .render_to_bytes()?;

Features

Flow elements

Fixed Box elements

NCRTF v1.0 — rich text format

NCRTF (NORMAXIS Canonical Rich Text Format) is a JSON schema for inline-styled paragraphs. It is the interchange format between editors (such as @normaxis/nx-doc) and this renderer.

{
  "ncrtf": "1.0",
  "blocks": [
    {
      "type": "paragraph",
      "alignment": "justify",
      "children": [
        {"type": "text", "text": "Normal, ", "marks": []},
        {"type": "text", "text": "bold", "marks": ["bold"]},
        {"type": "text", "text": " and italic.", "marks": ["italic"]}
      ]
    },
    {
      "type": "list",
      "list_type": "bullet",
      "children": [
        {"indent": 0, "children": [{"type": "text", "text": "Item", "marks": []}]}
      ]
    }
  ]
}

Supported block types: paragraph, heading (levels 1–4), list (bullet / ordered / checklist).
Supported inline marks: bold, italic, underline, strikethrough, code.

NDT v1.0.0 — document templates

NDT (NORMAXIS Document Template) is a JSON-driven template format for institutional documents. Templates define a layout schema; runtime data is injected at render time.

Template file (*.ndt.json):

{
  "ndt": "1.0.0",
  "meta": { "title": "Relatório", "description": "…" },
  "placeholders": {
    "entity_name": { "type": "string", "required": true },
    "body":        { "type": "ncrtf",  "required": false }
  },
  "body": [
    { "type": "heading", "text": "{{entity_name}}", "level": 1 },
    {
      "type": "conditional",
      "condition": "body", "operator": "exists",
      "then": [{ "type": "rich_text", "content": "{{body}}", "source": "placeholder" }],
      "else": [{ "type": "paragraph", "text": "Sem conteúdo." }]
    }
  ]
}

Data file (*.ndt-data.json):

{
  "ndt_data": "1.0.0",
  "data": {
    "entity_name": "Câmara Municipal de Exemplo",
    "body": "{\"ncrtf\":\"1.0\",\"blocks\":[]}"
  }
}

Supported body element types: paragraph, heading, rich_text, table, list, image, spacer, horizontal_rule, page_break, fixed_text, fixed_image, fixed_line, fixed_box, zone_ref, conditional, repeat, include.

Supported conditional operators: exists, empty, eq, neq, gt, lt.

Bundled templates

Ready-to-use NDT templates are provided under examples/templates/:

Examples

Run any example with:

cargo run --example <name> -p normordis-pdf

Fonts

Four font families are embedded at compile time — Liberation Sans, Liberation Serif, Liberation Mono, and Libertinus Serif. No system fonts are required.

// Register any TTF/OTF font family — from bytes or from disk
let pdf = DocumentBuilder::new("Doc")
    .font_from_bytes(
        "MyFont",
        include_bytes!("assets/MyFont-Regular.ttf"),
        Some(include_bytes!("assets/MyFont-Bold.ttf")),
        None, None,
    )?
    .push(Paragraph::new("Custom font paragraph.").font_family("MyFont"))
    .render_to_bytes()?;

Key font APIs:

Common Word font names (Arial, Calibri, Times New Roman, Cambria, Consolas, etc.) are pre-registered as aliases to their Liberation equivalents.

Version constants

normordis_pdf::VERSION        // "1.0.0" — crate version
normordis_pdf::NDT_VERSION    // "1.0.0" — NDT engine version
normordis_pdf::NCRTF_VERSION  // "1.0"   — NCRTF parser version

API stability

All public items re-exported from normordis_pdf::* are considered stable from v1.0.0 onwards. Internal modules (normordis_pdf::template::*, normordis_pdf::richtext::*, etc.) are not stable and may change between minor versions.

License

EUPL-1.2 — see LICENSE or https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12.