All of the following not “to” anyone in particular, just my personal feelings on Markdown.
The first problem I had… have… with Markdown is that it flew in the face of another markup I had been using before I came across it. Many non-WYSIWYG wiki products used a fairly standardised wiki markup and, in my opinion, did a much better job of being obvious and simple.
Using # for headings is fine in itself, but it is better suited to numbered lists — one of the non-tech uses of this symbol is literally to mean “number”. The wiki markup was a ! at the start of the line. As ! is used in non-tech language to convey increased emphasis, it seems logical for headings.
Markdown numbered lists use actual numbers, which is not how HTML does it and for very good reason. The writer should not have to concern themselves with which number goes where. Even if the conversion takes care of stripping the numbers out, it’s an unnecessary distraction in the text.
[Some words](some link) has taken me years to get used to because I could never remember whether it was [some words](some link) or (some words)[some link]. Some people might even try [some link](some words) or (some link)[some words]. There is nothing natural or obvious about this construct, you just have to learn it by rote. If we can at least learn that the link follows the words (which is not true in HTML) then the normal wiki syntax is, I feel, simpler: [[some words|some link]]. The wiki markup I used had various other sorts of linking which all occurred in [[ ]] and always separated parts with a |, you only had to learn which order the parts went in.
Being designed for direct conversion to HTML may seem like a power move, but the problem comes when something is not supported by Markdown. Because you will then have to edit the HTML to achieve it — the precise job Markdown was trying to avoid.
See my points above — knowing HTML can be just as much of a burden when using markdown. Particularly <a href="link goes first">Text goes second</a> versus [Text goes first](link goes second). If I had to choose between writing web content in HTML and Markdown, I would choose HTML and employ snippet expansion, because I find HTML more obvious and it has much, much more flexibility, even in basic content.
I think if everyone was told “it’s like shorthand” then it might not be so divisive. Like shorthand, you’ll almost certainly need to transcribe it and do more work later if it’s for anyone’s consumption other than yours.
Another reason for using Markdown is that it will future proof your notes. I still vividly remember having a folder of Pages documents and at some point Apple completely changed the format and I had to keep around an old version of Pages just to read them (when was this? 2009?). I converted them all, but that was a pain. At this point I realized that any binary format like Pages or Word is not a great long term storage solution. Markdown is just plain-old ASCII, which any computer in the future will be able to read. So even if Obsidian or every other markdown editor is gone, you will always be able to open and read the files.
Also flagging that Markdown isn’t really a syntax Gruber imposed on the world. Some stuff was obviously added, but there’s a sense in which Markdown grew out of how people were already writing before “rich text” was super-common.
It’s great for formatting relatively simple stuff like emails - one of the many reasons I like MailMate. It’s also great for not having to hop out of your writing flow to add basic markup.
It’s obviously not a replacement for more advanced tools. But it is a reasonable, quick solution for a number of use cases.
I had this issue, not remembering which syntax was the link. But my brain made sense of it by thinking - [ ], looks heavy, so the anchor. But ( ) looks light and almost disk like, so it has to " fly" to the destination.
One nit: Markdown numbered lists aren’t "1, 2, 3, … ". I usually use “1, 1, 1, …” - as that allows for reordering. (I think Drafts is nice in this regard.)
That for me is the big advantage. Most of my non-academic notes involve only the most basic formatting as they’re meeting notes or scripts. For those I rarely need more than bold, italic, headers, the occasional link and block quote. (I admit I use Highlighting ::word:: a lot in Ulysses which is non standard).
Concentrating on content and not format is wonderful, especially since Ulysses* can export the text to PDF or Word in different presentational formats (eg large font size PDF for reading from my iPad, normal size font to provide a copy to others for printing, export to HTML to put a copy on the website, large print export of the agenda for someone with sight issues.)
I don’t specifically write in Markdown purposely, but I do write a lot in Obsidian and Drafts which are Markdown.
I tried going to a plain text route for note taking, but found it really hard. For example, I like making notes using bullets and numbers, but you have to type them in yourself, with no indentation or anything. Equally you can’t write things in bold or italics, nor can you have headers with different formatting, which makes writing and re-reading my words more difficult.
Markdown gets around this enabling CMD+B for bold, etc., and Obsidian and Drafts both have some auto-formatting that means my bullet and number lists auto-populate and indent as I’d like.
In short, for me, markdown is a means to an end to get a document with a bit of nice formatting, and removes friction when I am writing and want some basic formatting. It also means I can change apps without extracting my data (as I did back in the day with Evernote).
iA Writer and Obsidian both have keyboard shortcuts for most Markdown syntax. For example, I’m constantly using Cmd-K to add links. Is that any harder than learning the keyboard shortcuts of Pages or Word?
I switched to Markdown for writing several years ago and now it’s tough to go back. Formatting is mostly similar across most things that are compatible with Markdown, which is an advantage over learning keyboard shortcuts for each app. Creating headings and modifying heading weights is a good example of this, as well as lists, code blocks, and links.
You can’t do everything in Markdown and images can be a real pain, but it lets me write most of what I need to write without taking my hands off the keyboard to click buttons or learn app-specific shortcuts, which is great.
I use Typora to make things like adding images easier (just drag and drop), but the bulk of my Markdown writing happens in Sublime Text with the MarkdownEditing extension.
That is an excellent way to sum up Markdown. I have certainly tried to explain that concept many times over the years, but never considered using the word “shorthand,” which works very well in conveying intended Markdown’s use.
@zharj, I find your specific criticisms of Markdown interesting. I too used a wiki markup language which had the same/similar features to what you describe (PMWiki IIRC). I already was familiar with Markdown when I was first introduced to the wiki markup and while I found the design choices to be reasonable, I didn’t ever find them to be “better.” In some cases I actually prefer Markdown. For example, while using ! for headers makes more logical sense, I found that # stand out much better when reading the text. I would often miss that a line was a header because the ! is such a narrow character and I would miss it completely. I have never had that problem with #.
Regarding lists, I am indifferent. I suspect that if I had designed Markdown I would have made different choices, but I’m fine with either design.
Regarding links, I have never had the problem you describe (confusing which part comes first etc). I always think of it as being similar to how links are often represented in print (ink & paper). Immediately following the link label in the text the URL would appear in parentheses. Same for Markdown. And of course, the label itself is wrapped in square brackets similar to wiki syntax. Also, as I mostly use reference links, I learned early on to only use square brackets. The parentheses only every get used in the unlikely event that I am using an inline link.
Finally, the fact that you can just include raw HTML right in your Markdown is one of its best features. I find other markup languages extremely limiting in this respect.
Regardless, I too do not like all of Markdown’s design choices. From time to time I have considered designing my own markup language. But why bother? I’m not interested in marketing and shepherding it over the coming years. And well, Markdown works well enough for my needs so I overlook the few irritations.
My point was they use numbers. People will approach those in two ways:
Make them accurate, creating an editing chore if re-ordering or inserting or deleting
Make them nonsense, such as 1, 1, 1.
The second approach is arguably just saying “numbered lists can be marked with 1 or 2 or 3 or 4…” in the same way that “bulleted lists can be marked with * or + or -”. Using numbers this way is not really symbology and, worse, it pretends to be the final output, which it isn’t.
The goal of Markdown is to be simple. I say “pick a number but not a real number” isn’t as simple as it could be.
To quote Gruber:
The first time I read that it bent my head a little.
Those were features exactly as I am describing, as I also used PmWiki.
Wow!! I never thought my initial post would spark such discussion! Awesome! I just wanted to let everyone know that I have found a great use case for Markdown in Drafts. I can write online content offline, click the HTML button to copy the text (translated into HTML) to the clipboard, and then paste it into my CMS! Great! I even got the paid version, so I can have all sorts of Actions!
I am now looking at Obsidian as a way not only to write web content offline, but also organize it into a file structure in folders to create more of a file system and archive. I therefore hare two questions:
Does Obsidian have an HTML button similar to Drafts to allow translation to HTML before pasting it into my CMS; and
Does Obsidian have a view that allows me to see the formatted text without the Markdown code, so when I view the completed work later, it is WYSIWYG?
Awesome! Thanks! I am just having trouble figuring out how to invoke the plug-in and copy HTML to the clipboard. Tried looking in pull-down menus, context menus, etc., but no go. Must be something simple I’m missing!
