This is a subject I am interested in, so I began your article eagerly, but had to stop about halfway through out of frustration. Please consider these as the constructive suggestions that I intend them to be:
Think about the story you want to tell. Maybe make an outline or diagram, marking at which points you will introduce which facts.
Example: For some reason something called Commonmark is abruptly mentioned, with a link to spec documents that would seem to be of only technical interest. What is this, and how is it connected to anything else?
Do enough research so that you know the highest peaks in the landscape. Why describe the foothills and take no notice of the prominent mountaintop right in front of us?
Example: the bits about the comics were fascinating. But where is Pandoc? I don’t think I’m guilty, here, of demanding that you write the article I would have written. But Pandoc is the application of Markdown. It turns Markdown into a way to author HTML, TeX, PDF, Office formats, and a lot more. It‘s huge.
Anyway, I like the look of your site (but agree with others that you should not hijack browser shortcuts).
Once you know about pandoc, you orient all of your prose around it, because it's so powerful and useful.
But before you use it, the common opinion is "oh that sounds nice", not "oh let me build all of my workflows around it".
It is incredible how far markdown, sed and pandoc (with filters) can take you!
I've made websites with breadcrumbs, validated inter-document links and images, on and on; mostly pipelines with sed and pandoc.
All of my non-source-code homework in college went through pandoc, and was persisted as markdown source. It makes for clean diffs, and great version history.
One of the prouder moments in life was convincing a legal team to convert a folder of Word docs to Markdown, check them into GitHub, and set up a CI/CD pipeline to convert them to PDFs to sharing.
> One of the prouder moments in life was convincing a legal team to convert a folder of Word docs to Markdown, check them into GitHub, and set up a CI/CD pipeline to convert them to PDFs to sharing.
Why would you want to do that?
I mean, I don't understand why would anyone have to have and maintain a CICD pipeline just to be able to share a PDF.
For a PDF? No way! For a whole set of PDFs sharing the same template, some containing auto-generated data and with builds triggered by external events? Oh yeah!
Also, read the second half of my other reply for the other reasons it was adopted.
> For a PDF? No way! For a whole set of PDFs sharing the same template, some containing auto-generated data and with builds triggered by external events? Oh yeah!
You do not need a full blown CICD pipeline or git or anything at all to do that. Even LibreOffice, of all things, has doc templates and doc includes.
Hell, have you ever heard of TeX/LaTeX? People have been using it for decades for the same effect. You write the text, generate the doc, and you're set.
There's no need to go all-in on a resume-driven-development rampage. I mean, why on earth would anyone force any cleric worker to read up on GitHub Actions just to be able to send a report? You can't really justify that, can you?
It's a fascinating achievement! I, and others at my org, want to do this for technical writing. Some want LaTex -- others Markdown -- so we must answer that question first.
Did you implement an example for them, demonstrate, and get acceptance?
- Finding an editor that felt comfortable. (BTW, iA Writer is awesome for this.)
Easy parts:
- "You never have to care about formatting again!"
- "Two people can edit stuff at the same time and we can work out the differences later, instead of playing the 'who has the most recent version?' game."
- "Look, you just write text and a nice document with logos pops out the other side, and all of the documents look nearly identical without even trying!"
- "Git shows you the full history of every line of this file."
- "Hey, cryptographic signatures you can use to irrefutably prove the history of the document!"
- "This 'pull request' thing in GitHub shows you exactly the changes you made, like 'track changes' except they're all in one place!"
The easy parts are what make it a selling product.
I'd love to see "github for non-developers", that is little more than a markdown-app, with a thin wrapper around some git server and pandoc.
Most CMSs implement all the hard stuff (version control, document generation) themselves, but exposing some of the "knobs" of pandoc/markdown/git and letting users run amok is kind of all you need to do, imo.
Confluence is kind of like this, but limited to the production of web pages.
Sort of. (See my last sentence in the above sentence, about how “confluence is close”).
Wikis are limited to rendering information in a webpage format. The benefit of pandoc is that you can render it in any format you like, with arbitrary filters and styling.
So you can display the content in a webpage, but you can also render it into PDFs with full legal headers and footers, and footnotes with links, to be physically printed and mailed to people.
It’s a level of abstraction once removed from a wiki.
Was Markdown really sufficient for you? I’ve tried to do this for a contract workflow, but always needed something like Asciidoc to get sufficient internal references, header numbering, tables, etc
And it’s true that’s it’s hard to take account of your own perspective. It’s possible to write a kind of story of Markdown and not make Pandoc a big part of it. But it seems like a glaring omission to not even mention it. It‘s what makes Markdown a real lingua franca, what gives it real power.
Author here, appreciate the feedback! I got caught up a bit in the story of the inspiration behind Markdown (email for Markdown, typewriters for Textile), what I'd assumed was competition between Textile and Markdown (when it turned out they were more connected that you'd think just by seeing two "competing" standards on the market), and how this standard of sorts in Markdown both came from all these inputs but then was flexible enough that everyone can write how they prefer and also that others can take the Markdown idea and run with it and make their own thing.
Pandoc would have absolutely been worth mentioning; that's definitely more on the modern look at how Markdown itself got remixed and taken further, but definitely relevant.
The article seems to gloss over the enormous contribution CommonMark made to ensuring a consistent and versatile interpretation of markdown, mostly by examining edge cases no one thinks about until they appear in the wild.
Author here: Goal here was to focus more on what led to Markdown itself, with a bit of details around how other takes (MultiMarkdown, CommonMark, GitHub Flavored Markdown) took it further, in the same way that Markdown in some ways took ideas from earlier formats further or honed them down to fit what Markdown was aimed at. There's definitely space to dig into the whole family of plain text syntax both before and after Markdown (including things like Org-mode, C2's wiki markup, Pandoc, Todo.txt, and more that were mentioned elsewhere in this discussion).
Just one of the great things Aaron Schwartz was involved in. So sad we lost him so young. I really do believe the Internet would somehow be a different place now if he was still around.
Am I the only person that gets annoyed that every single site wants to implement their own special and incompatible subset of markdown? Yes, I'm looking at you HackerNews, who makes it hard to block quote.
But on other sites, yes, it's very irritating that I can't count on support for things like tables or checkboxes because those are extensions to Markdown and not part of CommonMark or the original reference everyone implemented from. Or how some sites get finnicky about whitespace around list items.
I wonder why this is. Is it because there aren't enough HN users who would actually use markdown formatting (I know I would!), because it's too much work to implement, because "if it ain't broke...", or for any other reason?
The one and only reason I feel like that's not _such_ a bad thing is that once you do that, you know more people will drop tons of code samples in posts making the discussion a lot less easy to browse.
Currently people often use these code block-ish things for quoting text, for lack of a better option.
This is completely unreadable on mobile for lines of any significant length, because the block itself is a box about half the width of the screen that doesn't wrap and must be scrolled horizontally.
Minimal features and css are all well and good as long as they work properly ;)
It's the same idea even if they don't call it markdown. It's yet another formatting language to learn and occasionally confuse with similar things on other sites, and will occasionally bite you when you least expect it.
For example:
I never shop at WalMart because WalMart doesn't pay their workers a living wage.
Author here: Absolutely. Or how apps like Notion "eat" Markdown, turning it into Rich text when you paste it in but then if you copy the text you pasted, you don't get the Markdown copy but instead get their rich text conversion.
Also amazes me how Markdown basically has become a generic term—Slack referred to their plain text markup as "markdown" when it was actually closer to Textile (with single underscores for italics and single asterisks for bold, versus single of either for Markdown italics and double of either for bold).
That's perhaps the greatest downside to Markdown is that you have to almost check your copy and see how it looks in many web apps (seems native Mac/iOS apps are more likely to implement it well).
This is why I don't use Markdown: There is no such thing as Markdown. There are 1000 different parsers that have the word 'Markdown' in their names, but that's chaos, not a format.
I need features Gruber's Markdown doesn't support, so I have to use some other 'flavor' of Markdown. Ten years from now, how am I going to even know what to use to parse those files?
So now I just use org-mode for everything. It's more obscure (because Emacs) but there aren't 1000 different flavors of it.
CommonMark is not trivial to implement efficiently... and not all sites need as much functionality as CommonMark provides. So, would you prefer sites to invent something completely weird and new each time, or use something more familiar that looks like a subset of markdown? Sure, it can be done better or worse, but I don't think the concept is wrong. But honestly, many comment systems only have italics, quotes, lists, urls and maybe code, bold text and images... most of which have been indicated in plain txt files for a long time in quite consistent ways, hardly Markdown's trademark markup.
Author here: Ohhh that's one I wish I hadn't missed, thanks for mentioning it. Ward's contributions with c2 keep showing up in different places, as you mention here with plain text formatting, and in other ways with for example the backlinking that's popular now in Roam Research, Notion, and every other personal notes app that suddenly is making the personal wiki a reality.
Oh man, a standardized plain-text email formatting! I can't believe I hadn't come across that before. I just added a brief mention of that to the article with a credit to your comment; that's absolutely something worth including.
Author here: Org-mode would have been another good one to cover, thanks for mentioning that. It was started right in the middle—Textile came in 2002, Org-mode in 2003, Markdown in 2004. Makes me think of Todo.txt also, which came a couple years later. There might be space here to dig into the whole family tree of plain text formatting syntax.
Appreciate everyone's feedback on the the search pane. I think it feels better in other parts of our app where you can use it as a command palette of sorts to navigate, but you're right, it makes it hard to search inside longer blog posts like this. You can press CMD+F twice in a row to get browser search, but that's definitely a bit of extra trouble. We'll have to work on this!
As someone else pointed out, the discoverability of CMD-F twice in a row is nil, and frankly it annoyed me so much I wouldn't notice any instructions that were in the pane unless they were right at the top in big, apologetic letters.
This article mentions CommonMark, and skips lightly over the fact that it was hastily renamed that from Standard Markdown after Gruber threw an enormous hissy fit over users improving something he hadn't touched for twelve years: https://blog.codinghorror.com/standard-markdown-is-now-commo...
I don't want to rehash that whole thing, but I totally agree with Gruber in that case.
The "Standard Markdown" name really implied a degree of canonicity and authority over Markdown, even though it was neither created by or endorsed by Markdown's creator.
CommonMark also only changed the name from "Standard Flavored Markdown" to "Standard Markdown" after sending a copy to Gruber, so I'm sure it at least felt very dishonest.
The new name is clearer, and it's been a settled issue for the last 6 years. I'm not sure why the article would have gone into more detail about it.
What, did Gruber invent the practice of putting asterisks around text? The article made it clear he did not. Did Gruber invent the name "Markdown" from whole cloth? No, it is a pun based on the word "markup". Did the Standard Markdown consortium make changes that broke compatibility with Gruber's users? No, because nobody was using Gruber's perl parser. Were they competing with the standard Gruber wrote? No, because he never wrote a standard.
The article spends a great deal of time explaining how markdown codified existing conventions. It describes, not invents. Gruber didn't create markdown, because it already existed. Should he then hold the privilege to control it in perpetuity?
I've always known Gruber for only two things - suggesting the idea of Markdown and throwing hissy fits!
From the last paragraph of the Coding Horror post you linked -
>> after a long and thoughtful email from John Gruber – which is greatly appreciated – he indicated that no form of the word "Markdown" is acceptable to him in this case.
I read that and thought to myself, “The only thing this Lee Phillips person is managing to convince me of is that Lee Phillips is a dick”. Then I came back here and realized that’s you.
It's quite the essay, defending a man who purchased a house for a low price and made a piece of art decades ago, and continues to extract value from both without making any additional meaningful contributions as regards either. It's almost... like he's seeking... rent. I wonder if there's an economic term for this behavior or any theory about whether or not it should be rewarded.
If only we'd have bots on here, I could post this comment automatically, as I haven't seen anyone use the term correctly in the say 2/3 years since it became hip to mention it every time someone makes money in a way someone else has an ideological problem with.
How is he extracting value from the house by living in it? As the market value goes up, it costs him more, as his property taxes will go up. As to the photograph, well, he owns the copyright. Period. You may not think we should have copyright, but that’s another conversation.
You might find readers more sympathetic to your post if you spent more time on the copyright issues and less on telling us repeatedly that other people's taste in music is wrong
I used the name as it was when he created the thing I was talking about. This is a problem that arises whenever a scholar or artist changes his or her name, say by getting married. If you use the new name, nobody will find the reference. So I’m not sure what’s correct in all cases.
That's not unreasonable, but she started transitioning over 50 years ago. I think it's appropriate to refer to her as Wendy now, as Wikipedia and all the online music stores I just peeked at do.
I didn’t know that. (But I just looked it up and you’re right.) At the time, it was a secret, so as far as the world new, “Switched on Bach” was created by a man named Walter Carlos. The public didn’t know about Wendy until many years later. But, from a scholarly point of view, you don’t go back in time and change the names of authors. You generally refer to the author’s name as it was at creation.
The writing style of your article seems more personal and narrative-oriented than scholarly, to be honest. It might be better to reword it if you want your personal blog to have a more academic perspective.
Whatever the merits of the argument, the author of this article sounds pretty judgemental. To quote:
"The photographer happens to be the great Jay Maisel. I feel on fairly safe ground saying that any one of his photographs is worth more than all the “chiptune” ever produced."
I haven't heard of the cover album before, but thanks for linking it. It doesn't sound the opening track is using actual hardware (such as a Ricoh 2A03 or a Konami VRC6), but the cover of All Blues almost has a Tim Follin feeling to it.
I had always thought that Gruber was the guy who created it. This makes so much more sense. I couldn't make sense of it - it always felt like someone else with a different kind of capability had created it.
If you google "markdown" it says "Developed by: John Gruber (in collaboration with Aaron Swartz on the syntax)"
He wasn't. There was a movement amongst wiki engines to come up with a common markup format. c2 was the first but didn't participate in that. They were mostly php, perl and python engines sharing this code.
We had a good common markup long before Markdown, but Markdown got popular with Wikipedia, which also refused to participate. Eventually everybody switched over to Wikipedia syntax, which was then simplified to Markdown. I never saw Swartz taking part in those discussions, we just took his RSS idea.
All right, let me offer a different phrasing: Aaron Swartz created atx, and John Gruber created Markdown. The syntax between the two is similar, but not identical, as can be said for several other "plain text markup" formats that are, you know, not Markdown. (Like Textile, which was also not created by Aaron Swartz.) Not insignificantly, the original Perl script that implements Markdown was John Gruber's. It functions as a plugin for the Perl-based Movable Type blog engine because that's what Daring Fireball uses. Swartz wrote atx, by contrast, in his preferred programming language of Python.
I was introduced to markdown via RStudio. But what I really use the most nowadays is markdown for making notes during meetings etc, using a minimalist editor (Typora). I just wish it weren't so complicated/ugly to copy/paste markdown to/from other tools, like Outlook or Confluence.
I use only the basic and common syntactic elements (lists, headings, italics, links). IMHO the beauty of markdown is its simplicity, and trying to do complicated stuff like diagrams and tables is best left to other tools. (Another problem with the more ambitious uses is that they tend to not be standardized across markdown implementations.)
Author here: Agreed on it being better to do advanced stuff in other apps. I found it interesting that the original Markdown launch posts basically say that. Textile was trying to cover the vast majority of HTML; Gruber with Markdown basically said that this is to simplify writing for the web, and if you need HTML, you can just include HTML inline for extra stuff beyond the writing basics.
I've always found it strange that such a strong Mac advocate as Gruber was behind Markdown. After all, the Mac was doing real rich text in 1984, and with just one more push in the early browser days we might have got there for the web too.
Instead we're left with this inconsistent mess — hell, even Gruber gets his own link syntax wrong from time to time - because good enough was the enemy of better.
Author here. I think, for one, Markdown's focus is on writing for the web, and there rich text wasn't good in 2004 (where copying/pasting from say Word into WordPress was always hit and miss, and rich web editors were far less advanced than the Webflow's of today), and was inspired by email where plain text stayed the standard longer than elsewhere (especially on Apple products, where into the late '90's the main Mac mail app and the NeXT email app that turned into today's Mail.app both were plain text editors for sending email).
It would be interesting, though, if Tim Berners-Lee's original dream of dream of the web being somewhere everyone edited had come true, then if better quality rich text editing for the web would have shown up sooner.
Yes Markdown was fundamentally a hack around the limitations of <textarea>, especially as used in CMS interfaces like Movable Type. In my alternate timeline, 90s Netscape would have added rich text support to those (likely submitting HTML, a subset of what Composer already supported) and saving everyone to come a startling amount of effort.
It does also play into the TBL vision like you say - it would have meant everyone was writing HTML (and with tool interfaces there to help non-technical people not have to care) rather than a small group writing HTML and everyone else using baby markup.
Rich text editing doesn’t demand a mouse: it’s the same number of keystrokes to press cmd-b as it is to do shift-8. But if the intended output is rich text, then wysiwyg is a better interface for editing, yes. Not everything needs to degrade to a teletype.
Not usually, no. But applying formatting on top of selection is another rich text benefit: with text selected cmd-B makes it bold, shift-8 just replaces the selection with an asterisk (in a standard text field)
cmd-B does nothing in a standard text field. If you mean text fields with code to handle keyboard shortcuts, you can just as easily have cmd-B surround text in asterisks as trigger wysiwyg bold formatting.
Markdown is plaintext, because of e-mail, which works best as plaintext. A plaintext format is much easier to write consistently, without issues like invisible formatting [0] (which will bite you when editing), or Microsoft Word’s decision to make your ordered-list markers bold because some part of the previous line or this line is bold (and I’m almost convinced the algorithm for that is closely linked to rand()).
It doesn't even work! Ctrl-F "commonmark" shows zero results, even though the text is in the article. Pressing Ctrl-F twice to get the actual browser search does let you find it, but some fuckery has broken the scrolling to the result so you still can't find it easily.
It's more a UI problem, not having a tip telling the user you can do that.
Stripe's API reference[1] was one of the first to do this, and I really enjoy it. In their popup modal thing they tell you to press CMD/CTRL+F again if you want to browser native find functionality.
It's uncommon enough that none of the ton of websites I visit (a healthy mix of tech, gaming, hobby, news and other sites) employ this trick. Call it what you will, UX or UI: it's still poor, as in "nonstandard" and "confusing".
The goal is to make it easier for users to perform a site-wide "find".
You can easily disable it by using the checkbox on the bottom right of the overlay that appears; then cmd+f will behave similar to your browser's setup.
Few people want to do a site wide search and the ones who do will press the input box on the top left. No one expects that ctrl-f will open a site wide search, everyone expects a page search.
If you still want to enable this ctrl-f to enable the site wide search, I suggest making it opt in with the checkbox. It's really obnoxious to have to disable the checkbox.
If regular users find it helpful, maybe advertise this as an opt-in feature?
To be honest, the non-standard behaviour plus strange looking popup confused me. I didn't even notice the tiny checkbox, nor that you could press CTRL+F again to get the standard search behaviour. My mistake, of course, but this speaks of poor UX in my opinion...
Please don't override default keyboard shortcuts. The sitewide search is a nice tool, but if I wanted to do that I would search on your site. Novice and advanced users want CTRL+F to behave as they are expecting, not bring up an unfamiliar (and unrelated) tool. For example Google Sheets also hijacks CTRL+F but at least it replaces it with something that operates extremely similar to the original action.
Why should a browser allow its own shortcuts to be overridden at all? At the very least, some form of warning or permission-granting should be involved.
They're permitted to be overridden so that we can make web applications. It makes sense for sites like Google Docs or Sheets to override many of the defaults as, once loaded, it's replacing a desktop application and the common access patterns of it. It's less applicable (and very annoying) on sites meant for presentation or consumption of information.
That I would agree with 100%. It'd be nice to have a panel of all the shortcuts and their present meaning available, with the option to rebind them or remove site-local bindings.
The user could get the option to prevent (by default) changes to bindings, with the option to permit them on a site-by-site (or even page-by-page) basis; or to allow them by default and then deny them on a site-by-site basis.
Yes. Discourse does this to great effect. It searches the whole “page” by default, when all the content for the “page” isn’t actually loaded in the browser.
The problem is that our fancy new infinite scrolling pages break ctrl-f in browsers, as they cycle content in and out based on the viewport or collapse threads by actually removing the content from the page.
The downside is that the site's built-in search feature is always worse than ctrl-f at finding something on the page. Always. It shouldn't even be hard, but they're always returning garbage like 8 year old posts on completely unrelated articles instead of the stuff on the page you're currently viewing, and advanced mode is usually broken in weird and confusing ways. It seems like web designers are optimizing for the thing you never do.
This is a subject I am interested in, so I began your article eagerly, but had to stop about halfway through out of frustration. Please consider these as the constructive suggestions that I intend them to be:
Think about the story you want to tell. Maybe make an outline or diagram, marking at which points you will introduce which facts.
Example: For some reason something called Commonmark is abruptly mentioned, with a link to spec documents that would seem to be of only technical interest. What is this, and how is it connected to anything else?
Do enough research so that you know the highest peaks in the landscape. Why describe the foothills and take no notice of the prominent mountaintop right in front of us?
Example: the bits about the comics were fascinating. But where is Pandoc? I don’t think I’m guilty, here, of demanding that you write the article I would have written. But Pandoc is the application of Markdown. It turns Markdown into a way to author HTML, TeX, PDF, Office formats, and a lot more. It‘s huge.
Anyway, I like the look of your site (but agree with others that you should not hijack browser shortcuts).