---
seo_title: API Markdown in PDF: converti file Markdown in PDF | EnConvert
meta_desc: Converti Markdown in PDF via API REST. POST /v1/convert/markdown-to-pdf trasforma file .md in PDF con tabelle, evidenziazione del codice, header e footer.
keywords: markdown in pdf api, convertire markdown in pdf api, md in pdf api rest, api conversione markdown pdf, readme in pdf api, markdown in pdf con evidenziazione sintassi, markdown in pdf api python, markdown in pdf api node js
---

# API Markdown in PDF

L'API Markdown in PDF converte un file Markdown in un documento PDF con stile tramite `POST /v1/convert/markdown-to-pdf`. Il tuo file `.md` o `.markdown` viene prima renderizzato in HTML, con supporto per tabelle, blocchi di codice delimitati con evidenziazione della sintassi e indice. Il risultato viene poi convertito in PDF con WeasyPrint. La risposta è composta dai byte PDF grezzi per default, oppure da metadati JSON con un URL di download prefirmato quando `direct_download=false`; formati pagina personalizzati, margini, header, footer e output in scala di grigi sono disponibili tramite `pdf_options`.

---

## Endpoint

```
POST /v1/convert/markdown-to-pdf
```

**Content-Type:** `multipart/form-data`

**Input accettato:** file `.md` o `.markdown` (codificati in UTF-8)

**Formato di output:** `.pdf` (`application/pdf`)

---

## Autenticazione

Richiede una chiave API privata oppure un token JWT ottenuto da una chiave pubblica.

```
X-API-Key: sk_your_private_key
```

Oppure:

```
Authorization: Bearer <jwt_token>
```

---

## Parametri della richiesta

| Parametro | Tipo | Obbligatorio | Default | Descrizione |
|-----------|------|----------|---------|-------------|
| `file` | file | Sì | -- | Il file `.md` o `.markdown` da convertire. Deve essere codificato in UTF-8. |
| `output_filename` | `string` | No | Nome del file di input | Nome file di output personalizzato. L'estensione `.pdf` viene aggiunta automaticamente. |
| `direct_download` | `boolean` | No | `true` | Con `true`, restituisce i byte PDF grezzi. Con `false`, restituisce metadati JSON con un URL di download prefirmato. |
| `pdf_options` | `string` | No | `null` | Stringa JSON con le opzioni di configurazione del PDF. Vedi sotto. |

### Opzioni PDF

Passa una stringa JSON nel campo form `pdf_options`. Tutti i campi sono opzionali.

| Parametro | Tipo | Default | Descrizione |
|-----------|------|---------|-------------|
| `page_size` | `string` | `"A4"` | Formato pagina con nome. |
| `page_width` | `float` | `null` | Larghezza pagina personalizzata in millimetri. Larghezza e altezza vanno impostate insieme. |
| `page_height` | `float` | `null` | Altezza pagina personalizzata in millimetri. |
| `orientation` | `string` | `"portrait"` | `"portrait"` o `"landscape"`. |
| `margins` | `object` | `{"top": 10, "bottom": 10, "left": 10, "right": 10}` | Margini di pagina in millimetri. |
| `grayscale` | `boolean` | `false` | Converte l'output in scala di grigi. |
| `header` | `object` | `null` | Intestazione di pagina. Formato: `{"content": "<text>", "height": 15}`. |
| `footer` | `object` | `null` | Piè di pagina. Stesso formato dell'intestazione. |

**Formati pagina supportati:** `A0`-`A6`, `B0`-`B5`, `Letter`, `Legal`, `Tabloid`, `Ledger`

**Variabili template per header/footer:** `{{page}}`, `{{total_pages}}`, `{{date}}`, `{{title}}`, `{{url}}`

---

## Dettagli della conversione

La conversione avviene in due passaggi:

1. **Da Markdown a HTML** con Python-Markdown e le estensioni:
   - `tables` -- tabelle delimitate da pipe
   - `fenced_code` -- blocchi di codice con tripli backtick
   - `codehilite` -- evidenziazione della sintassi
   - `toc` -- indice tramite il marcatore `[TOC]`
   - `attr_list` -- attributi HTML con la sintassi `{.class #id}`

2. **Da HTML a PDF** con WeasyPrint e un foglio di stile integrato che fornisce:
   - Stack di font di sistema, layout centrato con larghezza massima di 800px
   - Blocchi di codice, tabelle, citazioni e immagini con stile
   - Dimensionamento responsive delle immagini (`max-width: 100%`)

Le `pdf_options` vengono iniettate come regole CSS `@page` prima del rendering.

---

## Risposta

### Download diretto (`direct_download=true`, default)

```
HTTP 200 OK
Content-Type: application/pdf
Content-Disposition: inline; filename="readme_20260405_123456789.pdf"
```

### Risposta con metadati (`direct_download=false`)

```json
{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/markdown-to-pdf/readme_20260405_123456789.pdf",
    "filename": "readme_20260405_123456789.pdf",
    "file_size": 34567,
    "conversion_time_seconds": 0.8
}
```

---

## Esempi di codice

### Python

```python
import requests
import json

with open("README.md", "rb") as f:
    response = requests.post(
        "https://api.enconvert.com/v1/convert/markdown-to-pdf",
        headers={"X-API-Key": "sk_your_private_key"},
        files={"file": ("README.md", f, "text/markdown")},
        data={
            "pdf_options": json.dumps({
                "page_size": "Letter",
                "margins": {"top": 25, "bottom": 25, "left": 20, "right": 20},
                "footer": {"content": "Page {{page}} of {{total_pages}}", "height": 10}
            })
        }
    )

with open("README.pdf", "wb") as out:
    out.write(response.content)
```

### Node.js

```javascript
const form = new FormData();
form.append("file", fs.createReadStream("README.md"));
form.append("pdf_options", JSON.stringify({
    page_size: "Letter",
    footer: { content: "Page {{page}} of {{total_pages}}", height: 10 }
}));

const response = await fetch("https://api.enconvert.com/v1/convert/markdown-to-pdf", {
    method: "POST",
    headers: { "X-API-Key": "sk_your_private_key" },
    body: form
});

fs.writeFileSync("README.pdf", Buffer.from(await response.arrayBuffer()));
```

### PHP

```php
$ch = curl_init("https://api.enconvert.com/v1/convert/markdown-to-pdf");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: sk_your_private_key"],
    CURLOPT_POSTFIELDS => [
        "file" => new CURLFile("README.md", "text/markdown"),
        "pdf_options" => json_encode(["page_size" => "Letter", "grayscale" => true])
    ]
]);
$pdf = curl_exec($ch);
curl_close($ch);
file_put_contents("README.pdf", $pdf);
```

### Go

```go
body := &bytes.Buffer{}
writer := multipart.NewWriter(body)

part, _ := writer.CreateFormFile("file", "README.md")
file, _ := os.Open("README.md")
io.Copy(part, file)

writer.WriteField("pdf_options", `{"page_size":"Letter","grayscale":true}`)
writer.Close()

req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/markdown-to-pdf", body)
req.Header.Set("Content-Type", writer.FormDataContentType())
req.Header.Set("X-API-Key", "sk_your_private_key")
resp, _ := http.DefaultClient.Do(req)
```

---

## Risposte di errore

| Stato | Condizione |
|--------|-----------|
| `400 Bad Request` | Il file non è un file `.md` o `.markdown` |
| `400 Bad Request` | Codifica Markdown non valida (attesa UTF-8) |
| `400 Bad Request` | Conversione da Markdown a PDF non riuscita |
| `400 Bad Request` | JSON `pdf_options` non valido |
| `401 Unauthorized` | Chiave API / token JWT mancante o non valido |
| `402 Payment Required` | Quota mensile di ops esaurita |
| `402 Payment Required` | Limite di storage raggiunto |
| `413 Payload Too Large` | Il file supera la dimensione massima prevista dal piano |

---

## Limiti

| Limite | Valore |
|-------|-------|
| Dimensione massima del file | Dipende dal piano (Founding: 5 MB) |
| Codifica di input | Solo UTF-8 |
| Estensioni accettate | `.md`, `.markdown` |
| Contenuto header/footer | Massimo 2000 caratteri |
| Conversioni mensili | Dipende dal piano |

## Domande frequenti

### Come converto un file Markdown in PDF con un'API REST?

Invia una richiesta `multipart/form-data` a `POST /v1/convert/markdown-to-pdf` con il file `.md` o `.markdown` (codificato in UTF-8) nel campo `file`, autenticandoti con `X-API-Key` o un JWT Bearer. Per default vengono restituiti direttamente i byte PDF grezzi.

### La conversione da Markdown a PDF supporta tabelle ed evidenziazione della sintassi del codice?

Sì. Il Markdown viene renderizzato con le estensioni di Python-Markdown, tra cui `tables` per le tabelle delimitate da pipe, `fenced_code` per i blocchi di codice con tripli backtick e `codehilite` per l'evidenziazione della sintassi, poi stilizzato da un foglio di stile integrato.

### Posso aggiungere un indice al PDF generato?

Sì. Inserisci un marcatore `[TOC]` nel tuo Markdown e l'estensione `toc` lo renderizza come indice nel documento di output.

### Come aggiungo i numeri di pagina a un PDF da Markdown?

Imposta un `footer` (o `header`) nel JSON `pdf_options`, ad es. `{"content": "Page {{page}} of {{total_pages}}", "height": 10}`. Le variabili template supportate sono `{{page}}`, `{{total_pages}}`, `{{date}}`, `{{title}}` e `{{url}}`.

### Perché la mia richiesta restituisce 400 Bad Request?

Cause comuni: il file non è `.md` o `.markdown`, il contenuto non è codificato in UTF-8, il campo `pdf_options` non è JSON valido oppure la conversione stessa è fallita. Controlla il messaggio di errore specifico nel body della risposta.