Markdeep | Hacker News Reader

Markdeep

casual-effects.com

256 pointshaakon78 comments

Funny enough, browsing without Javascript resulted in the same plain text appearing in both windows. I was nearly ready to comment about how easy that is with a pair of <pre> tags. :)

That said, I'm OK with it degrading like that. The text file is perfectly readable, and conveys the information within quite well. I even kind of preferred it.

So, yeah. Great job, OP.

How can you tell if someone browses the web with JavaScript disabled?

Oh don't worry. They'll let you know. Any chance they get.

A vegan, a crossfitter, an atheist, a crypto nerd, and a javascript disabler walk into a bar...

Same person?

Made me wonder if putting a tiny <img> tag in a <noscript> block would provide some insight by tracking user-agents hitting that file only.

Yes that's how facebook's and Google's pixel tracking works

I'm terribly sorry for providing context for the rest of my comment. My sincerest apologies.

EDIT: On a less passive-aggressive note, I'll stop announcing my blocking of JavaScript by default when static content sites stop requiring JavaScript to read them.

bu-but then how will you be able to view my un-skippable pop-up marketing video, my amazing photo carousal.

And don't tell me you actually like default browser scrolling, my custom JS scrolling is much better.

Oh and don't worry about the load time, that only happens the first time, after that the 30Mb of content is cached so its fine.

:^)

Sorry I'm dying here...

I opened the site, saw two identical boxes of text with some ascii in the middle, read the first paragraphs.. then scrolled down and saw some license thrown in there...

Almost got too happy seeing a satire get so popular on HN. :(

I too thought it was satire at first. I was all like "hmm, that's slightly amusing". And then I realised it was serious and I was all like "wtf is the point?", then "and if it's so amazing, why isn't the main website built using it?".

I'm over Markdown and related formats for the web. We have a great ASCII format for marking up the web, and it's called HTML.

I keep a text file that grows noticeably every day. I write it in Restructured Text (could have been Markdown) for two reasons:

1. My text editor (Vim in this case) renders the text file in colors, and helps me distinguish different elements.

2. If I want, I can export to html.

Markdown and the like grew out of what people were already doing in plain text: dashes and asterisks for bullets, indentation, etc.

I would much rather write plain text, or minimally marked up Markdown or rst, than have to write <tags> for everything, especially for something like my text file that isn't really intended for the web, but can be converted if needed. html is not really meant to be read, but rendered. The various markdowns can be comfortably written, and read as is.

My 2c.

I don't get it. Why would I do diagrams in ascii when I can use any one of dozens of good programs and export the result via DVI or PDF. I guess it must might be nice if I want to read the document on a text console, but I don't see that use case coming up nearly often enough to justify learning yet another version of markdown and commit to doing diagrams with ascii art.

I actually like the idea, for simple diagrams at least. No need to keep separate image resources anywhere. No need to even have a separate image processing program. Want to change that diagram? Well, it's right there in the document itself -- just change it. Done. And the diagram is legible both pre- and post-rendering of the document.

Exactly. There are lots of situations where it's worth trading up some polish for simpler tools and formats. Especially simpler formats.

There is lots of prior art extracting diagrams from textual drawing but AFAIK all required global conformance to some accepted "syntax". Markdeep's(?) idea of local beautification while maintaining the global fixed-width layout is brilliant as you're not limited to particular structures and anything unsupported degrades gracefully! (If this idea has no name, let's call it "2D ligatures"?)

We could have a dozen different tools based on this idea, each supporting a somewhat different dialect, yet any diagram will be reasonably readable under any of them — which is exactly the quality you want when excavating a 40-year-old README of unknown origin.

It's the simplest thing that could possibly work. Except one: using line drawing characters directly in the source (and requiring no tool at all, just view in fixed-width font). Let's try:

  *                                                                             .                 *
  *    0       3                          P ●              Eye ╱         ▶     ╱                  *
  *     ●───────●      +y                    ╲                〈)          ╲   ╱  Reflection       *
  *  1 ╱│    2 ╱│       ▲                     ╲                ╲           ╲ ▶                    *
  *   ●───────● │       │                v0    ╲       v3           ────────●────────             *
  *   │ │4    │ │7      │                  ●────╲─────●                                           *
  *   │ ●─────│─●       +─────▶ +x        ╱      ◀ X   ╲          ◜⎺◝◀────────        ○           *
  *   │╱      │╱       ╱                 ╱        ○     ╲        ( ╱ ) Refraction    ╱ ╲          *
  *   ●───────●       ▶                 ╱                ╲        ◟⎽◞               ╱   ╲         *
  *  5       6      +z              v1 ●──────────────────● v2    │                ○─────○        *
  *                                                               ▼                               *

Hmm, not as good but mostly OK (though font dependent), except for circles. Disappointingly I found no matching parts for bigger than 2x2 circle. It's easy (technically, not sure about politically) to add a few more but it's impossible to support smooth circles of arbitrary radiuses. (OTOH, neither does Markdeep.) Perhaps the best of both worlds would be writing unicode (perhaps using some ascii->unicode helper at typing time) and further enhancing it with this kind of tool...

Because using ASCII makes the documents more portable, more cross-platform.

There is not need to learn another version of Markdown, the diagrams are just plain ASCII and Markdeep supports the Markdown you know and love, plus more.

I think it is great, I love it!

I agree, it's kind of a one-time affair too because if you ever need to add or change a word in a node, you're fcked and have to edit ascii to change borders and lines and what not. There are way better ways to spend your time than to draw an ascii diagram.

http://asciiflow.com/

If there's a way to edit boxes/lines once you draw them to address kgen's point, I've never been able to figure it out in asciiflow.

I've only been using it for a few seconds, so I don't know if I'm off-base here, but isn't that what the third-to-last icon at the top does (box with diagonal arrow)?

Thanks, you're right. I was thinking of the old version. http://stable.ascii-flow.appspot.com/#Draw

Well, the only worst think would be to have to launch Visio, Powerpoint or whatever and then export and then re-embed. Especially if you want to fix something done by someone else so you only have the image and not the binary... Also, versioning.

Version control. If I add an ASCII art diagram to a text document, I can git diff it, and see that the ASCII art diagram was added. If my documentation is is in PDF, I can keep it in version control, but I lose a lot of the advantages that version control provides because PDF is a binary format.

What diagram tool uses PDFs? PDFs are a build artifact like any other binary.

But if you create the pdf using a script (e.g. latex tikz) then this is in your version control instead.

Yes, once we have more intelligent diffs. Line by line isn't enough anymore.

The "have ASCII diagrams converted to images" thing is getting ridiculous. No, I don't want to type a border around my diagram. Text is completely and utterly unsuitable for this, I don't want to have every change require me to reformat everything.

(And frankly, the diff thing is nonsense, too. Diff produces an unreadable mess on ASCII art. I'd rather see the diff of some XML that shows me nodes added, removed, properties changed.)

> Text is completely and utterly unsuitable for this, I don't want to have every change require me to reformat everything.

You need a better editor, that's all. Emacs has picture-mode and artist-mode; no doubt vim has something too, although a quick search didn't help.

1. You need n copies of the tool where n is the number of people in your team.

2. Version control for binaries sucks.

3. Graphical tools can be very awkward when aligning stuff. MS Word, for example, is a pain for making diagrams in.

LaTeX and DOT are not graphical tools.

There are literally dozens of examples of text-based markup tools that are cross-platform, version-controllable, and can be rendered in a terminal if you're into that, and which don't require me to waste time drawing ridiculous ASCII art borders to denote logical relations.

I think org-mode can do that too (and much more I guess).

http://home.fnal.gov/~neilsen/notebook/orgExamples/org-examp...

How popular is it? Will this ever catch on?

Combine with http://asciiflow.com/ and ascii heaven comes closer ;)

Don't forget artist-mode! http://www.cinsk.org/emacs/emacs-artist.html

RST could do this - but I like Markdeep's simplified way (no "directives")

Now if all editors could come up with a compatible ascii graphic drawing tool that would actually be useable.

I think all editors can read in the results of an external program, which might be a better solution. For example, the par text reformatter. Vim doesn't know a thing about it, but it will feed selected text to it, and replace it with results.

So for ascii diagrams, you might have an external program that generates, at least, various kinds of boxes and connectors, then you could edit the labels from the editor. Bonus if the external ascii diagram generator would take labels associated with entities.

Maybe that's an additional feature for Markdeep, or maybe it's a specific itch for someone else to scratch.

ST could do this

some years ago i rendered .rst urls using a cgi shell script that drove rst2html.py from docutils.

Nice setup, but its very cumbersome to write graphs in ascii, i prefer DOT if i dont care about layout too much, otherwise i use gliffy or something like that. For simple diagrams this is nice. However i think the main reason to use this is not diagrams. However then i think its better to use Markdown since most people know that.

There's ASCIIFlow for that: http://asciiflow.com/

The author seems very proud of the automatic-rendering JS they've written, and it's kind of cute but personally I'd much rather a batch-conversion tool.

On the other hand, that ASCII-art-to-SVG conversion is golden, and I'd absolutely love to have that supported in my API docs and blog-posts.

It would probably be trivial to pre-process the text with the script if you wanted to - at the end of the day it has to just be outputting DOM elements.

I for one love that it doesn't require a preprocessing step, because it means that any text file can easily be rendered without any need to do anything else.

Fantastic job OP, I think this is really awesome. Would be perfect if this was integrated with github - I would do all my readmes with this.

After 10 seconds of inspection: no, not a good idea, don't think this solves a nice problem.

Speaking as a PL & s-exp guy, I don't really have a problem writing

(bullets (item "pick up milk") (item "drop off desk"))

... but at the end of the day, I see that I can convey the same structure in a clearer way using markdown. Markdown is lovely because it's the thinnest possible skin over the structure; you can immediately see what structure the syntax is attaching. (Yes, there's still some parsing nastiness around paragraphs). This thing, though, doesn't have that "brilliant solution to a simple but really important problem" feel to it. I don't see this catching on.

Of course, I said the same thing about the internet in the spring of 1993.

So frustrating that both Markdown and this don't support underlines.

I don't think this is the right way to look at this. They both transform to the most sensible html given the input.

If you want to use an underline for emphasis instead of cursive, this is more of a style concern than anything else, so the appropriate place to change this would be in the stylesheet, which is perfectly possible.

If you specifically want it to output the <u> html tag, I agree that this is not as convenient.

> They both transform to the most sensible html given the input.

I'm going to have to disagree with you. Long before Markdown came along, the convention was to use asterisks for * bold *, slashes for /italics/ and underscores for _underlined_ text. And that's just for starters.

Those three examples perfectly convey the intended effect, quite unlike the Markdown versions where asterisks will somehow imply italics, but only if they're single asterisks? It's a strange thing!

The point is that bold, italics, underline are all a property of the style, but not intent. The intent is "emphasis". How emphasis is rendered is dependent on the stylesheet.

If the intent is simply "emphasis", why are there different ways of expressing it?

I agree. _this_should_be_underlined_

That's because underlining is inferior typography. It's from back in the typewriter days when the only way to add emphasis was to back up and put underscores underneath the text. Either bold or italic is more preferable.

Underlining also represents the thing you often do with a pen on printed text. It's perfectly OK and useful type of formatting online.

That's well and good, but the reason that it is appropriate when using a pen on printed text is that the vast majority of people don't differentiate their penmanship when representing emphasized text.

Historically underlined content == actionable hyperlink; for content that is intended for public consumption (ie. not a note that you're writing for your own use) there are usability issues with typographic styles that represent emphasis with an underline.

The ASCII to graph feature reminds me of https://github.com/knsv/mermaid .

But I like the more WYSIWYG approach (if I dare say) of Markdeep.

I am thinking of using this for my personal website. It has been a while since I have had to think about licenses, and I am having trouble thinking this one through.

Markdeep is open source. You may use, extend, and redistribute Markdeep without charge under the terms of the BSD license: ... Markdeep includes markdown.js, so you are also bound by the MIT license (which is BSD-compatible): ... ...and the highlight.js BSD license:

If I understand correctly that means I have to serve all three licenses in my HTML?

I wonder if it would be acceptable to link to the license ( possibly also hosted on your site) instead.

Presumably you don't have to serve _any_ licenses - the license should be in the Javascript file itself?

(disclaimer: I didn't check)

Nice, you could also do something to embed http://yuml.me diagrams for converting text into diagrams?

Might want to make sure you spell your inspiration's name correctly (ie, not Grubber)

he also spelled github as githib, so Gruber's name might also be intentional.

Two wrongs don't make a right...

the ability to turn txt into a diagram is intriguing

Absolutely fricking cool. Would need to learn some extra text editor tricks, however, to make it a smooth experience...

Emacs, at least, already has artist-mode built in.

Screen cast showing it off: http://www.cinsk.org/emacs/emacs-artist.html

DrawIt for Vim: http://www.vim.org/scripts/script.php?script_id=40 . I think I started using this in the previous millennium, and if not, not much later. It's awesome. Not all (former) coworkers agree with that sentiment though, to be honest.

Thanks for your suggestions, roel_v and a_e_k! Will play around with DrawIt, looks fun!

Two other tools that render images from ascii are ditaa (http://ditaa.sourceforge.net/) and plantuml (http://plantuml.com/). Those tools, some scripts to render and combine markdown and images, and DrawIt (+ some other vim tools like 'boxes' (not sure if that still has a web page), 'sketch.vim' and 'boxdraw') make for the least painful, versionable documentation system, for me. ('least painful' in the sense that I still need to code way too much to get it all to work, but there isn't anything ready-made and stable enough that I have been able to find the last decade).

It's reasonably common for LaTeX documents to use PSTricks or PGF/TikZ or Asymptote to specify diagrams as text, within the main document. However, these use textual descriptions of diagrams, rather than ASCII-art pictures of them.

I think before there were GUI tools for editing ladder diagrams [0], there were tools that would read ASCII-art diagrams, and program PLCs with the corresponding logic. However, a quick Google didn't give a source confirming this.

[0]: https://en.wikipedia.org/wiki/Ladder_logic https://en.wikipedia.org/wiki/PGF/TikZ

Where exactly is the source code?

http://casual-effects.com/markdeep/markdeep.min.js

> The current 0.01 beta release is minified-only to find bugs and get feedback, but a full source version is coming soon after some more code cleanup.

Unminified via http://unminify.com/

http://pastebin.com/Y7Q5H0AL

still looks pretty unreadable to me, but then it is late on a friday.

This looks pretty sweet! (On a sidenote, I'm trying to figure out whether making the documentation look like daringfireball.net was intentional or not.)

Neat, but offering only minified JS is not in the spirit of open source imho

https://github.com/reelsense/markdeep

The Flash Of Unstyled Content is strong with this one.

If you remove the Math section of the demo [1] that invokes 17 HTTP request for MathJax artifacts the FOUC is still there but much quicker.

1. http://casual-effects.com/markdeep/features.md.html

I'm still kinda noob at javascript.

Can I call this on a string using a function, returning an html string, rather do it for the whole page?

Why do people keep reinventing LaTeX?

ditaa?

I know you can't exactly copyright a color scheme, but it might be a good idea to not so closely copy Daring Fireball.

Reply on news.ycombinator.com