12 ms·
Markdeep markup language
- rapnie 8y agoMarkdeep 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 agoYeah, if there are merge conflicts within the ascii charts then it is even more PITA.
- asah 8y agoPlantUML looks neat! Great for design docs
- rapnie 8y agoYes, 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 agoWhat 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 agoA 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 agoThis 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 agoI could never write that diagram in ASCII. My brain is unable think in lines like that or something.
- hobo_mark 8y agoI 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 agoYes, 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 agoAsciidoctor 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 agoWe 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 agowtf?? 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 agoShameless 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 agoBit 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 agoEverything 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 agoMonodraw is the best application I've found for ASCII (and Unicode) diagramming: https://monodraw.helftone.com https://monodraw.helftone.com
- SahAssar 8y agoMermaid.js has worked pretty well for me and has vscode plugins: https://mermaidjs.github.io/ https://mermaidjs.github.io/
- rapnie 8y agoSomething 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 https://github.com/github/markup/issues/1189 Also mentions multi-line cell contents, which are hard in regular markdown (require inline html)..
- duckerude 8y agoI 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 https://orgmode.org/org.html#Tables
- rcthompson 8y agoI'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 8y agoMarkdown 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-markdown 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 http://www.hyperfiddle.net/:docs/:fiddle-markdown
- paultopia 8y agoThis 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 8y agoJustified margins?
- sbjs 8y agoI 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 8y agoI 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-common-markdown/ https://blog.codinghorror.com/standard-markdown-is-now-commo...
- geraldbauer 8y agoI'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 https://texti.github.io for more.
- akvadrako 8y agoYou don't have to remember that - it's up to you. Whatever markup you use for headings, the levels are inferred.
- ivanceras 8y agoSimilar https://ivanceras.github.io/svgbob-editor/ https://ivanceras.github.io/svgbob-editor/
- disqard 8y agoVery cool. Thank you for making and sharing this!
- s5ma6n 8y agoWell 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 8y agoI'm not sure you realize how many blogs and website are written using markdown.
- deleted 8y ago[deleted]
- alphakappa 8y agoI think the parent's point is that markdown is simple, but markdeep is not.
- mort96 8y agoI 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.
- tannhaeuser 8y agoTo 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>
- agumonkey 8y agoso XML removed the best part of SGML..
- JadeNB 8y agoXML 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.
- agumonkey 8y agounfortunately it had its time as a pseudo programming language period..
- JadeNB 8y ago> 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).
- quink 8y agoThere’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.
- dang 8y agoFrom 2015: https://news.ycombinator.com/item?id=10402121 https://news.ycombinator.com/item?id=10402121
- writepub 8y agoShameless plug: http://write.pub 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
- medntech 8y agoIs this just a wrapper for tui.editor?
- nkkollaw 8y agoMarkdown 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 8y agoThis was my thought when I saw the example on the frontpage with styling
- theshadowknows 8y agoIs there some way of doing 3D diagrams?
- stewbrew 8y agoI 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 8y agoThe 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 https://leanpub.com/markua/read
- ramses0 8y agoI'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 8y agoI 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 8y agoHartl’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-softcover_flavored_markdown http://manual.softcover.io/book/softcover_markdown#cha-softc...