Markdeep markup language | Hacker News Reader

Markdeep markup language

casual-effects.com

174 pointsaparashk59 comments

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.

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

PlantUML looks neat! Great for design docs

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
  ```

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.

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.

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...

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

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.

Yes, I am considering to switch to AsciiDoc in future. Does Github have proper support, or do you have to write in a subset?

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

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.

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 :)

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.

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.

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.

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

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

To go beyond generic Wiki syntax, SGML lets you define context-specific token replacement rules. For example, to make SGML format a simplistic markdown fragment into HTML, you could use an SGML prolog like this:

    <!DOCTYPE p [
      <!ELEMENT p - - ANY>
      <!ELEMENT em - - (#PCDATA)>
      <!ENTITY start-em '<em>'>
      <!ENTITY end-em '</em>'>
      <!SHORTREF in-p '*' start-em>
      <!SHORTREF in-em '*' end-em>
      <!USEMAP in-p p>
      <!USEMAP in-em em>
    ]>
    <p>The following text:
       *this*
       will be put into EM
       element tags</p>

so XML removed the best part of SGML..

XML was always intended more for machine than for human consumption. It's easier for machines to consume extremely regular syntax, so that's what XML has.

unfortunately it had its time as a pseudo programming language period..

> unfortunately it had its time as a pseudo programming language period..

You are quite right. I should probably have said something more like "XML was intended by its creators more for machine than human consumption" (and, incidentally, creation; I think I have read that XML construction wasn't really intended to be done by humans either).

There’s XSLT Markdown to HTML converters out there. And while XSL isn’t XML, it is in every browser and available next to XML in near enough everything else.

Yes, it's not only everywhere, it's nothing less than a second programming language for the web, although very much neglected :)

How does the parser distinguish between in-p and in-em to substitute in the corresponding entities? It seems to me that when it reaches the second asterisk it's not going to be able to know whether to open or close the em element.

Is this one of those pieces of occult witchery that SGML excels at..?

If the context (top-most) element is "em", the "in-em" shortref map is current (as per the second USEMAP declaration), which defines the replacement text for "*" to be "</em>", ending the emphasized text span. Whereas within "p", it's "<em>", starting an emphasized text span, and making "em" the context element.

Something I haven't seen in any markdown editor so far (suggestions welcome) is extended table support.

Say I have a table with a 'name' and 'value' column and 100 entries. And I'd like names to be alphabetically sorted. So far so good.

But this table is too long and too small, so I want to have 4 columns and 50 rows, where the name/value continue in column 3, 4. Out of luck. This is unmanageable, as you have to shift many cells when adding a new entry.

A proposal for something like this: https://github.com/github/markup/issues/1189

Also mentions multi-line cell contents, which are hard in regular markdown (require inline html)..

I think Emacs's org-mode can do that, by offering an easy way to insert columns. It's not markdown, but at a glance, the table syntax seems compatible or close enough, so maybe copy/pasting to and from Emacs could do the job if you can stand Emacs.

org-mode's tables can do a lot of things.

https://orgmode.org/org.html#Tables

I'm pretty sure Pandoc has an option to interpret org-mode style tables in Markdown files, and Org-mode itself has a mode for editing tables in non-org files. I haven't played with either, however, so I can't report on how well they work.

Markdown doesn't compose very well, you kind of want to drop into a programming language for that

http://www.hyperfiddle.net/:docs/:cookbook!static-site-markd...

It can be abstracted into a function though, here's a different table done from only markdown (and backed by a database!)

http://www.hyperfiddle.net/:docs/:fiddle-markdown

Hartl’s Tenth Rule of Typesetting:

"Any sufficiently complicated typesetting system contains an ad hoc, informally specified, bug-ridden, slow implementation of half of LATEX."

Markdeep is no exception.

http://manual.softcover.io/book/softcover_markdown#cha-softc...

Well the whole point of markdown is that it is simple enough so that devs easily document whatever necessary. As you know documentation is notoriously neglected by the developers. But this is not that simple. I doubt it will be adopted that much.

I'm not sure you realize how many blogs and website are written using markdown.

I think the parent's point is that markdown is simple, but markdeep is not.

I think your parent's point was that Markdown is used in a lot of situations where simplicity isn't as important as it is when documenting code.

I really like the idea of a new markup format. To me markdown has been very unintuitive in some ways. I can never remember whether more # means higher or deeper header level. Or which of - - - or === makes a first or second level header. But since markdown is first class citizen at github, I don’t think we’ll ever be able to see any real competition rise up (even though github has first class support for others, markdown is the clear winner). And I’ve never heard anyone else mention these confusions so maybe everyone else is fine with it and I’m the only one who wants an alternative.

I think the biggest problem with Markdown is that the spec is ambiguous and there’s no clearly prevailing standard.

Jeff Atwood tried to fix this, but the creator of Markdown does not seem keen to cooperate with any attempts to standardize it.[1]

Since he owns the trademark, standardization will likely be impossible without his cooperation. Not to come down on John Gruber, I understand his position and he’s a cool cat... it’s just an unfortunate shortcoming of markdown, which I otherwise love.

With the exception of ordered lists. I can never figure out how to get multiple paragraphs or interstitial content into ordered lists, and it always resets the counter to 1... but everything else is great!

[1] https://blog.codinghorror.com/standard-markdown-is-now-commo...

I've been working on an evolved markdown format alternative - that removes some known failures such as image links e.g. ![]() and improves some such as links e.g. lets use wikipeda style links :-) and lets offer more link of syntax alternatives - and adds some stuff while trying to learn from the "real world", that is, getting the best of the world of wikipedia markup, markdown and latex all together and easy to use. The format is called texti short for text with (formatting) instructions. See https://texti.github.io for more.

You don't have to remember that - it's up to you. Whatever markup you use for headings, the levels are inferred.

Asciidoc is a viable alternative. By now you have Asciidoctor in Ruby, AsciidoctorJ on JVM, Asciidoctor.js and even original Asciidoc Python recently rewritten for Py3.

https://github.com/asciidoctor/asciidoctor.org/blob/master/d...

Here is a very short intro on rendering in your browser: https://www.youtube.com/watch?v=4LOB3WeOUJk

Asciidoc.org at some time in the future should be the page for the language spec. The biggest feature is probably that you can produce DocBook and it's very easy!

We've been really happy with Asciidoc at work. We maintain multiple large versioned documents as a team and had been using Word and 'Track Changes' to do updates. We've now moved them entirely to Asciidoc and are using Git for tracking and approving changes, and the difference is night and day. We considered Markdown at the time, but things like numbered lists incorporating paragraphs, metadata inclusion, and the need to specify certain elements about the final published version meant that Asciidoc was a clear winner. To get all of those incorporated using Markdown would have meant implementing one of the Markdown dialects, and then ensuring that everyone's tool-chain that thought it spoke Markdown wouldn't then munge it to death.

Markdown isn't perfect, but I find it really weird that you complain about the headers in particular. I never use the underline style, but I don't think you can get more straightforward than the # notation.

I really wish people would simply forget about markdown and restart with a slightly more sensible and extensible markup. I personally always thought that some sort of latex/context with a simple markup for common commands would be more useful.

This sounds pretty cool. My own workflow is so pandoc-dependent though that I don't think I could use it unless someone who is much better at Haskell than I am works the markdeep extensions into pandoc :-(

The day I find one of these mark* languages that supports poetry -- which simply means, a section in which it respects literal indents and line-breaks, but not by dropping into monospace font -- I'll use it.

N.B. the online publishing platform Leanpub has its own mark* variant, "markua"[1] which actually does recognize a poem section -- although as implemented it has minor formatting issues.

[1] https://leanpub.com/markua/read

I've put together a book of poetry using CLI/markdown-ish tools. pandoc make texlive-xetex is what's in the Dockerfile that builds it. If you contact me directly I'd be willing to share how far I've gotten with the problem.

I think anyone would agree that Markdown the sna bit too simplistic, and while Markdeep looks cool, it seems like it ends up at the opposite extreme with too much complexity.

Very cool. Thank you for making and sharing this!

From 2015: https://news.ycombinator.com/item?id=10402121

Shameless plug: http://write.pub supports most of the features of MarkDeep, and allows WYSIWYG writing.

It also shows with built in version control, you don't have to know git to use it

Is this just a wrapper for tui.editor?

The editor is indeed TUI. But TUI doesn't support editing/saving local files, which write.pub allows.

There are multiple other features, like WYSIWYG diff and version control that make this app compelling

That's awesome! I'm a huge fan of tui so I was curious.

Is there some way of doing 3D diagrams?

Justified margins?

Markdown is cool because it's minimalistic.

Markdeep might be a good idea, but if you start adding more and more feature you reimplement HTML, at that point why not simply use HTML? Isn't HTML plain text, too?

This was my thought when I saw the example on the frontpage with styling

Reply on news.ycombinator.com