The Story Behind Markdown
capiche.com
capiche.com
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.
Anyway. Give pandoc a try if you haven't already.
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.
Also, read the second half of my other reply for the other reasons it was adopted.
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?
Did you implement an example for them, demonstrate, and get acceptance?
What was the resistance? How was it overcome?
- It's Markdown, not Word
- 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!"
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.
Aren't you describing a wiki?
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.
I’m teaching my children to write their school papers in markdown for similar reasons.
I use a github PR to provide feedback.
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.
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.
HN's doc on formatting: https://news.ycombinator.com/formatdoc
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.
In particular, for a website that heavily covers software and engineering, it's a pain that it doesn't have a good way to format code.
``` this should be formatted as four lines of code with line breaks at every newline without having to indent every line with spaces ```
Currently people often use these code block-ish things for quoting text, for lack of a better option.
Minimal features and css are all well and good as long as they work properly ;)
For example:
I never shop at WalMart because WalMart doesn't pay their workers a living wage.
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).
Now it's fractured so much it's just a pain. Is this vanilla markdown or am I in Github markdown? Or my wiki markdown?
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.
<script src="https://unpkg.com/showdown/dist/showdown.min.js"></script>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!
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.
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?
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 really couldn't believe this!!
I guess I’m the dick now.
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.
Not contributing anything? It says right there in the article that he is cleaning the graffiti and rehabbing the house.
he owns the copyright to a piece of pixel art created as a tribute to his famous album cover photo?
This is a hilarious way to look at it. Please, will the rich of the world burden me with their wealth so that I may pay the tax for them?
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.
"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."
http://www.aaronsw.com/2002/atx/intro
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)"
This now seems like a gross misrepresentation.
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.
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.)
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.
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.
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.
In rich text interfaces, keyboard shortcuts do more and work better than they do when typing Markdown in pure plain text environments.
That you can build better keyboard shortcuts for plain text areas is of course true, but it’s still a hack on top of a hack.
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.
Every standard interaction started out non-standard, after all.
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.
This search interface has been a huge hit with our regular users, but it's harder to get feedback from fly-by traffic, so this is really helpful.
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...
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.
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.
I just switched to reader mode and used Command-F there instead.