LibreKAT/Ocideck
LibreKAT/Ocideck
Watch
4
0
Fork
You've already forked Ocideck
 1
Code Issues Pull requests Projects Releases 21 Packages Activity Actions

Evalueer markdown_quill vervanging (17 maanden stale, onverifieerde uitgever) #1743

New issue
Closed
opened 2026-08-23 08:37:48 +00:00 by brenno · 2 comments
brenno commented 2026-08-23 08:37:48 +00:00
Owner
Copy link

Achtergrond

markdown_quill (4.3.0) is 17 maanden niet bijgewerkt en heeft een onverifieerde uitgever. Het pakket zet Markdown om naar Quill-Delta (en terug) voor de WYSIWYG-editor.

Gebruik in OciDeck

markdown_quill wordt gebruikt in meerdere bestanden voor de markdown↔Quill conversie die de WYSIWYG-editor mogelijk maakt:

  • lib/utils/markdown_quill_codec.dart (regels 3, 26) — de centrale codec
  • lib/widgets/markdown_editor/markdown_editor.dart (regel 11)
  • lib/widgets/markdown_editor/wysiwyg_notes_field.dart (regel 6)
  • lib/widgets/markdown_editor/timeline_table_embed_builder.dart (regel 3)
  • lib/widgets/markdown_editor/table_embed_builder.dart (regel 3)
  • lib/utils/timeline_table_embed_syntax.dart (regel 56)
  • lib/utils/pentest_block_embed_syntax.dart (regel 140)
  • lib/utils/image_embed_syntax.dart (regels 5, 39)
  • lib/services/latex/markdown_to_latex.dart (regel 9)
  • lib/widgets/shell/document_save_actions.dart (regel 16)

Het probleem

  1. 17 maanden zonder updates — mogelijk niet compatibel met toekomstige flutter_quill versies
  2. Onverifieerde uitgever — geen garanties over onderhoud
  3. flutter_quill zelf (11.5.1) is wel actief onderhouden (verified publisher, 3 maanden geleden bijgewerkt). Als flutter_quill breaking changes introduceert, is markdown_quill mogelijk niet tijdvolgend bij te werken.
  4. De markdown↔Quill conversie is kernfunctionaliteit voor de WYSIWYG-editor — als dit breekt, valt de editor.

Alternatieven

  1. Eigen codec bouwen — We hebben al lib/utils/markdown_quill_codec.dart als wrapper. We kunnen de conversielogica zelf implementeren met de markdown-package (7.3.1, actief) en flutter_quill's Delta-API. Dit elimineert de afhankelijkheid volledig.
  2. Fork van markdown_quill — Vendoren in third_party/ met eigen onderhoud, net als we met desktop_multi_window en screen_retriever_macos doen.
  3. Ander pakket — Zoeken naar een actiever alternatief (maar dit is een niche, er zijn weinig alternatieven).

Wat dit issue moet uitzoeken

  1. Hoeveel van markdown_quill's conversielogica gebruiken we echt? Is het een dunne wrapper of diepe integratie?
  2. Is een eigen codec haalbaar? De markdown-package kan Markdown naar AST parsen, en flutter_quill heeft een Delta-API. De brug daartussen is het werk.
  3. Hoeveel code zou een eigen codec kosten vergeleken met de huidige afhankelijkheid?
  4. Zijn er bekende bugs in markdown_quill 4.3.0 die we nu al werken omheen?

Prioriteit

Medium. Het werkt nu, maar de combinatie van 'onverifieerde uitgever' + '17 maanden stale' + 'kernfunctionaliteit' is een risico. Als flutter_quill een major bump doet, kan markdown_quill achterblijven en de WYSIWYG-editor breken.

## Achtergrond `markdown_quill` (4.3.0) is **17 maanden niet bijgewerkt** en heeft een **onverifieerde uitgever**. Het pakket zet Markdown om naar Quill-Delta (en terug) voor de WYSIWYG-editor. ## Gebruik in OciDeck `markdown_quill` wordt gebruikt in meerdere bestanden voor de markdown↔Quill conversie die de WYSIWYG-editor mogelijk maakt: - `lib/utils/markdown_quill_codec.dart` (regels 3, 26) — de centrale codec - `lib/widgets/markdown_editor/markdown_editor.dart` (regel 11) - `lib/widgets/markdown_editor/wysiwyg_notes_field.dart` (regel 6) - `lib/widgets/markdown_editor/timeline_table_embed_builder.dart` (regel 3) - `lib/widgets/markdown_editor/table_embed_builder.dart` (regel 3) - `lib/utils/timeline_table_embed_syntax.dart` (regel 56) - `lib/utils/pentest_block_embed_syntax.dart` (regel 140) - `lib/utils/image_embed_syntax.dart` (regels 5, 39) - `lib/services/latex/markdown_to_latex.dart` (regel 9) - `lib/widgets/shell/document_save_actions.dart` (regel 16) ## Het probleem 1. 17 maanden zonder updates — mogelijk niet compatibel met toekomstige `flutter_quill` versies 2. Onverifieerde uitgever — geen garanties over onderhoud 3. `flutter_quill` zelf (11.5.1) is wel actief onderhouden (verified publisher, 3 maanden geleden bijgewerkt). Als `flutter_quill` breaking changes introduceert, is `markdown_quill` mogelijk niet tijdvolgend bij te werken. 4. De markdown↔Quill conversie is kernfunctionaliteit voor de WYSIWYG-editor — als dit breekt, valt de editor. ## Alternatieven 1. **Eigen codec bouwen** — We hebben al `lib/utils/markdown_quill_codec.dart` als wrapper. We kunnen de conversielogica zelf implementeren met de `markdown`-package (7.3.1, actief) en `flutter_quill`'s Delta-API. Dit elimineert de afhankelijkheid volledig. 2. **Fork van markdown_quill** — Vendoren in `third_party/` met eigen onderhoud, net als we met `desktop_multi_window` en `screen_retriever_macos` doen. 3. **Ander pakket** — Zoeken naar een actiever alternatief (maar dit is een niche, er zijn weinig alternatieven). ## Wat dit issue moet uitzoeken 1. Hoeveel van `markdown_quill`'s conversielogica gebruiken we echt? Is het een dunne wrapper of diepe integratie? 2. Is een eigen codec haalbaar? De `markdown`-package kan Markdown naar AST parsen, en `flutter_quill` heeft een Delta-API. De brug daartussen is het werk. 3. Hoeveel code zou een eigen codec kosten vergeleken met de huidige afhankelijkheid? 4. Zijn er bekende bugs in `markdown_quill` 4.3.0 die we nu al werken omheen? ## Prioriteit Medium. Het werkt nu, maar de combinatie van 'onverifieerde uitgever' + '17 maanden stale' + 'kernfunctionaliteit' is een risico. Als `flutter_quill` een major bump doet, kan `markdown_quill` achterblijven en de WYSIWYG-editor breken.
brenno commented 2026-08-23 08:40:43 +00:00
Author
Owner
Copy link

Licentie- en taalonderzoek

Huidige package

Package Licentie Taal Opmerking
markdown_quill MIT Dart (100%) Pure Dart, geen native code. Converteert Markdown ↔ Quill Delta. Onverifieerde uitgever, 17 maanden stale.

Alternatief 1: Eigen codec bouwen

Als we een eigen markdown↔Quill codec bouwen, gebruiken we packages die we al hebben:

Package Licentie Taal Opmerking
markdown BSD-3-Clause Dart (100%) Officieel Dart-team pakket (dart-lang/tools). Al in gebruik in OciDeck. Parseert Markdown naar AST.
flutter_quill MIT Dart (primair), +Kotlin, Swift, Objective-C, C++, CMake, HTML Al in gebruik in OciDeck (verified publisher, actief onderhouden). De Delta-API is pure Dart.

Alternatief 2: Fork van markdown_quill (vendoren)

Package Licentie Taal Opmerking
markdown_quill (geforked) MIT Dart (100%) We vendoren de code in third_party/ met eigen onderhoud, net als desktop_multi_window en screen_retriever_macos. MIT licentie blijft gelden.

Conclusie

  • markdown_quill: MIT, pure Dart. Licentie geen probleem, maar wel stale en onverifieerd.
  • Eigen codec: BSD-3-Clause (markdown) + MIT (flutter_quill). Beide al in gebruik, geen nieuwe afhankelijkheid. Licentiegewijs de schoonste optie — we verwijderen een afhankelijkheid in plaats van er een toe te voegen.
  • Fork: MIT, pure Dart. Licentie identiek aan huidige. We nemen het onderhoud zelf over.

Alle opties zijn licentie-technisch haalbaar. De taal is in alle gevallen pure Dart — geen native code, geen platform-specifieke complicaties.

## Licentie- en taalonderzoek ### Huidige package | Package | Licentie | Taal | Opmerking | |---|---|---|---| | **markdown_quill** | MIT | Dart (100%) | Pure Dart, geen native code. Converteert Markdown ↔ Quill Delta. Onverifieerde uitgever, 17 maanden stale. | ### Alternatief 1: Eigen codec bouwen Als we een eigen markdown↔Quill codec bouwen, gebruiken we packages die we al hebben: | Package | Licentie | Taal | Opmerking | |---|---|---|---| | **markdown** | BSD-3-Clause | Dart (100%) | Officieel Dart-team pakket (dart-lang/tools). Al in gebruik in OciDeck. Parseert Markdown naar AST. | | **flutter_quill** | MIT | Dart (primair), +Kotlin, Swift, Objective-C, C++, CMake, HTML | Al in gebruik in OciDeck (verified publisher, actief onderhouden). De Delta-API is pure Dart. | ### Alternatief 2: Fork van markdown_quill (vendoren) | Package | Licentie | Taal | Opmerking | |---|---|---|---| | **markdown_quill** (geforked) | MIT | Dart (100%) | We vendoren de code in `third_party/` met eigen onderhoud, net als `desktop_multi_window` en `screen_retriever_macos`. MIT licentie blijft gelden. | ### Conclusie - **markdown_quill**: MIT, pure Dart. Licentie geen probleem, maar wel stale en onverifieerd. - **Eigen codec**: BSD-3-Clause (markdown) + MIT (flutter_quill). Beide al in gebruik, geen nieuwe afhankelijkheid. Licentiegewijs de schoonste optie — we verwijderen een afhankelijkheid in plaats van er een toe te voegen. - **Fork**: MIT, pure Dart. Licentie identiek aan huidige. We nemen het onderhoud zelf over. Alle opties zijn licentie-technisch haalbaar. De taal is in alle gevallen pure Dart — geen native code, geen platform-specifieke complicaties.
brenno commented 2026-08-23 08:58:08 +00:00
Author
Owner
Copy link

Evaluatie: markdown_quill vervanging

Onderzoek uitgevoerd op branch eval/markdown-quill-1743. Hieronder de antwoorden op de vier vragen uit het issue, gevolgd door een aanbeveling.

1. Hoeveel van markdown_quill gebruiken we echt?

Geen dunne wrapper — we gebruiken de volledige conversie-engine.

De package (markdown_quill-4.3.0) is 1169 regels verdeeld over 6 bestanden:

Bestand Regels Wat het doet Gebruik in OciDeck
markdown_to_delta.dart 464 Markdown AST → Quill Delta (heenweg) Volledig — MarkdownToDelta in de codec met 7 custom embeds
delta_to_markdown.dart 513 Quill Delta → Markdown (terugweg) Volledig — DeltaToMarkdown in de codec met custom embed handlers + custom italic
embeddable_table_syntax.dart 117 GFM-tabel als x-embed-table embed Volledig — EmbeddableTable + EmbeddableTableSyntax direct gebruikt
utils.dart 59 transform() (newline na embed) + horizontalRule Volledig — transform() wordt intern door DeltaToMarkdown.convert() aangeroepen
custom_quill_attributes.dart 11 CodeBlockLanguageAttribute Volledig — gebruikt in markdown_to_delta.dart voor code-blok-taal
markdown_quill.dart 5 Barrel export —

Directe import-plekken (4):

  • lib/utils/markdown_quill_codec.dart — de centrale codec. Gebruikt MarkdownToDelta, DeltaToMarkdown, CustomAttributeHandler, EmbeddableTable, EmbeddableTableSyntax.
  • lib/widgets/markdown_editor/table_embed_builder.dart — gebruikt alleen EmbeddableTable (de BlockEmbed-subclass + tableType constante).
  • lib/widgets/markdown_editor/timeline_table_embed_builder.dart — gebruikt alleen EmbeddableTable.
  • test/markdown_quill_codec_test.dart — gebruikt EmbeddableTable.tableType, EmbeddableToc.tocType.

De overige referenties in het issue (markdown_editor.dart, wysiwyg_notes_field.dart, document_save_actions.dart, etc.) importeren het lokale markdown_quill_codec.dart, niet de package direct.

Conclusie: OciDeck gebruikt de volledige conversie-engine (977 regels heen+terug) plus de tabel-embed (117 regels). Het is geen dunne wrapper die we makkelijk kunnen missen — het is de kern van de WYSIWYG-brug.

2. Is een eigen codec haalbaar?

Ja, maar het is geen klein project. De markdown-package (al aanwezig, ^7.3.1) levert de AST. De flutter_quill Delta-API (al aanwezig, ^11.5.1) levert het doel. De brug ertussen is precies het werk dat de package nu doet.

OciDeck heeft al bewezen dat het patroon werkt: lib/services/latex/markdown_to_latex.dart doet hetzelfde (Markdown AST → LaTeX) met dezelfde markdown-package als AST-parser. Maar LaTeX is een andere output met eenvoudigere regels. De Quill-Delta heeft specifieke complexiteit:

  • Block-attribute-exclusivity: header, list, code-block en blockquote sluiten elkaar uit. De package heeft niet-triviale logica (_effectiveBlockAttrs, 30 regels) om dit af te dwingen.
  • Newline-insertie tussen blokken: wanneer en hoe newlines geinsert worden is subtiel — voor/na embeds, na hr, tussen opeenvolgende blockquotes, in geneste lijsten. De package heeft ~60 regels (_insertNewLineBefore/AfterElementIfNeeded) voor deze logica.
  • GFM-spec text-trimming: leading spaces na bepaalde tags, soft line break handling. ~25 regels (_trimTextToMdSpec).
  • Inline-opmaak samenvoegen: bold/italic/strike/code/link met before/after-content handlers die voorkomen dat aangrenzende spans dubbele markers krijgen. ~60 regels per richting.
  • Delta → Markdown boom-wandeling: een eigen visitor over Quill's Root/Block/Line/QuillText/Embed node-hiërarchie. Dit is de kwetsbare kant: de package importeert met // ignore_for_file: implementation_imports en gebruikt package:flutter_quill/quill_delta.dart — als flutter_quill deze interne structuur hertekent, breekt dit.

Haalbaarheid: Ja. Het is vertaalwerk, niet onderzoek. De markdown-package API is stabiel (dart-lang team). De flutter_quill Delta-API is publiek en gedocumenteerd. De node-hiërarchie (Root/Block/Line/QuillText/Embed) is publiek via flutter_quill.dart — de implementation_imports-flag staat er voor quill_delta.dart, niet voor de node-klassen.

3. Hoeveel code zou een eigen codec kosten?

Schatting: ~950-1150 regels, vergelijkbaar met de package zelf. Dat is logisch — we zouden in essentie de package herschrijven, toegespitst op wat OciDeck gebruikt.

Component Package regels Eigen codec schatting Besparing
MarkdownToDelta 464 ~400 softLineBreak weglaten, customElementToInlineAttribute weglaten (ongebruikt)
DeltaToMarkdown 513 ~420 escapeSpecialCharactersRelaxed weglaten, _prefixNumber vereenvoudigen, custom italic handler inbouwen
EmbeddableTable + syntax 117 ~117 1:1 over te nemen (MIT) — of herschrijven zonder charcode
CodeBlockLanguageAttribute 11 ~11 1:1
utils (transform/hr) 59 ~30 Vereenvoudigd — alleen de embed-types die OciDeck gebruikt
Totaal 1164 ~980 ~15% kleiner

Vergelijking: de huidige afhankelijkheid is 1169 regels. Een eigen codec zou ongeveer even groot zijn. Het verschil is niet in regels maar in controle: we ondersteunen alleen wat OciDeck nodig heeft, en we kunnen bugs direct fixen.

Bijkomend voordeel: de charcode-dependency (alleen gebruikt in embeddable_table_syntax.dart voor $pipe, $space, $tab — simpele code-unit constanten) kan vervallen.

4. Bekende bugs in markdown_quill 4.3.0 waar we omheen werken?

Ja, zeven workarounds in OciDeck-code, plus 10 open issues upstream.

Workarounds in OciDeck

# Bug Workaround Bestand
a Image alt-tekst verloren — package maakt image-embed met alleen bron. README zegt dit expliciet: "Currently this convertor doesn't support image alts" EmbeddableMarkdownImage draagt hele markdown als embed image_embed_syntax.dart
b Image-embed laat schrijfvlak omvallen — geen EmbedBuilder voor image-type, Quill werpt UnimplementedError Zelfde custom image-embed + DividerEmbedBuilder voor divider-type image_embed_syntax.dart, divider_embed_builder.dart
c - - - i.p.v. --- — DeltaToMarkdown schrijft thematische breuk met spaties _writtenOutRule normaliseert naar --- markdown_quill_codec.dart regel 111, 118
d | escaped in tabelcellen — escapeSpecialCharacters breekt tabelstructuur (één cel → twee) _normalizeQuillOutput: tabelregels via opslagnormalisatie, andere regels via schermnormalisatie markdown_quill_codec.dart regel 126-136
e Cursief met _ i.p.v. * — package default gebruikt _ CustomAttributeHandler overschrijft met * markdown_quill_codec.dart regel 87-98
f GFM-tabellen vallen uit elkaar — zonder EmbeddableTableSyntax worden tabellen losse woorden in de rijke-tekstlaag EmbeddableTableSyntax vóór standaard-syntax geregistreerd markdown_quill_codec.dart regel 54
g Voetnoten, TOC, pentest-blokken breken visuele modus — geen standaardondersteuning 5 eigen embed-syntaxen + embed-builders footnote_embed_syntax.dart, toc_embed_syntax.dart, pentest_block_embed_syntax.dart, timeline_table_embed_syntax.dart

Open issues upstream (10, waarvan 5 relevant)

Issue Datum Beschrijving Treft OciDeck?
#33 sep 2024 Lijsten — elke bullet wordt 1. i.p.v. 2., 3. Mogelijk — OciDeck gebruikt genummerde lijsten
#22 apr 2024 Block quotes niet correct geconverteerd Mogelijk
#20 mrt 2024 Line breaks niet geconverteerd Mogelijk — OciDeck heeft eigen newline-logica
#36 okt 2024 Force new line characters Mogelijk
#39 jan 2025 Table markdown OciDeck heeft eigen tabel-embed, dus waarschijnlijk niet

Upstream activiteit

  • Laatste pub.dev-publicatie: 17 maanden geleden (mrt 2025).
  • Laatste GitHub-commits: jan 2026 ("update vga", "fix: add test for 27") — maar niet naar pub.dev gepubliceerd.
  • Issue-aanmaken is restricted op de repo.
  • 24 stars, 67 forks, 85 commits totaal.
  • Publisher op pub.dev: "unverified uploader".

Aanbeveling

Fork / vendoren als korte-termijn actie; eigen codec als langetermijndoel in een apart issue.

Fork / vendoren (nu, kleinste diff)

Kopieer de 1169 regels naar third_party/markdown_quill/ met path:-dependency, net als desktop_multi_window en screen_retriever_macos.

Voordelen:

  • Kleinste werk — kopiëren + pubspec.yaml aanpassen (2 regels: markdown_quill: ^4.3.0 → markdown_quill: path: third_party/markdown_quill).
  • API verandert niet → geen call-site wijzigingen.
  • Elimineert "onverifieerde uitgever" + "stale" risico onmiddellijk.
  • We kennen nu alle 7 bugs en workarounds — in een fork kunnen we ze direct aan de bron fixen in plaats van eromheen te werken.
  • charcode-dependency kan vervallen (herschrijf embeddable_table_syntax.dart zonder charcode — het zijn 3 simpele constanten).
  • MIT-licentie blijft gelden; MODIFICATIONS.md documenteert onze wijzigingen, net als bij de andere vendored packages.

Nadeel: we nemen 1169 regels onderhoud over. Maar we onderhouden er nu al 7 workarounds voor — in een fork zijn dat 7 fixes in plaats van 7 workarounds.

Eigen codec bouwen (later, apart issue)

Herschrijf de conversie-engine met markdown + flutter_quill Delta-API, ~980 regels, geen externe afhankelijkheid meer.

Voordelen:

  • Verwijdert de afhankelijkheid volledig.
  • Alleen wat OciDeck nodig heeft — geen dode code.
  • Volledige controle over conversiegedrag.

Nadeel: ~980 regels nieuw code + testdekking. Het is een herschrijving, geen refactor. Het verdient een eigen issue met een spike om de haalbaarheid te bevestigen (bijv. eerst alleen DeltaToMarkdown herschrijven en de package's MarkdownToDelta behouden, of andersom).

Waarom niet behouden?

Het werkt nu, maar het risico is reëel: flutter_quill is actief (verified publisher, 3 maanden geleden bijgewerkt). Als flutter_quill een major bump doet die de Node/Root/Block/Line/QuillText/Embed-hiërarchie of quill_delta.dart raakt, is markdown_quill mogelijk niet tijdvolgend bij te werken — 17 maanden stale, unverified uploader, restricted issues. De WYSIWYG-editor is kernfunctionaliteit.

Volgorde

  1. Nu: Fork naar third_party/markdown_quill/ (dit issue, ~1 PR).
  2. Daarna: Fix de 7 bekende bugs in de fork (zelfde issue of opvolg-issue).
  3. Langetermijn: Eigen codec in een apart issue met spike.

Als de fork er is, is de drempel voor de eigen codec lager: we hebben de code lokaal, kunnen hem stap voor stap vervangen, en de tests (10415+) vangen elke regressie.

## Evaluatie: markdown_quill vervanging Onderzoek uitgevoerd op branch `eval/markdown-quill-1743`. Hieronder de antwoorden op de vier vragen uit het issue, gevolgd door een aanbeveling. --- ### 1. Hoeveel van markdown_quill gebruiken we echt? **Geen dunne wrapper — we gebruiken de volledige conversie-engine.** De package (`markdown_quill-4.3.0`) is 1169 regels verdeeld over 6 bestanden: | Bestand | Regels | Wat het doet | Gebruik in OciDeck | |---|---|---|---| | `markdown_to_delta.dart` | 464 | Markdown AST → Quill Delta (heenweg) | **Volledig** — `MarkdownToDelta` in de codec met 7 custom embeds | | `delta_to_markdown.dart` | 513 | Quill Delta → Markdown (terugweg) | **Volledig** — `DeltaToMarkdown` in de codec met custom embed handlers + custom italic | | `embeddable_table_syntax.dart` | 117 | GFM-tabel als `x-embed-table` embed | **Volledig** — `EmbeddableTable` + `EmbeddableTableSyntax` direct gebruikt | | `utils.dart` | 59 | `transform()` (newline na embed) + `horizontalRule` | **Volledig** — `transform()` wordt intern door `DeltaToMarkdown.convert()` aangeroepen | | `custom_quill_attributes.dart` | 11 | `CodeBlockLanguageAttribute` | **Volledig** — gebruikt in `markdown_to_delta.dart` voor code-blok-taal | | `markdown_quill.dart` | 5 | Barrel export | — | **Directe import-plekken (4):** - `lib/utils/markdown_quill_codec.dart` — de centrale codec. Gebruikt `MarkdownToDelta`, `DeltaToMarkdown`, `CustomAttributeHandler`, `EmbeddableTable`, `EmbeddableTableSyntax`. - `lib/widgets/markdown_editor/table_embed_builder.dart` — gebruikt alleen `EmbeddableTable` (de `BlockEmbed`-subclass + `tableType` constante). - `lib/widgets/markdown_editor/timeline_table_embed_builder.dart` — gebruikt alleen `EmbeddableTable`. - `test/markdown_quill_codec_test.dart` — gebruikt `EmbeddableTable.tableType`, `EmbeddableToc.tocType`. De overige referenties in het issue (markdown_editor.dart, wysiwyg_notes_field.dart, document_save_actions.dart, etc.) importeren het **lokale** `markdown_quill_codec.dart`, niet de package direct. **Conclusie:** OciDeck gebruikt de volledige conversie-engine (977 regels heen+terug) plus de tabel-embed (117 regels). Het is geen dunne wrapper die we makkelijk kunnen missen — het is de kern van de WYSIWYG-brug. --- ### 2. Is een eigen codec haalbaar? **Ja, maar het is geen klein project.** De `markdown`-package (al aanwezig, ^7.3.1) levert de AST. De `flutter_quill` Delta-API (al aanwezig, ^11.5.1) levert het doel. De brug ertussen is precies het werk dat de package nu doet. OciDeck heeft al bewezen dat het patroon werkt: `lib/services/latex/markdown_to_latex.dart` doet hetzelfde (Markdown AST → LaTeX) met dezelfde `markdown`-package als AST-parser. Maar LaTeX is een andere output met eenvoudigere regels. De Quill-Delta heeft specifieke complexiteit: - **Block-attribute-exclusivity**: header, list, code-block en blockquote sluiten elkaar uit. De package heeft niet-triviale logica (`_effectiveBlockAttrs`, 30 regels) om dit af te dwingen. - **Newline-insertie tussen blokken**: wanneer en hoe newlines geinsert worden is subtiel — voor/na embeds, na `hr`, tussen opeenvolgende blockquotes, in geneste lijsten. De package heeft ~60 regels (`_insertNewLineBefore/AfterElementIfNeeded`) voor deze logica. - **GFM-spec text-trimming**: leading spaces na bepaalde tags, soft line break handling. ~25 regels (`_trimTextToMdSpec`). - **Inline-opmaak samenvoegen**: bold/italic/strike/code/link met before/after-content handlers die voorkomen dat aangrenzende spans dubbele markers krijgen. ~60 regels per richting. - **Delta → Markdown boom-wandeling**: een eigen visitor over Quill's `Root`/`Block`/`Line`/`QuillText`/`Embed` node-hiërarchie. Dit is de kwetsbare kant: de package importeert met `// ignore_for_file: implementation_imports` en gebruikt `package:flutter_quill/quill_delta.dart` — als flutter_quill deze interne structuur hertekent, breekt dit. **Haalbaarheid:** Ja. Het is vertaalwerk, niet onderzoek. De `markdown`-package API is stabiel (dart-lang team). De `flutter_quill` Delta-API is publiek en gedocumenteerd. De node-hiërarchie (`Root`/`Block`/`Line`/`QuillText`/`Embed`) is publiek via `flutter_quill.dart` — de `implementation_imports`-flag staat er voor `quill_delta.dart`, niet voor de node-klassen. --- ### 3. Hoeveel code zou een eigen codec kosten? **Schatting: ~950-1150 regels, vergelijkbaar met de package zelf.** Dat is logisch — we zouden in essentie de package herschrijven, toegespitst op wat OciDeck gebruikt. | Component | Package regels | Eigen codec schatting | Besparing | |---|---|---|---| | MarkdownToDelta | 464 | ~400 | `softLineBreak` weglaten, `customElementToInlineAttribute` weglaten (ongebruikt) | | DeltaToMarkdown | 513 | ~420 | `escapeSpecialCharactersRelaxed` weglaten, `_prefixNumber` vereenvoudigen, custom italic handler inbouwen | | EmbeddableTable + syntax | 117 | ~117 | 1:1 over te nemen (MIT) — of herschrijven zonder `charcode` | | CodeBlockLanguageAttribute | 11 | ~11 | 1:1 | | utils (transform/hr) | 59 | ~30 | Vereenvoudigd — alleen de embed-types die OciDeck gebruikt | | **Totaal** | **1164** | **~980** | ~15% kleiner | Vergelijking: de huidige afhankelijkheid is 1169 regels. Een eigen codec zou ongeveer even groot zijn. Het verschil is niet in regels maar in controle: we ondersteunen alleen wat OciDeck nodig heeft, en we kunnen bugs direct fixen. **Bijkomend voordeel:** de `charcode`-dependency (alleen gebruikt in `embeddable_table_syntax.dart` voor `$pipe`, `$space`, `$tab` — simpele code-unit constanten) kan vervallen. --- ### 4. Bekende bugs in markdown_quill 4.3.0 waar we omheen werken? **Ja, zeven workarounds in OciDeck-code, plus 10 open issues upstream.** #### Workarounds in OciDeck | # | Bug | Workaround | Bestand | |---|---|---|---| | a | **Image alt-tekst verloren** — package maakt `image`-embed met alleen bron. README zegt dit expliciet: "Currently this convertor doesn't support image alts" | `EmbeddableMarkdownImage` draagt hele markdown als embed | `image_embed_syntax.dart` | | b | **Image-embed laat schrijfvlak omvallen** — geen `EmbedBuilder` voor `image`-type, Quill werpt `UnimplementedError` | Zelfde custom image-embed + `DividerEmbedBuilder` voor `divider`-type | `image_embed_syntax.dart`, `divider_embed_builder.dart` | | c | **`- - -` i.p.v. `---`** — `DeltaToMarkdown` schrijft thematische breuk met spaties | `_writtenOutRule` normaliseert naar `---` | `markdown_quill_codec.dart` regel 111, 118 | | d | **`\|` escaped in tabelcellen** — `escapeSpecialCharacters` breekt tabelstructuur (één cel → twee) | `_normalizeQuillOutput`: tabelregels via opslagnormalisatie, andere regels via schermnormalisatie | `markdown_quill_codec.dart` regel 126-136 | | e | **Cursief met `_` i.p.v. `*`** — package default gebruikt `_` | `CustomAttributeHandler` overschrijft met `*` | `markdown_quill_codec.dart` regel 87-98 | | f | **GFM-tabellen vallen uit elkaar** — zonder `EmbeddableTableSyntax` worden tabellen losse woorden in de rijke-tekstlaag | `EmbeddableTableSyntax` vóór standaard-syntax geregistreerd | `markdown_quill_codec.dart` regel 54 | | g | **Voetnoten, TOC, pentest-blokken breken visuele modus** — geen standaardondersteuning | 5 eigen embed-syntaxen + embed-builders | `footnote_embed_syntax.dart`, `toc_embed_syntax.dart`, `pentest_block_embed_syntax.dart`, `timeline_table_embed_syntax.dart` | #### Open issues upstream (10, waarvan 5 relevant) | Issue | Datum | Beschrijving | Treft OciDeck? | |---|---|---|---| | [#33](https://github.com/TarekkMA/markdown_quill/issues/33) | sep 2024 | Lijsten — elke bullet wordt `1.` i.p.v. `2.`, `3.` | Mogelijk — OciDeck gebruikt genummerde lijsten | | [#22](https://github.com/TarekkMA/markdown_quill/issues/22) | apr 2024 | Block quotes niet correct geconverteerd | Mogelijk | | [#20](https://github.com/TarekkMA/markdown_quill/issues/20) | mrt 2024 | Line breaks niet geconverteerd | Mogelijk — OciDeck heeft eigen newline-logica | | [#36](https://github.com/TarekkMA/markdown_quill/issues/36) | okt 2024 | Force new line characters | Mogelijk | | [#39](https://github.com/TarekkMA/markdown_quill/issues/39) | jan 2025 | Table markdown | OciDeck heeft eigen tabel-embed, dus waarschijnlijk niet | #### Upstream activiteit - Laatste pub.dev-publicatie: **17 maanden geleden** (mrt 2025). - Laatste GitHub-commits: **jan 2026** ("update vga", "fix: add test for 27") — maar **niet naar pub.dev gepubliceerd**. - Issue-aanmaken is **restricted** op de repo. - 24 stars, 67 forks, 85 commits totaal. - Publisher op pub.dev: **"unverified uploader"**. --- ## Aanbeveling **Fork / vendoren als korte-termijn actie; eigen codec als langetermijndoel in een apart issue.** ### Fork / vendoren (nu, kleinste diff) Kopieer de 1169 regels naar `third_party/markdown_quill/` met `path:`-dependency, net als `desktop_multi_window` en `screen_retriever_macos`. **Voordelen:** - Kleinste werk — kopiëren + `pubspec.yaml` aanpassen (2 regels: `markdown_quill: ^4.3.0` → `markdown_quill: path: third_party/markdown_quill`). - API verandert niet → geen call-site wijzigingen. - Elimineert "onverifieerde uitgever" + "stale" risico onmiddellijk. - We kennen nu alle 7 bugs en workarounds — in een fork kunnen we ze direct aan de bron fixen in plaats van eromheen te werken. - `charcode`-dependency kan vervallen (herschrijf `embeddable_table_syntax.dart` zonder `charcode` — het zijn 3 simpele constanten). - MIT-licentie blijft gelden; `MODIFICATIONS.md` documenteert onze wijzigingen, net als bij de andere vendored packages. **Nadeel:** we nemen 1169 regels onderhoud over. Maar we onderhouden er nu al 7 workarounds voor — in een fork zijn dat 7 fixes in plaats van 7 workarounds. ### Eigen codec bouwen (later, apart issue) Herschrijf de conversie-engine met `markdown` + `flutter_quill` Delta-API, ~980 regels, geen externe afhankelijkheid meer. **Voordelen:** - Verwijdert de afhankelijkheid volledig. - Alleen wat OciDeck nodig heeft — geen dode code. - Volledige controle over conversiegedrag. **Nadeel:** ~980 regels nieuw code + testdekking. Het is een herschrijving, geen refactor. Het verdient een eigen issue met een spike om de haalbaarheid te bevestigen (bijv. eerst alleen `DeltaToMarkdown` herschrijven en de package's `MarkdownToDelta` behouden, of andersom). ### Waarom niet behouden? Het werkt nu, maar het risico is reëel: `flutter_quill` is actief (verified publisher, 3 maanden geleden bijgewerkt). Als flutter_quill een major bump doet die de `Node`/`Root`/`Block`/`Line`/`QuillText`/`Embed`-hiërarchie of `quill_delta.dart` raakt, is `markdown_quill` mogelijk niet tijdvolgend bij te werken — 17 maanden stale, unverified uploader, restricted issues. De WYSIWYG-editor is kernfunctionaliteit. ### Volgorde 1. **Nu:** Fork naar `third_party/markdown_quill/` (dit issue, ~1 PR). 2. **Daarna:** Fix de 7 bekende bugs in de fork (zelfde issue of opvolg-issue). 3. **Langetermijn:** Eigen codec in een apart issue met spike. Als de fork er is, is de drempel voor de eigen codec lager: we hebben de code lokaal, kunnen hem stap voor stap vervangen, en de tests (10415+) vangen elke regressie.
brenno 2026-08-23 13:51:38 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
v0.5.0
v0.4.10
v0.4.9
v0.4.8
v0.4.7
v0.4.6
v0.4.5
v0.4.4
v0.4.3
v0.4.2
v0.4.1
v0.4.0
v0.3.6
v0.3.5
v0.3.4
v0.3.3
v0.3.2
v0.3.1
v0.3.0
v0.2.0
v0.1.3
v0.1.2
v0.1.1
v0.1.0
archive/git-mirror
Labels
Clear labels   
accepted
Assessed and will be built

  
bug
Something is broken

  
declined
Assessed and will not be built

  
docs
Documentation only

  
duplicate
Already tracked elsewhere

  
enhancement
New feature or improvement request

  
good first issue
Small, self-contained, and a good place to start

  
in-progress
Someone is working on this right now. Do not start it in parallel.

  
needs-info
Waiting for the reporter

  
privacy
Personal data can leak. Handled before anything else.

  
security
A weakness someone could use. Handled before anything else.

  
triage
Awaiting assessment

No labels
accepted
bug
declined
docs
duplicate
enhancement
good first issue
in-progress
needs-info
privacy
security
triage
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
LibreKAT/Ocideck#1743
No description provided.