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#

Opzioni PDF#

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

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:
2. tables -- tabelle delimitate da pipe
3. fenced_code -- blocchi di codice con tripli backtick
4. codehilite -- evidenziazione della sintassi
5. toc -- indice tramite il marcatore [TOC]

6. attr_list -- attributi HTML con la sintassi {.class #id}

7. Da HTML a PDF con WeasyPrint e un foglio di stile integrato che fornisce:

8. Stack di font di sistema, layout centrato con larghezza massima di 800px
9. Blocchi di codice, tabelle, citazioni e immagini con stile
10. 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)#

{
    "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#

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#

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#

$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#

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#

Limiti#

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.