How to convert Delta JSON to Markdown using server-side Python

[joaopedrolourencoaffonso]

Hi everyone!

I'm building an open-source text editor for writers using Quill. I store my editor content locally as Quill Delta JSON files, and I've been working on a Python script to convert these Deltas directly into Markdown files.

Since Delta ops represent line formats (like headers or lists) on the trailing newline character, parsing them sequentially in Python required a bit of tweaking.

Here is my current implementation handling basic inline styling, headers, lists, and links:

import json
from pathlib import Path

file_path_entrada = Path("capitulos") / f"4-1-2.json";
file_path_saida =   Path("exemplo.md")

def quill_to_md(path_do_arquivo, path_arquivo_saida):
    string_final = "";
    with path_do_arquivo.open("r", encoding="utf-8") as file:
        rawChapterData = file.read()

    jsonData = json.loads(rawChapterData);
    lista = jsonData["ops"]
    tamanho_lista = len(lista);

    i = 0;
    while i < tamanho_lista:
        if (i + 1 >= tamanho_lista):
            string_final = string_final + lista[i]["insert"];
            break
        
        if 'header' in lista[i+1]['attributes']:
            if (lista[i+1]['attributes']['header'] == 1):
                hashes = "# ";
            
            if (lista[i+1]['attributes']['header'] == 2):
                hashes = "## ";
            
            if (lista[i+1]['attributes']['header'] == 3):
                hashes = "### ";

            string_final = string_final + hashes + lista[i]["insert"] + lista[i+1]["insert"];
        
        if 'list' in lista[i+1]['attributes']:
            # lista de elementos entre \n
            temp = lista[i]["insert"].split("\n");

            if (len(temp) > 1):
                item_da_lista = temp[len(temp) - 1];
                temp.pop();
                intermediario = "\n".join(temp);
                intermediario += "\n";
            else:
                intermediario = ""

            if (lista[i+1]['attributes']["list"] == "ordered"):
                marcador = "1. "
            
            if (lista[i+1]['attributes']["list"] == "bullet"):
                marcador = "- "
            
            string_final = string_final + intermediario + marcador + item_da_lista + lista[i+1]["insert"];

        if 'bold' in lista[i+1]['attributes']:
            string_final = string_final + lista[i]["insert"] + "**"  + lista[i+1]["insert"] + "**";
        
        if 'italic' in lista[i+1]['attributes']:
            string_final = string_final + lista[i]["insert"] + "*"  + lista[i+1]["insert"] + "*";
        
        if 'underline' in lista[i+1]['attributes']:
            string_final = string_final + lista[i]["insert"] + "<ins>"  + lista[i+1]["insert"] + "</ins>";
        
        if 'link' in lista[i+1]['attributes']:
            string_final = string_final + lista[i]["insert"] + f"<a href='${lista[i+1]['attributes']['link']}'>"  + lista[i+1]["insert"] + "</a>";
        
        i += 2;

    string_final = string_final.replace("\n", "\n\n");
    
    with path_arquivo_saida.open("w", encoding="utf-8") as file:
        file.write(string_final)

    return string_final

string_final = quill_to_md(file_path_entrada, file_path_saida);
print(string_final)

It works well for basic formatting (images are not supported yet).

I wanted to share this here for anyone working with Quill Deltas on a Python backend/tooling setup, and to ask:

• Are there edge cases in Delta structures I should watch out for when converting line formats vs. inline formats?
• Has anyone taken a similar approach for Python-side Delta parsing?

Any feedback or suggestions are welcome!

[joaopedrolourencoaffonso]

Here is the same thing, but to html.

def quill_to_html(json, path_do_arquivo):
    string_final = ""

    with path_do_arquivo.open("r", encoding="utf-8") as file:
        rawChapterData = file.read()

    jsonData = json.loads(rawChapterData)
    lista = jsonData["ops"]
    tamanho_lista = len(lista)

    i = 0

    while i < tamanho_lista:

        # Caso seja o último elemento
        if i + 1 >= tamanho_lista:
            string_final += lista[i]["insert"]
            break

        texto = lista[i]["insert"]
        proximo = lista[i + 1]

        atributos = proximo.get("attributes", {})

        # HEADER
        if "header" in atributos:
            if atributos["header"] == 1:
                primeiro_elemento = "<h1>"
                segundo_elemento = "</h1>"

            elif atributos["header"] == 2:
                primeiro_elemento = "<h2>"
                segundo_elemento = "</h2>"

            elif atributos["header"] == 3:
                primeiro_elemento = "<h3>"
                segundo_elemento = "</h3>"

            else:
                primeiro_elemento = ""
                segundo_elemento = ""

            string_final += (
                primeiro_elemento
                + texto
                + segundo_elemento
                + proximo["insert"]
            )

        # LISTA
        elif "list" in atributos:
            tipo_lista = atributos["list"]

            # Texto antes da última quebra de linha
            temp = texto.split("\n")

            if len(temp) > 1:
                item_da_lista = temp[-1]
                temp.pop()

                intermediario = "\n".join(temp)

                if intermediario:
                    string_final += intermediario + "\n"
            else:
                item_da_lista = texto

            if tipo_lista == "ordered":
                string_final += "<ol><li>" + item_da_lista + "</li></ol>"
            elif tipo_lista == "bullet":
                string_final += "<ul><li>" + item_da_lista + "</li></ul>"

            string_final += proximo["insert"]

        # BOLD
        elif "bold" in atributos:
            string_final += (
                texto
                + "<strong>"
                + proximo["insert"]
                + "</strong>"
            )

        # ITALIC
        elif "italic" in atributos:
            string_final += (
                texto
                + "<em>"
                + proximo["insert"]
                + "</em>"
            )

        # UNDERLINE
        elif "underline" in atributos:
            string_final += (
                texto
                + "<ins>"
                + proximo["insert"]
                + "</ins>"
            )

        # LINK
        elif "link" in atributos:
            link = atributos["link"]

            string_final += (
                texto
                + f"<a href='{link}'>"
                + proximo["insert"]
                + "</a>"
            )

        # Nenhum atributo
        else:
            string_final += texto + proximo["insert"]

        i += 2

    # Quebras de linha do Quill para HTML
    string_final = string_final.replace("\n", "<br>\n")

    return string_final

Can be very usefull as an intermediary for exporting to other formats.

[tevinch]

For text inserts, each op is a run, rather than half of a pair. For example, this is one paragraph with three runs:

{"ops":[{"insert":"A "},{"insert":"bold","attributes":{"bold":true}},{"insert":" ending\n"}]}

bold belongs to the second insert itself. The last op has no attributes. Pairing ops with i += 2 cannot reliably preserve either case.

I'd accumulate text runs until each newline, keeping each run's inline attributes, then choose the block format from that newline's header/list attributes. One insert can contain several newlines. In the HTML version, compose the inline wrappers instead of using elif, since bold, italic, underline and a link can coexist.

There is a runnable Python file-export example, sample chapter and tests here. It uses only the standard library and covers the default Snow toolbar's text formats, including mixed and nested lists. Unsupported formats and embeds fail explicitly before replacing an existing export.

The example uses Markdown blocks with inline HTML for styled text. Underline and explicit empty paragraphs therefore need a Markdown renderer that retains HTML. Checks include real Quill 2.0.3 getContents() snapshots, exporting and rendering the result, and editing a chapter before exporting again.

Use the saved complete getContents() document, including its final newline, rather than a text-change delta containing retain/delete. I hope this helps with the chapter export.

[joaopedrolourencoaffonso]

Thank you, the project is a bit frozen for now, but I will give it a try as soon as I return to it! Thanks!