News for hackers. Stuff that matters.
Re:Markdeep markup language by rapnie on Saturday August 04, 2018 @08:03AM (#17686517)
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

I use VS Code and it has a nice plugin to handle this.

Re:Markdeep markup language by shitloadofbooks on Saturday August 04, 2018 @12:39PM (#17687493)
We had a really bad experience with PlantUML (as a Confluence plugin) ~2 years ago: https://github.com/plantuml/plantuml/issues/25.

(Also, this: https://github.com/plantuml/plantuml/pull/94)

Something to keep in mind.

Re:Markdeep markup language by rapnie on Saturday August 04, 2018 @02:02PM (#17687820)
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 :)
Re:Markdeep markup language by nhh9000 on Saturday August 04, 2018 @01:05PM (#17687592)
Shameless plug:

I have been working on a tool like markdeep but with PlantUML-like syntax. It's here: http://markdown.online

The syntax help page is a kitchen-sink of what's supported: 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.

Re:Markdeep markup language by BLanen on Saturday August 04, 2018 @04:47PM (#17688361)
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.

Re:Markdeep markup language by nhh9000 on Saturday August 04, 2018 @06:25PM (#17688718)
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.

Re:Markdeep markup language by scott113341 on Saturday August 04, 2018 @01:55PM (#17687792)
Monodraw is the best application I've found for ASCII (and Unicode) diagramming: https://monodraw.helftone.com
Re:Markdeep markup language by jkabrg on Saturday August 04, 2018 @10:04AM (#17686887)
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.

Re:Markdeep markup language by paultopia on Saturday August 04, 2018 @11:50AM (#17687291)
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...
Re:Markdeep markup language by hawski on Saturday August 04, 2018 @10:34AM (#17686990)
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.
Re:Markdeep markup language by hobo_mark on Saturday August 04, 2018 @12:12PM (#17687385)
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.
Re:Markdeep markup language by rapnie on Saturday August 04, 2018 @12:28PM (#17687447)
Yes, I am considering to switch to AsciiDoc in future. Does Github have proper support, or do you have to write in a subset?
Re:Markdeep markup language by geraldcombs on Saturday August 04, 2018 @02:28PM (#17687925)
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 [2] https://github.com/asciidoctor/asciidoctor

Re:Markdeep markup language by jtbayly on Saturday August 04, 2018 @11:35AM (#17687228)
I could never write that diagram in ASCII. My brain is unable think in lines like that or something.
Re:Markdeep markup language by SahAssar on Saturday August 04, 2018 @05:27PM (#17688496)
Mermaid.js has worked pretty well for me and has vscode plugins: https://mermaidjs.github.io/
Re:Markdeep markup language by sudeepj on Saturday August 04, 2018 @08:15AM (#17686560)
Yeah, if there are merge conflicts within the ascii charts then it is even more PITA.
Re:Markdeep markup language by asah on Saturday August 04, 2018 @09:59AM (#17686863)
PlantUML looks neat! Great for design docs
Re:Markdeep markup language by rapnie on Saturday August 04, 2018 @10:32AM (#17686979)
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
  ```