Markdeep markup language

by aparashk • 8 years ago

174 59 8 years ago

rapnie5• 8 years 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

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

sudeepj• 8 years ago

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

asah• 8 years ago

PlantUML looks neat! Great for design docs

rapnie5• 8 years 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• 8 years 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• 8 years 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.

paultopia2• 8 years 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• 8 years ago

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

hobo_mark• 8 years 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.

rapnie5• 8 years 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?

shitloadofbooks• 8 years ago

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.

rapnie5• 8 years 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 :)

nhh90002• 8 years ago

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.

BLanen• 8 years 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.

scott113341• 8 years ago

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

SahAssar• 8 years ago

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

rapnie5• 8 years ago

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

duckerude• 8 years ago

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

rcthompson• 8 years ago

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.

dustingetz• 8 years ago

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

paultopia2• 8 years ago

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

janaagaard• 8 years ago

Justified margins?

sbjs• 8 years ago

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.

throwaway0255• 8 years ago

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

geraldbauer• 8 years ago

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.

akvadrako• 8 years ago

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

type0• 8 years ago

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!

castillar76• 8 years ago

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.

j_4• 8 years ago

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.

ivanceras• 8 years ago

disqard• 8 years ago

Very cool. Thank you for making and sharing this!

s5ma6n• 8 years ago

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.

bnchrch• 8 years ago

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

alphakappa• 8 years ago

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

tannhaeuser2• 8 years ago

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>

agumonkey2• 8 years ago

so XML removed the best part of SGML..

JadeNB2• 8 years ago

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.

quink• 8 years ago

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.

eponeponepon• 8 years ago

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

tannhaeuser2• 8 years ago

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.

dang• 8 years ago

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

writepub2• 8 years ago

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

medntech2• 8 years ago

Is this just a wrapper for tui.editor?

writepub2• 8 years ago

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

nkkollaw• 8 years ago

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?

bausshf• 8 years ago

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

theshadowknows• 8 years ago

Is there some way of doing 3D diagrams?

stewbrew• 8 years ago

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.

fernly• 8 years ago

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

ramses0• 8 years ago

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.

transfire• 8 years ago

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.

amai• 8 years ago

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

Markdeep markup language

Related Stories