4 ms·

Markdeep has some very nice features. I love to be able to have more expressiveness than in regular markdown. But I am not so sure about the diagramming featur

by rapnie 8y ago

Markdeep has some very nice features. I love to be able to have more expressiveness than in regular markdown. But I am not so sure about the diagramming feature. Writing diagrams as ascii art seems like a PITA to me, especially when you need to update a diagram with new shapes, etc. For this I prefer PlantUML markdown integration: http://plantuml.com http://plantuml.com I use VS Code and it has a nice plugin to handle this.

sudeepj 8y ago
Yeah, if there are merge conflicts within the ascii charts then it is even more PITA.
asah 8y ago
PlantUML looks neat! Great for design docs
- rapnie 8y ago
  Yes, it is a very easy text-only format, and with that VS Code plugin you see the rendered diagram updated in real-time in the preview panel. ```plantuml @startuml :Actor: --> (UseCase) @enduml ```
jkabrg 8y ago
What about freehand drawn diagrams? It seems pretty fast and intuitive, and would deal with your problem* . Are there any tools for making freehand diagrams look professional? It would be analogous to how Markdown makes "crude" text look "professional". * As long as you have good coordination.
- hawski 8y ago
  A ruler would make a difference. Maybe also using something at least a level or two better than cheapest ball point pen available. Those and a bit of calligraphy exercises.
- paultopia 8y ago
  This is an interesting idea---how hard would it be to do this? It might be as simple as doing k-means on the pixels or some other kind of clustering algorithm, and then fitting a spline curve to each cluster...
jtbayly 8y ago
I could never write that diagram in ASCII. My brain is unable think in lines like that or something.
hobo_mark 8y ago
I do all my markup, including diagrams (PlantUML and more), in AsciiDoc and I have yet to find a good reason to switch to one of the many markdowns.
- rapnie 8y ago
  Yes, I am considering to switch to AsciiDoc in future. Does Github have proper support, or do you have to write in a subset?
  - geraldcombs 8y ago
    Asciidoctor is in the supported markup list in the GitHub Markup README[1], which means you might need to enable compat-mode for strict AsciiDoc syntax support. The Asciidoctor repository's README.adoc renders just fine[2]. [1] https://github.com/github/markup https://github.com/github/markup [2] https://github.com/asciidoctor/asciidoctor https://github.com/asciidoctor/asciidoctor
shitloadofbooks 8y ago
We had a really bad experience with PlantUML (as a Confluence plugin) ~2 years ago: https://github.com/plantuml/plantuml/issues/25 https://github.com/plantuml/plantuml/issues/25. (Also, this: https://github.com/plantuml/plantuml/pull/94 https://github.com/plantuml/plantuml/pull/94) Something to keep in mind.
- rapnie 8y ago
  wtf?? Wow, thanks for these pointers. I have not run into any trouble, but these are some bad coding practices. At least they are in the process of addressing them all :)
nhh9000 8y ago
Shameless plug: I have been working on a tool like markdeep but with PlantUML-like syntax. It's here: http://markdown.online http://markdown.online The syntax help page is a kitchen-sink of what's supported: http://markdown.online/view/public/syntaxhelp http://markdown.online/view/public/syntaxhelp Planning on supporting more than sequence and flowcharts, but for now that's what I have. Please note, this is not ready yet for prime time, it's alpha quality at best. Finally, I think there is a place for a tool like Markdeep. There is only so much expressiveness that a tool like mine can support. Yes, ascii art to diagrams is PITA, but it is the most generic solution if you want diagrams with flexibility. I find my tool and tools like PlantUML to fit in the other end of the spectrum, you want a quick diagram without much fussing over how it really looks.
- BLanen 8y ago
  Bit weird that on such a 'static' website, the pages don't render without javascript. Are you doing the rendering completely client side? >you want a quick diagram without much fussing over how it really looks. It's also way easier to edit and collaborate with. Could even be version controlled in a source-code way.
  - nhh9000 8y ago
    Everything is rendered on the clientside, yes. One of the big issues right now is that one of the libraries which I use for layout (ELK.js) weighs in at 3MB which is huge (and most of the code is unused). But re-implementing it all from scratch is quite a bit of work, and I need to pick between perfect and getting something done. :) > It's also way easier to edit and collaborate with. Could even be version controlled in a source-code way. Overall idea is to make this into a wiki. I am also planning to add an ability to collaboratively edit the same page (like google docs). In terms of version control, yes, also thought about it. It's a bit more complex, and I don't have a good architecture as a solution at the moment.
scott113341 8y ago
Monodraw is the best application I've found for ASCII (and Unicode) diagramming: https://monodraw.helftone.com https://monodraw.helftone.com
SahAssar 8y ago
Mermaid.js has worked pretty well for me and has vscode plugins: https://mermaidjs.github.io/ https://mermaidjs.github.io/

by rapnie 8y ago

sudeepj 8y ago

Yeah, if there are merge conflicts within the ascii charts then it is even more PITA.

asah 8y ago

PlantUML looks neat! Great for design docs

rapnie 8y ago
Yes, it is a very easy text-only format, and with that VS Code plugin you see the rendered diagram updated in real-time in the preview panel. ```plantuml @startuml :Actor: --> (UseCase) @enduml ```

jkabrg 8y ago

What about freehand drawn diagrams? It seems pretty fast and intuitive, and would deal with your problem* . Are there any tools for making freehand diagrams look professional? It would be analogous to how Markdown makes "crude" text look "professional". * As long as you have good coordination.

hawski 8y ago
A ruler would make a difference. Maybe also using something at least a level or two better than cheapest ball point pen available. Those and a bit of calligraphy exercises.
paultopia 8y ago
This is an interesting idea---how hard would it be to do this? It might be as simple as doing k-means on the pixels or some other kind of clustering algorithm, and then fitting a spline curve to each cluster...

jtbayly 8y ago

I could never write that diagram in ASCII. My brain is unable think in lines like that or something.

hobo_mark 8y ago

I do all my markup, including diagrams (PlantUML and more), in AsciiDoc and I have yet to find a good reason to switch to one of the many markdowns.

rapnie 8y ago
Yes, I am considering to switch to AsciiDoc in future. Does Github have proper support, or do you have to write in a subset?
- geraldcombs 8y ago
  Asciidoctor is in the supported markup list in the GitHub Markup README[1], which means you might need to enable compat-mode for strict AsciiDoc syntax support. The Asciidoctor repository's README.adoc renders just fine[2]. [1] https://github.com/github/markup https://github.com/github/markup [2] https://github.com/asciidoctor/asciidoctor https://github.com/asciidoctor/asciidoctor

shitloadofbooks 8y ago

We had a really bad experience with PlantUML (as a Confluence plugin) ~2 years ago: https://github.com/plantuml/plantuml/issues/25 https://github.com/plantuml/plantuml/issues/25. (Also, this: https://github.com/plantuml/plantuml/pull/94 https://github.com/plantuml/plantuml/pull/94) Something to keep in mind.

rapnie 8y ago
wtf?? Wow, thanks for these pointers. I have not run into any trouble, but these are some bad coding practices. At least they are in the process of addressing them all :)

nhh9000 8y ago

Shameless plug: I have been working on a tool like markdeep but with PlantUML-like syntax. It's here: http://markdown.online http://markdown.online The syntax help page is a kitchen-sink of what's supported: http://markdown.online/view/public/syntaxhelp http://markdown.online/view/public/syntaxhelp Planning on supporting more than sequence and flowcharts, but for now that's what I have. Please note, this is not ready yet for prime time, it's alpha quality at best. Finally, I think there is a place for a tool like Markdeep. There is only so much expressiveness that a tool like mine can support. Yes, ascii art to diagrams is PITA, but it is the most generic solution if you want diagrams with flexibility. I find my tool and tools like PlantUML to fit in the other end of the spectrum, you want a quick diagram without much fussing over how it really looks.

BLanen 8y ago
Bit weird that on such a 'static' website, the pages don't render without javascript. Are you doing the rendering completely client side? >you want a quick diagram without much fussing over how it really looks. It's also way easier to edit and collaborate with. Could even be version controlled in a source-code way.
- nhh9000 8y ago
  Everything is rendered on the clientside, yes. One of the big issues right now is that one of the libraries which I use for layout (ELK.js) weighs in at 3MB which is huge (and most of the code is unused). But re-implementing it all from scratch is quite a bit of work, and I need to pick between perfect and getting something done. :) > It's also way easier to edit and collaborate with. Could even be version controlled in a source-code way. Overall idea is to make this into a wiki. I am also planning to add an ability to collaboratively edit the same page (like google docs). In terms of version control, yes, also thought about it. It's a bit more complex, and I don't have a good architecture as a solution at the moment.

scott113341 8y ago

Monodraw is the best application I've found for ASCII (and Unicode) diagramming: https://monodraw.helftone.com https://monodraw.helftone.com

SahAssar 8y ago

Mermaid.js has worked pretty well for me and has vscode plugins: https://mermaidjs.github.io/ https://mermaidjs.github.io/