search

podlomar / kodim.cz

Web for publishing materials from programming courses
1 stars 5 forks source link

Vkládání diagramů do Markdownu #96

Open FilipJirsak opened 8 months ago

FilipJirsak commented 8 months ago

Zvážit použití Kroki (nebo Mermaid, ale Kroki umí renderovat i Mermaid diagramy), které umí z textových zápisů generovat diagramy. Tj. v Markdownu by mohl být textově popsaný diagram, který by se na stránce vykreslil. Dalo by se to použít např. pro vykreslování diagramů komponent v Reactových lekcích – jen jako vizualizace pro ty studentky, které dávají přednost vizuálnímu zobrazení před textovým popisem.

Sice je možné vkládat do lekcí přímo obrázky diagramů, ale pak hrozí, že budou zastarávat a bude obtížné je udržovat aktuální.

podlomar commented 7 months ago

Souhlasím, prozkoumán to

FilipJirsak commented 7 months ago

Já to budu řešit i pro jiné projekty, tak ať to nezkoumáme oba dva.

Kroki funguje tak, že běží jako web server, na který se POSTem pošle zdrojový text a vrátí to obrázek v požadovaném formátu a rozměrech. Menší zdroje jde posílat i jako GET, ale to podle mne není vhodné.

Protože to generování obrázku nějakou chvilku trvá, moje představa je taková, že by se ty obrázky kešovaly. Při zpracování Markdownu by se vzal zdrojový kód obrázku, ten by se poslal POSTem na nový server, ten by vrátil odkaz na obrázek (pravděpodobně hash vstupnímu textu), ten odkaz by se vyrenderoval do HTML. A ten nový server by pak použil Kroki pro vykreslení toho obrázku a uložil by to jako soubor na disk pod tím jménem, které tomu přiřadil. Tím pádem pro koncové uživatele už by se pak obrázky poskytovaly ze statických souborů na disku.

Ještě nemám rozmyšlené mazání – výše uvedeným postupem by ty soubory byly nakešované navždy, i když se zdrojový kód změní a přestane se používat. Asi bych tam přidal nějaký příznak, ke kterému zdrojovému repository obrázek patří, aby se dalo sledovat, zda bylo požadováno ho vykreslit znova, nebo zda se může smazat.

podlomar commented 7 months ago

Na kodím je to tak, že se naparsuje markdown, udělá se z toho nějaká datová struktura a ta se pak rekuzivně prochází a renderují se z toho rovnou serverové React komponenty. Nebylo by jednodušší prostě udělat React komponentu, která pomocí té knihovny rovnou vyrobí SVG toho diagramu? Celé se to pak i s tím inline SVG pošle na klienta. Já jsem trochu koukal na ten Mermaid a ten by to měl v pohodě umět.

FilipJirsak commented 7 months ago

Já jsem totiž nikdy reálně neuvažoval o použití Mermaid, vždy jen o Kroki. A to je serverové řešení, nedá se provozovat jako knihovna. Kroki totiž integruje spoustu různých nástrojů, třeba i TikZ nebo teď snad mají i experimentální odporu draw.io. Je otázka, pro co všechno by se diagramy používaly. Mně by se líbilo použít je pro hierarchii komponent v Reactu a pak pro nějaká schémata volání – callbacky, komunikace dítě→rodič nebo rodič→dítě v Reactu. Je otázka, zda by na to Mermaid stačil. Nemám to vyzkoušené, ale nezkoušel jsem to ani s Kroki.

FilipJirsak commented 7 months ago

Ještě jsem našel přímo plugin Kroki pro Remark: https://github.com/nice-move/remark-kroki