udf-cli

udf-cli

Convert between HTML and UYAP UDF file format. Designed for AI agents that need to read and write UDF documents programmatically.

What is UDF?

UDF is the document format used by UYAP (Turkey's National Judiciary Informatics System). A UDF file is a ZIP archive containing a single content.xml file with text content, formatting, images, and tables encoded in a custom XML schema.

Install

npm install udf-cli

Or run directly:

npx udf-cli html2udf input.html output.udf

CLI Usage

HTML to UDF

udf-cli html2udf <input> [output]

Input accepts a file path, raw HTML string, or - for stdin. If input contains < it is treated as raw HTML. Output is optional — omit it to write to stdout.

# File to file
udf-cli html2udf input.html output.udf

# Raw HTML string to file
udf-cli html2udf '<p><strong>Merhaba</strong> dünya</p>' output.udf

# Raw HTML string to stdout
udf-cli html2udf '<p>Test</p>' > output.udf

# Stdin to file
cat input.html | udf-cli html2udf - output.udf

# Stdin to stdout (pipe-friendly)
echo '<p>Merhaba</p>' | udf-cli html2udf - > output.udf

UDF to HTML

udf-cli udf2html <input> [output]

Input accepts a file path or - for stdin. Output is optional — omit it to print HTML to stdout.

# File to file
udf-cli udf2html input.udf output.html

# File to stdout (agent-friendly — read UDF content directly)
udf-cli udf2html input.udf

# Stdin to stdout
cat input.udf | udf-cli udf2html -

# Full roundtrip via pipes
echo '<p>Test</p>' | udf-cli html2udf - | udf-cli udf2html -

Markdown to UDF

udf-cli md2udf <input> [output]

Input accepts a file path, raw Markdown string, or - for stdin.

# File to file
udf-cli md2udf input.md output.udf

# Stdin to file
cat input.md | udf-cli md2udf - output.udf

# Raw Markdown via stdin
echo '**Merhaba** dünya' | udf-cli md2udf - output.udf

Supported Markdown syntax for input:

• **bold** and *italic*, ***bold italic***
• # Heading 1 through ###### Heading 6
• 1. Numbered list and - Bulleted list (with nesting via indentation)
• Markdown tables (| col1 | col2 | with separator row)
• ![alt](data:image/png;base64,...) images

UDF to Markdown

udf-cli udf2md <input> [output]

Converts UDF to Markdown — ideal for AI agents that work better with Markdown than HTML. Tables become Markdown tables, bold/italic use **/* syntax, lists become 1./- items.

# Read a UDF file as Markdown (agent-friendly)
udf-cli udf2md input.udf

# Save as Markdown file
udf-cli udf2md input.udf output.md

Example output:

**T.C.**
**ANTALYA 3. ASLİYE HUKUK MAHKEMESİ**

**ESAS NO:** 2024/463
**DAVACI:** Mehmet Yılmaz

| **Sıra No** | **Açıklama** | **Toplam (TL)** |
| --- | --- | --- |
| 1 | Arsa değeri | 1.250.000,00 |
| 2 | Bina değeri | 990.000,00 |

1. Taşınmazın konumu
2. Yapının fiziksel durumu

- Dış cephe boyasında dökülme
- Çatı izolasyonunda bozulma

Library Usage

import { htmlToUdf, udfToHtml, udfToMarkdown, markdownToUdf } from 'udf-cli';

// HTML string → UDF buffer
const udfBuffer = await htmlToUdf('<p><strong>Mahkeme kararı</strong></p>');
fs.writeFileSync('document.udf', udfBuffer);

// UDF buffer → HTML string
const udf = fs.readFileSync('document.udf');
const html = await udfToHtml(udf);

// UDF buffer → Markdown string
const md = await udfToMarkdown(udf);

// Markdown string → UDF buffer
const udfFromMd = await markdownToUdf('**Başlık**\n\nParagraf metni');

Supported HTML Elements

HTML	UDF Mapping
<p>	Paragraph
<h1> - <h6>	Paragraph with bold, sizes 24/20/16/14/12/10 pt
<strong>, <b>	Bold text
<em>, <i>	Italic text
<u>	Underlined text
<span style="...">	Styled text (font, size, color, background)
<br>	Paragraph break
<img src="data:...">	Embedded image (base64 data URI)
<table>, <tr>, <td>, <th>	Table with borders (nested tables supported)
<ul>, <ol>, <li>	Bulleted / numbered lists
<div>	Block container

Supported CSS Properties

These inline styles are recognized on <p>, <span>, <td>:

• font-family — mapped to UDF font family
• font-size — supports px (converted to pt) and pt
• font-weight: bold — bold text
• font-style: italic — italic text
• text-decoration: underline — underlined text
• color — text color (hex, rgb, named colors)
• background-color — text/cell background
• text-align — left, center, right, justify
• vertical-align — top, middle, bottom (table cells)
• line-height — paragraph line spacing

Writing HTML for UDF Conversion

When generating HTML that will be converted to UDF, follow these guidelines:

Text Formatting

<p>Normal text</p>
<p><strong>Bold text</strong></p>
<p><em>Italic text</em></p>
<p><strong><em>Bold and italic</em></strong></p>
<p><span style="font-family:Arial; font-size:14pt; color:#FF0000">Custom styled text</span></p>

Images

Images must use base64 data URIs. Specify width and height in points:

<img src="data:image/png;base64,iVBORw0KGgo..." width="200" height="100">

Tables

<table>
  <tr>
    <td>Cell 1</td>
    <td>Cell 2</td>
  </tr>
  <tr>
    <td colspan="2">Merged cell</td>
  </tr>
</table>

Nested tables are supported:

<table>
  <tr>
    <td>
      <table>
        <tr><td>Inner cell</td></tr>
      </table>
    </td>
  </tr>
</table>

Lists

<ol>
  <li>First item</li>
  <li>Second item</li>
</ol>

<ul>
  <li>Bullet point</li>
  <li>Another point</li>
</ul>

Centered / Aligned Text

<p style="text-align:center">Centered paragraph</p>
<p style="text-align:right">Right-aligned paragraph</p>
<p style="text-align:justify">Justified paragraph</p>

UDF Format Reference

UDF files have this internal structure:

document.udf (ZIP archive)
└── content.xml

The XML schema:

<?xml version="1.0" encoding="UTF-8" ?>
<template format_id="1.8">
  <content><![CDATA[All document text here]]></content>
  <properties>
    <pageFormat mediaSizeName="1" leftMargin="42.52" rightMargin="28.35"
                topMargin="14.17" bottomMargin="14.17" paperOrientation="1" />
  </properties>
  <elements resolver="hvl-default">
    <paragraph Alignment="0">
      <content startOffset="0" length="5" family="Times New Roman"
               size="12" bold="true" foreground="-16777216" background="-1" />
    </paragraph>
    <table tableName="Sabit" columnCount="2" columnSpans="150,150" border="borderCell">
      <row rowName="row1" rowType="dataRow" border="borderCell">
        <cell colspan="1" align="top" fillColor="16777215"
              border="borderCell" borderSpec="15">
          <paragraph>...</paragraph>
        </cell>
      </row>
    </table>
  </elements>
</template>

Key details:

• Text offsets are rune-based (Unicode codepoints), not byte-based
• Colors are signed 32-bit ARGB integers (black = -16777216, white = -1)
• Alignment: 0 = left, 1 = center, 2 = right, 3 = justify
• Border spec: bitmask (top=1, right=2, bottom=4, left=8; all sides=15)
• Images: base64-encoded in imageData attribute, \uFFFC placeholder in text
• Empty paragraphs: \u200B (zero-width space) placeholder in text

Development

npm install
npm test          # run tests
npm run build     # compile TypeScript