JDFJDF/ docs

CLI — @uurtech/jdf-cli

Command-line tool for validating .jdf documents against the JSON Schema and converting source formats into JDF. Designed to be safe to drop into CI.

Install

# run on demand (no install)
npx @uurtech/jdf-cli validate doc.jdf

# or install globally
npm install -g @uurtech/jdf-cli
jdf --help

Commands

jdf validate <file.jdf>

Runs Ajv against spec/jdf-schema.json and reports path-level errors with warnings vs hard failures separated.

$ jdf validate spec/examples/hello-world.jdf

✓ Valid: hello-world.jdf
  Format:    1.0.0
  Title:     Hello, JDF
  Pages:     2
  Elements:  14

Failures look like:

$ jdf validate broken.jdf

✗ Invalid: broken.jdf
  /pages/0/elements/3/heading — must be one of [true, 1, 2, 3, 4, 5, 6]
  /pages/0/elements/5 — required property "type" missing

Exit code: 0 if valid, 1 if not. Drop into a CI step:

# .github/workflows/ci.yml
- run: npx @uurtech/jdf-cli validate docs/whitepaper.jdf

jdf import <file.{md,pdf}> [-o output.jdf]

Convert a Markdown or PDF file to a .jdf:

jdf import README.md                    # → README.jdf
jdf import README.md -o readme.jdf      # custom output
jdf import paper.pdf -o paper.jdf       # PDF

Markdown import uses pulldown-cmark with full GFM (tables, blockquotes, fenced code, links, images, task lists, hr, strikethrough). Bold/italic emit as richtext runs.

PDF import is currently a placeholder — it prints a hint to use the desktop Reader. The plan is to extract apps/reader/src/import/pdfToJdf.ts into a shared @uurtech/jdf-pdf-import package with a Node entry point so the CLI can run the same PDF.js-based extractor (positions, fonts, colors, vector shapes, embedded images).

Schema validation in CI

If your project generates .jdf files programmatically, validate them on every PR. Example workflow:

name: Validate JDF docs

on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npx @uurtech/jdf-cli validate docs/*.jdf