Codimd: Markdeep Support?

[offray]

I just discovered Markdeep, which seems like a pretty complete and lightweight CommonMark superset, implemented in pure Javascript. It has already some differences with the one supported by CodiMD, like the way both markdown variants work with admonitions (warnings, alerts and so on).

Because of its minimalism, Markdeep can be easily integrated with light DVCS systems like Fossil by just adding a JS file. In workflows where we are editing collaboratively in real time with CodiMD, but we can have also long times for off-line edition, having such lightweight combinations, would be pretty important (working on-line and off-line, instead of having on-line as a given is pretty common in several places on the Global South).

I wonder, how difficult would be to make CodiMD to work with Markdeep in the code editor and in the live preview panels and it this setup could make sense for online offline workflows as the described above. In such case, I imagine that a system wide setup could be related with the CommonMark superset that is being used.

[ccoenen]

I've looked at the provided weblink (thanks!) but I'm not quite certain what the advantage of a switch would be? The only thing I see as differently, is the ASCII-Art diagram feature, which I am not sure is worth the effort. I may well be wrong, I was merely skimming that website.

I am not quite sure what the fossil integration might be about, or why this would be tied to Markdeep somehow (as opposed to "what's currently integrated")

If there's anything in particular that you'd like to point out, feel free to expand on your initial post!

[offray]

I would talk first about Fossil integration and then about Markdeep support, to see if I can explain the use case better in that way.

Fossil is a lightweight integrated DVCS with support for distributed code, ticketing/issues, wiki and forum (think in GitHub/GitLab in a box, running under 3 Mb). I would like to have CodiMD support for DVCS beyond git based ones, starting with Fossil, because is dead easy to install and deploy on one hand and enables true decentralization on the other.

Once we have such integration, would be nice to have proper HTML rendering of the CodiMD Markdown files stored in the DVCS. This would mean that some support for rendering technologies of CommonMark superset should implemented in the DVCS. I don't know which part of CodiMD makes the HTML (live) rendering of its Markdown variant, but I know that in the case of Markdeep, is just a Javascript file, which means that just adding it to a (Fossil) DVCS repository, would give me all the features of its Markdown superset, including not only ASCII diagrams, but labeled figures, figures arrays, and bibliographic citation support, which is pretty much what CodiMD CommonMark superset already has (without smileys support) plus almost anything that academic and book writing support needs, (again, in just a single Javascript file). This would keep the DVCS light while improving greatly its rendering capabilities for documents that where created collaboratively online, but that can work pretty well offline (this online offline functionality without major degradation is important, as I told, in many places of the Global South).

The other way I think to have collaborative CommonMark writing with live preview, with good and offline writing and lightweight preview integrated in a DCVS would be converting between the superset provided by CodiMD and the one provided by Markdeep... which could be done with Pandoc. The problem with this approach is having to maintain two CommonMark supersets, which was issue CommonMark was trying to solve with Markdown balkanization in the first place.

[kindfulkirby]

I've asked for truly static rendering before, see #897, might be relevant?

Integration with Fossil sounds really interesting, but also really challenging.

[offray]

Reading #897 I think that Markdeep support would solve the part related with proper Markdown export when Javascript is disabled in the browser. You would not get HTML preview in that case, but you would get the same Markdeep file it was wrote in CodiMD and having HTML rendering would be just matter of enabling Javascript in the browser. That simplicity and completeness is the big advantage of Markdeep over other CommonMark supersets.

In any case we will be trying some workarounds on connecting Markdeep and CodiMD with Grafoscopio and we will keep this community updated on them.

Cheers,

[kindfulkirby]

I see what you mean. I guess my desire for static HTML is very old school...

Looking forward to hear what you can achieve!

[ccoenen]

Markdeep would not change the complicatedness of this at all. We could probably send .md right now. But this would not be, what people expect from that API endpoint in my opinion.

[SISheogorath]

Just as note: Exchanging the markdown parser in CodiMD is not trivial. We have a ton of stuff that hooks into it, does minor to major changes and we end up with the results we currentl see under https://hackmd-ce.herokuapp.com/features

Replacing the parser would also cause a almost complete rewrite of the parser extension code, including the external modules we use as well as the ones that are written in our own client code.

If there isn't a damn good reason to change it, I would like to avoid it.

[offray]

I imagine that CodiMD is a pretty complicated piece of software and maybe supporting several CommonMark supersets is too difficult. So, it seems that the Pandoc approach it the best one for Markdeep support to documents written in CodiMD, without major rewrite, while the Markdeep features are integrated in a more "standard" CommonMark superset. My intended workflow would be something like:

1. Write collaboratively and in real time in CodiMD.
2. Use CodiMD-CLI API or some equivalent to export to plain text .md files.
3. Use Pandoc to transform the .md file, with the CodiMD CommonMark superset, to md.html, with the Markdeep superset. That would also deal with the features like Yaml metadata blocks that are not supported in Markdeep. So Pandoc would be a two ways sync between both CommonMark supersets.
4. Add .md and md.html files to a (Fossil) DVCS to have a fluid realtime synchronous online editing and non-realtime asynchronous offline editing.
5. Advocate for missing features in one superset without losing the features of the other, like Yaml metadata blocks for Markdeep's variant and diagrams, labeled figures, figure arrays, bibliographic references, in CodiMD's variant, while sharing the experiences and workarounds on that possible bridge.

[SISheogorath]

If you really want, you can may write in integration for pandoc-as-a-service which is a nice way to use pandoc on a web platform.

This could make it less manual work :)

[offray]

Thanks for the link. Seems interesting.

Because we are using Grafoscopio as a client for implementing and extending the described workflow (including PDF and EPUB export), it would not be a lot of manual work, just a pair of clicks in the Grafoscopio GUI or a command in its CLI :).

[offray]

@ttheuer Note that you can have "HTML export to static content using ?export in the URL", according to Markdeep documentation ;).

[kindfulkirby]

@offray That's still rendering client side. Also off-topic here :wink:

[offray]

@ttheuer Sorry, I don't understand. It is Off-topic in the context of talking about Markdeep integration and HTML rendering?

Anyway it seems that nor Markdeep or CodiMD would serve your request of static HTML rendering without Javascript enabled.

[almereyda]

Given the comment https://github.com/hackmdio/codimd/issues/926#issuecomment-416140925 above am I right to conclude that the reported issue with Markdeep Support? is not able to be resolved without major efforts and can therefore be closed here?

OT: Thanks for pandoc-as-a-service.

[offray]

For me it can be closed. We will try to build a CodiMD to Markdeep conversor that doesn't rely on any code present on CodiMD, just the ability to export its Markdown to other clients, so maybe this functionality should be external anyway.

[ccoenen]

Thanks everyone!