Hacker News new | past | comments | ask | show | jobs | submit login
Markdownify (tibastral.github.io)
204 points by tibastral2 on Apr 10, 2015 | hide | past | web | favorite | 88 comments

I would love to see a really good WYSIWYG-like thing that creates Markdown.

I'm one of the founders of Perch (http://grabaperch.com) and we have almost 6 years of experience with Perch - and many more of creating custom CMS solutions before launching Perch. We've always tried to get people to write Textile or Markdown.

When we were developing custom solutions we actually had pretty good success with getting our clients to use Textile, once we'd explained the benefits. With Perch we ship our default templates (which are really just samples) using the MarkItUp editor and set to use Markdown, and not allow HTML. However it's all configurable and we offer editor plugins so people can switch to using Redactor, CKEditor, TinyMCE or create their own editor plugin.

In discussing this stuff with our customers who are developing sites for clients, it's not something that inserts HTML that they want. They just don't want the end client to see the Markdown as they don't think they will cope. I think there is often an assumption that they won't cope, but for whatever reason they end up installing CKEditor or whatever and it allows in a load of junk markup. This makes me sad.

So, an editor that created Markdown yet allowed for some sort of preview of how things will look I can see the benefit of, if just to encourage confidence in not using things that allow inserted HTML.

Personally I completely understand end-users for wanting a purely visual writing environment. No "show HTML", no markdown codes (and escape characters!) etc.. There is a reason desktop writing applications became fully visual three decades ago!

The value of Markdown is that it defines a limited set of semantic blocks and text styles so that the markup and css needed to render the content is finite and predictable upfront.

It seems to me this advantage could be achieved with an editor designed specifically with this idea in mind. The editor could be fully visual, but it would respect a pre-defined set of rules regarding content semantics. The editor could output an XML or JSON tree of content with semantic labels that you could then run through a markup generator. That way you have full control over the markup.

Once you have that you no longer need to limit yourself to what markdown offers. Maybe you want to give authors the ability to create "warning" and "tip!" blocks when writing help manuals for example. If you define those blocks then the editor would allow the author to insert them.

What I want to see is something like Texts[0] on the web. It's WYSIWYM, I can write Markdown and see the result instantly, or if you don't know markdown use the built in toolbar to format your text. No preview mode needed!

[0] http://texts.io

Texts.io is new to me, but looks fantastic. Does it use a two window (Markdown and preview) though? I've never been pleased with the idea of my writing being available as a "preview" alongside the source, I want just one window to worry about.

Texts is single-window, WYSIWYM (“what you see is what you mean”).

Is entry of mathematical equations also visual, or that still requires learning the markup syntax?

https://www.mediawiki.org/wiki/VisualEditor is a really well thought out modern document editor. I'm slightly biased as I work for the Wikimedia foundation. I'm not on the Visual Editor team, however, I'm very impressed with what they are doing.

We already essentially do that sort of thing within Perch (see Blocks: http://grabaperch.com/blog/archive/introducing-blocks). However people still want to be able to add inline links, make things bold and italic, add headings and so on within the content fields.

One could - within Perch - make the editing incredibly granular with Blocks. We find though that whatever we do with structured content, a lot of customers will still just go with the "big textarea and a WYSIWYG".

Having worked for a long time with block-based editors in systems like Drupal and WordPress, We've found that there is a big limitation - the editor is detached from the authoring experience. We're moving on to front-end editing, and I think most CMS systems will have to do the same to stay competitive in the larger scope of things. What are your thoughts on front-end editing, more specifically, how could one apply a block-based mantra to frontend editing?

Front-end editing is one of those features that sounds like a good idea, and makes for good demo, but has some fundamental failings.

1) It sets up an expectation for the user that they are editing content on a page, as if they were editing a Word document. But they're not doing that. They're editing content in a system that then happens to be output on that page. It might also be output in other places on the site, maybe in different presentations. This causes weird spookiness-at-a-distance issues where making a change in one places has unintended consequences in another. Essentially you're presenting a metaphor of editing content on a page, but the metaphor is a lie.

2) It encourages the user to think about how the content _looks_ not what the content _says_. This is the same fundamental issue with WYSIWYG editors, where the user wants to make things big and red and underlined. And blinking. The role of a CMS user is to create content. The role of the web designer is to set up the system to publish that content in a way that communicates best according to the site's objectives.

3) The way the page looks when someone is editing on a big screen isn't necessarily how it looks to all visitors to the site. Even saying "this is what your site looks like" is a massive oversimplification. It's not even straightforward to define what a 'page' is on a modern site, and that's only going to get more complex as the web evolves. Trying to tangle your editing interface in with an ever increasingly complex presentation layer is setting the user up for a world of hurt. And lies. Hurt and lies.

It's simply not sustainable, nor a good idea to try to combine your content management and your presentation layer.

1.) There are some pretty nifty frontend editing demos that show you what the site will look like on desktop, table and mobile at once, I don't see that as a big problem. Don't really agree with it being a metaphor since most front-end plugins literally make the actual content editable on the frontend.

2.) Agreed on the formatting. But you can limit content editors by restricting the available tools and formatting options. As for the looks vs says, I think it heavily relies on the person. Some people are visual beings and perform better when they are seeing their page being built as opposed to created in a detached vacuum.

3.) #1 adresses this in part. As for complex content, we've had pretty good feedback on using blocks with visual previews on the frontend. There are issues, such as very large blocks having problems with drag-and drop, but I think these are just hurdles.

From a programmer standpoint, I guess it would be nice to detach the content from the presentation, but working "IRL" with business owners, creatives and journalists I hear almost every day about the "complicated systems" that people want to get rid of, opting for a simpler, visual experience.

Right. In the thing I am describing the editor would handle block-level things as well as inline styles and links -- all in one contiguous editing surface.

It's true though that non-technical users have an amazing ability to fall back on the most primitive tech just to get the job done.

I completely agree. The arrogance of the programmer community to say things like "we know that is bad for them" is comical but sad.

I love this approach.

I've seen too many double-pane markdown editors, which strike me as an uninspired, bloated interface.

Markdown is already readable! You don't need to waste half your interface on a preview that's visible all the time, when you can just syntax-highlight the Markdown to be its own preview.

The best interface I have seen yet allows you to switch between source and rendered text on a paragraph-to-paragraph basis[1]. There is really no reason why the text you are currently NOT editing should not be rendered. Unfortunatly this approach is a little bit more challenging to implement, why so few editors use it.

That said, I fully agree with your stance on double-pane editors.

[1] http://www.inkcode.net/qute

I have long held the same opinion as the parent comment and even attempted to build it myself a few times, but I hadn't seen qute, and I think I like that approach even better. Well, a hybrid; the paragraph currently being edited could be highlighted as markdownify does.

Markdown by itself _is_ pretty readable. Ultimately, you want to have it rendered though. This is why live preview helps me a lot. Markdown, while readable by itself, has many gotchas that may screw up the rendered result: newline here, wrong indentation there, forgot to put pipe symbol in the table etc etc. It is much easier and faster to catch these things right away than after the fact. I compare this to the on-the-fly syntax check in IDEs that saved me countless compile-and-fix cycles and boosted my productivity tremendously.

...which is why the above poster recommended syntax-highlighting. Not raw MD, but not double the output space either.

Two-pane is useful as it highlights precisely where you're fouling up Markdown in realtime. On far too many platforms (including HN) I have to go through multiple submit-edit cycles to try to fix buggy markup.

G+ is horrible at this as it parses double and single spaces differently (a double space is "<space><nbspace>").

On HN, it's the failure to recognize underbars. Since I write _italic_ and bold, I keep leaving underbars all over my comments. I'll notice and fix some of them (just nearly did it there with "some"), but often don't run across the issue until after the re-edit window has closed.

Reddit's RES double-pane editor is among the best I've encountered especially in full-screen view, screenshot:


It depends. I'm building interfaces that have non technical users and being able to have preview is important.

Having said that I can't find anything that is easily integratable with flask so I think I will go with this for now

I disagree. I use markdown as my typesetting software, and I try to create good looking documents, so seeing how it's being rendered is quite important at times.

Isn't a specialized "editor" is antithetical to the very idea behind Markdown, which is to make written text as readable as possible both in plain text and the web? Markdown syntax is already too simple. The original authors even mention "plain text e-mail" as their biggest source inspiration. [1]

[1]: https://daringfireball.net/projects/markdown/

The text is still readable as plaintext, but I think you could concede that styling it a bit does make it easier to see the effect of your markdown.

It's like how, say, Sublime text has a syntax highlighter for markdown files. Sure, you could argue that is enough to signify that the contained text is bold, but it's hard to deny that also bolding that text in the editing stage is helpful.

Syntax "highlighting" like in OP's editor will always provide more than just plain text formatting can. So it's not really antithetical anyway. Sure, markdown is made to make written text as readable as possible in plain text, but that doesn't mean it can't be even more readable in a non-plain text setting.

No, of course not. While Markdown is plain text, it is a markup language with its own syntax. This syntax is parsed by tools to transform Markdown into other formats. As it happens, this is analogous to code: encoded as text with a specific syntax.

As such, "markdown editors" are for the most part text editors with syntax highlighting. The syntax is important because it encodes the user's intent beyond the raw text bytes. Just as with code editor's highlighters, we use them because it provides an immediate and useful visualization of our intent. "Why isn't my link highlighted? OH, missed that paren." "Why is everything italic? OH, fat-fingered the closing asterisk."

So while well-formatted Markdown happens to also be well-formatted plain-text, but that doesn't mean that good authoring tools aren't needed or helpful.

I think the idea is that the web is used as a content creation tool, so we need a simple tool, on the web, to do markdown creation.

> Clients always want wysiwyg editors and you know that's bad for them, so this is a great compromise for them and for you

So far any time Ive released a content editing text area that uses markdown to the mass public, it's resulted in everyone treating it like a normal text box because they don't want to learn markdown. Wysiwyg editors, as much as we hate them, always gets much better adoption.

Markdown is primarily for writerly writers with workflows. That's where all the benefits accrue.

That's where it matters whether mark-up is done inline with content creation, or whether it's a post-pass process of fiddly buttons and menu options. That's where it matters whether the mark-up is lightweight, or overbearing. That's where it matters whether formatting is treated consistently from one piece of software to the next, or a constant surprise. That's where it matters whether the resulting file is locked away in a proprietary binary format, or not. Etcetera.

If you're building a proprietary end-to-end service -- for editing a little bit of text, storing that text, and then displaying that text -- whether your solution incorporates markdown is, at best, probably irrelevant.

I'm nodding my head in agreement to the points you make and wondering why we're not having the conversation about AsciiDoc instead, especially with regard to the constant surprise you mention.


Storytella[0] takes the same approach. It uses a Markdown editor in a single pane, no preview, which is also based on CodeMirror[1]. CodeMirror makes this kind of editor straight forward to build, with a lot of configuration and extension options. This seems to hide a lot of the configuration, so I would think is great for dropping into new admin or comment systems where you need rich text but don't want to allow arbitrary HTML.

I would consider switching over to it, as it would mean less code for me to manage, but I'd need the CodeMirror extensibility exposed.

(disclosure, I built Storytella)

[0] https://storytel.la/

[1] http://codemirror.net/

I tried building something similar to your product a couple years ago, but found CodeMirror syntax highlighting lacking since you couldn't style multiple lines which seemed like a must for Markdown.

E.g. try setex headers:

Only the ===== are styled as a header in Markdownify. Did you manage to solve it in Storytella? (too lazy to sign up and check myself, sorry.)

I've always used the starting hash header form:

# Header

## Header

So I haven't come across that issue before. Thanks for pointing out a possible issue!

I've just had a look at the Storytella editor using the === style of headers and it doesn't work. You can see it for yourself in the editor demo, here:


This is fantastic! I've seen a few of these WYSYWYG-like Markdown editors, but I like this because it doesn't come with an ugly toolbar and has automatic list, numbered list, and quote insertion upon typing the return key.

There's a lovely app for OS X called Mou that does this quite well: http://25.io/mou/

I recently switched to MacDown which is influenced by Mou and open source, it's great: http://macdown.uranusjr.com/

The problem which this is trying to solve is that clients like WYSIWYG and developers want control over their markup.

But, why not make a simple WYSIWYG -> Markdown editor? I've never found an elegant and mature editor which does this

WYSIWYGs have its own set of problems and this is why most popular websites have WYSIWYG editor but do have Markdown.

Some issues:

  - Portability
  - Error prone (want to close a bold style but can't unless you copy/paste text)
  - Doesn't work well on mobile/tablet
  - Clutter the HTML as the rendering of WYSIWYG needs a lot of wrapper

Both Wordpress and Gmail have full blown wysiwyg, and many other sites such as facebook and Twitter have wysiwyg-like features in their messaging/commenting. What site bigger than these use markdown?

What "wysiwyg-like" features do Twitter and Facebook have? I'm not aware of any.

User tagging. It's not a traditional WYSIWYG editor feature, but it means the implementation of the actual editor input field faces the same problems WYSIWYG editors do.

Wordpress WYSIWYG (TinyMCE) is notorious for bugs - I experienced them first hand - and it's not a website, it's a software people install. Big difference.

I had forgotten about Gmail, so I guess this is the exception to the rules. On the other hand, markdown is supported on Reddit, Stack Overflow, Github, and many more.

Stack Overflow and Github's primary audience is developers. Reddit's started out with a mostly developer audience and still today has a huge crossover. It absolutely makes sense to support mark down if your audience is developers.

I don't find gmail to be an exception to the rule at all - all the big webmail providers offer full WYSIWYG support.

> facebook and Twitter have wysiwyg-like features

Yeah, you see plain text, and you get plain text. Big deal.

> What site bigger than these use markdown?

reddit, stackoverflow, discourse, all use MD. Granted, none of them are bigger than gmail (AFAIK), but they do add a pretty huge base.

> Yeah, you see plain text, and you get plain text. Big deal.

Nope, not quite. @Tagging someone will suggest and highlight users. Not a full blown WYSIWYG but in the same calibre of technical problems and reasons why people stay away from WYSIWYG.

>this is why no popular websites have WYSIWYG editor but do have Markdown.


While the opposite of your suggestion, the side by side editor -> preview (like Atom has) is so elegant to me.

Really? When I re-read in the preview window and spot a typo I naturally click in the preview window to set the caret there. But of course nothing happens. I have to map what I am seeing on the right to what is on the left, find the typo again, and then do the fix. To each their own but I find it to be awful UX.

Smarts in the preview pane to reposition to the selected point in the edit file would be useful. Highlighting corresponding text -- e.g., highlight a passage on preview and have the editor scroll to the top of that section and highlight it.

I was wondering about the solution to this very problem. I, personally, like the approach of markdown and live-updated rendered HTML side-by-side with toolbar buttons for markup, the approach that MarkdownPad[1] takes.

[1] http://markdownpad.com/

A few years ago I developed a rich text to markdown converter, completely client side in the browser: http://markitdown.medusis.com

It could be a first step to build what you're descibing.


I'm still waiting for an editor that let's swap editing between WYSIWYG and raw markup (for Markdown).

(I could try to do it myself, but I'm not much of a front-end guy).

Great work! Always happy to see people working towards a WYSIWYG editor for Markdown.

I did a similar project¹, with strong focus on editing math, inline, and “real time” wysiwyg. It failed. The problem is that most such approaches treat Markdown as _code_ instead of _text_, and inevitably mistake syntax highlighting for semantic, text-driven styling (as if one would style nouns, verbs, adjectives, instead of <h1>, <p>, <em>, etc.). Thus they use a code editor such as CodeMirror (like this one does, too). And then you must style `.cm-` syntax markers instead of the eventual (html) nodes that would be the output of a real Markdown parser. Which makes it impossible to just throw in any arbitrary html5 css-stylesheet. Which is imho the whole point of wysiwyg Markdown editing.

What you’d really want instead is true Markdown parsing, which normalizes the user’s input into a parse tree, then renders to clean html. But syncing input and output over an AST is quite impossible as long as Shadow DOM is not available in browsers. Cfr interesting discussion, over at Github (re: Quill editor).²

As for Markdown parsers: there’s many of them. The OP’s project uses @chjj’s marked.js³: wouldn’t harm to mention that on the homepage or in the README, since behavior (markdown interpretation) is very different from parser to parser. (I used to maintain a repo which lists all available Markdown parsers, apps, etc.)⁴

Meanwhile there’s CommonMark⁵, of course, which has already some really fast implementations in JavaScript. (Plus, they’re “Standard” ;-)⁶ Would be nice to see one of the CommonMark reference implementations incorporated into a WYSIWYG editor like this one.

¹ https://github.com/rhythmus/mathdown ² https://github.com/quilljs/quill/issues/74#issuecomment-4294... ³ https://github.com/chjj/markedhttps://github.com/rhythmus/markdown-resourceshttp://commonmark.orghttps://news.ycombinator.com/item?id=8264733

> Clients always want wysiwyg editors and you know that's bad for them

Not a fan of wysiwyg, but a bit arrogant no?


All the wysiwyg I used are very bad. Even as a dev knowing what's up, I wouldn't use them.

What you see is very pretty, <w:ptab alighment="RIGHT" relativeto="MARGIN" leader="DOT"><p><p><p>but what you <em><strong></strong><em>get is very ugly</p></p></p><br><br></w:ptab>

The only person reading that markup is a computer...

If it works, use it. If it's visually broken, don't.

All else being equal, pick the best user experience (i.e. not the one that breaks when grandma types in an asterisk).

I wish. But really, it mess up a lot of thing.

Styles may be wrongly applied, javascript may bind to the wrong dom elements, etc.

Most of the time, everything look really good in the wysiwyg box but breaks in the website. That empty tag might have a padding that adds extra whitespace on the website. Perhaps you added a <h1> or <h2> tag without noticing and this empty tag gets added to your navigation as an empty element.

I worked on a project where the user was using and modifying the same content page for the last 5 years. The page was glitchy as hell. Trust me, it didn't even look like HTML anymore. Hell, at first glance the whole HTML code looked like a big regex.

I really have to wonder why wysiwyg is so difficult on the web when it's a solved problem on Desktop. I recommend looking at what markup iWorks Pages produces when you export to html - it's quite clean. Why not making a simple wysiwyg that

1) doesn't do any styles, it just operates using pure html tags. So no font for example.

2) cleans up empty tag as soon as possible (but at the latest when you hit save).

3) treats newlines as follows: single newline = <br>, double newline = new <p> tag. Regarding <p> tags there is exactly two states: Having one open and having none open.

Does it really have to be that hard?

This is pretty much what CKEditor does if you configure it to do that (simple toolbar, enter inserts <br>)

Thinking about it, the correct thing to do is to use <p> for each line, but allow the user to specify single or double spacing.

This is approximately what real word processors do, because often you will want one line to be left-aligned (e.g. to show English text) and the immediately next line to be right aligned (e.g. to show Hebrew text).

I have a set of utils I use to sanitize input to markdown... It's relatively limited, but it works for my needs. You could present WYSIWYG to the user, but still have a preview that sanitizes and presents the sanitized output.

I'm using this for import/export description fields... Then I replace h1/h2 with h3. It works pretty well.


Not at all. WYSIWYG never has worked well, and it's working even worse when your product is multi-channel or responsive, or mobile-first.

Sure, if you stick to simple things like paragraphs or italicizing text, it kinda sorta works, but people tend to go crazy with WYSIWYG editors trying to design an article layout of a text with them. Not a great idea.

Or tongue-in-cheek.

The developer always knows what's right for you.

People are not born knowing how to use WYSIWYG, they learn it, and it is not easy, it is not more "natural" than writing Markdown or any other thing.

Funny, this is the kind of solution that programmers come up with (as opposed to UI designers).

I use SpaceGray theme in Sublime Text which provides syntax highlighting for markdown, which I simply adore and find indispensable. One thing I always missed in it was the better formatting of different headers, I am glad to see this and other features implemented so properly.

I think I may be in the minority for just not liking Markdown in general. I don't understand the hub-bub around it.

People tend to like it because it's plain text, easy enough to sanitize input, represents most of the typical syntax people already used for a generation in marking up plain text. Doesn't require knowledge of HTML tags, and doesn't introduce the copy-paste pain that WYSIWYG editors introduce.

The thing I dislike about the hubub around Markdown is the incredible poverty of ambition. No-one has yet quite nailed the perfect web-based editor for the kind of styled text we've had in printed matter for 500 years; apparently, because of this, we're all supposed to be excited about an ugly hack for representing styled text which is arbitrarily limited by the computer systems of the 1970s. Sorry, I want something better than that.

Codemirror is such a great peace of code!

Call me crazy but I still can't see what all the hype is with Markdown, BBcode, and all these other formatting languages that come out every few years. What ever was wrong with just defining and using a subset of HTML?

Markdown and its kin are easier to read raw. Surrounding underscores, for example, break flow much less than <b> tags.

Interesting. Perhaps readability-wise yes, but in terms of actually writing it, I always find myself googling Markdown cheatsheets because I can't remember for the life of me whether single-asterisk or double-asterisk is bold or italic (the HTML counterparts are hard to screw up), and what the assortment of other symbols do. Like, my brain's parser wants to explode.

Also, * in Markdown appears to map to HTML <b>, </b>, and <li> and this drives me nuts, especially when these have to be used together.

You can produce <li> with ‘-’ instead of ‘*’. ‘-’ has no other meaning.

That's great. One thing: You may want to know that the link input is broken on the iPad. If you already have an open keyboard, you can't insert text on the alert form.

Would upload to s3 work?

For images? That would imply that you'd be serving your images directly off s3, which is more expensive than Cloudinary.

Since the project is less than 100 lines of code, I bet you could customize the image uploader to fit your needs.

I failed to see any mention of iPython notebook which does the same thing. Who borrowed from whom?

Perhaps the author independently invented the technique. Or perhaps he copied it from one of the other editors that highlight Markdown like this, such as Mou, MacDown, or Sublime Text and Emacs when using certain themes.

The WYSIWYG should be closer to the Preview for these messy cases.

You might want to consider changing the name. It's not great practice to use the name of someone else's open source thing to name yours. It's fine in the tagline.

A little confused here, what open source thing are they basing the name off of?

there is a PHP and python "Markdownify" , both are HTML to Markdown converters, so they are different to this project, there is no Markdownify in the JS world that I'm aware of.

A better name could be WYMIWYG, "What you markdown is what you get" :P

It sounded so familiar, that name. Thanks for pointing out, you are right.

WYAIWYPF (what you accept is what you pay for :))

I thought this was a Browserify extension from the naming convention personally. Not that that is enough of a reason to change the name.


Don't agree.

Meh. Still doesn't come anywhere close to Emacs and Org-mode.

Guidelines | FAQ | Support | API | Security | Lists | Bookmarklet | Legal | Apply to YC | Contact