Markdownify
tibastral.github.io
tibastral.github.io
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.
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.
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".
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.
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.
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.
[0] http://texts.io
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.
Having said that I can't find anything that is easily integratable with flask so I think I will go with this for now
That said, I fully agree with your stance on double-pane editors.
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'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.
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.
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.
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 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)
E.g. try setex headers:
Header
======
# Header
## Header
So I haven't come across that issue before. Thanks for pointing out a possible issue!
But, why not make a simple WYSIWYG -> Markdown editor? I've never found an elegant and mature editor which does this
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).
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 wrapperhuh?
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.
I don't find gmail to be an exception to the rule at all - all the big webmail providers offer full WYSIWYG support.
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.
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.
It could be a first step to build what you're descibing.
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/marked ⁴ https://github.com/rhythmus/markdown-resources ⁵ http://commonmark.org ⁶ https://news.ycombinator.com/item?id=8264733
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>
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).
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.
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?
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'm using this for import/export description fields... Then I replace h1/h2 with h3. It works pretty well.
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.
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.
Since the project is less than 100 lines of code, I bet you could customize the image uploader to fit your needs.
**foo*f**f*
A better name could be WYMIWYG, "What you markdown is what you get" :P