Markdown is inevitable
Java 23 and Google Docs show that developers want only one thing and it's disgusting. And by "disgusting" I mean "Markdown."
Developers reach for Markdown when they need to style text in programs. There are a few reasons for this.
Their editors and IDEs make it easy to work with plain-text files.
Text is easy to store.
Markdown is readable even when it’s not rendered into HTML.
Every file is valid Markdown. So even if something doesn’t behave correctly, the rendered output is still usable.
It has built-in support for code samples.
Any computer-literate person can learn Markdown with just a cheat sheet.
Every major language already has libraries that render Markdown as HTML.
Markdown isn’t fussy. It looks nice. It plays nicely with systems that developers already use. It has become the closest thing to an “official text markup language” that modern software developers have.
So it came as no surprise when I joined the Google Docs team in 2010, it only took a few months before I cornered our product manager and tech lead and asked them, “why don’t we add support for importing and exporting Markdown?”
I don’t remember what they said. So here’s some historical fiction. This is the information they communicated, but it has been dramatized for effect.
They exchanged significant glances like a child that just asked where babies came from. They knew they had to give me The Talk. They had given this talk countless times before.
“Sweetie”, one of them probably started. “None of our users ask us for Markdown. Nobody tries to import it for conversion. Businesses don’t ask for it in contract discussions. The only people who ask are Googlers, and they’re not our typical user. And it’s questionable whether exporting Markdown is even sensible! Its job is to be rendered into HTML. Why wouldn’t we just export the HTML? And for logistics, the document conversion team is 15 time zones away. The communication overhead is a nightmare. And finally and most importantly, Microsoft has a 25 year head start on us and we need to implement dozens of major features just to catch up.”
When taken together, this is a solid argument for deferring implementation. But Markdown is inevitable. It will happen.
What do I mean by inevitable? Consider Java. It was almost a decade old when John Gruber first specified Markdown in 2004. Text markup is a big part of Java’s development experience. Roughly speaking, Java code is organized via classes. Each class has its own file. A developer might want to know the purpose of the class, as well as any extra information about what each class method does.
At launch, Java introduced a system called Javadoc enabling developers to document all of this information in their classes. Javadoc is two things: a markup language designed to document Java classes, and a command-line program that generates HTML documentation from the markup in the files.
Because it produces a website, Java developers can quickly answer any question they have by just consulting the relevant generated page. If they don’t want to do that, they ALSO have the option of reading the Javadoc annotations in the source code.
You can read some examples on Oracle’s documentation page, but it’s a clunky mix of HTML and has some extra directives that provide functionality like links.
Let’s recap. So we have markup language. It is used by developers. It is supposed to be readable in its unprocessed format. It also generates HTML. Does that remind you of anything?
So anyway, Markdown ate Javadoc. Java 23 shipped with an implementation of a proposal, JEP 467, defining how to specify Markdown instead of the Javadoc format.
From JEP 467
Summary
Enable JavaDoc documentation comments to be written in Markdown rather than solely in a mixture of HTML and JavaDoc
@
-tags.Goals
Make API documentation comments easier to write and easier to read in source form by introducing the ability to use Markdown syntax in documentation comments, alongside HTML elements and JavaDoc tags.
Do not adversely affect the interpretation of existing documentation comments.
Extend the Compiler Tree API to enable other tools that analyze documentation comments to handle Markdown content in those comments.
The Java team rolled out the red carpet. Since every text file is a valid Markdown file, it gets its own custom comment syntax.
The Javadoc syntax has probably existed for 30 years, which is older than many current Java developers. And those developers will probably switch to Markdown as soon as they learn that their company has upgraded to Java 23.
Why did I start this newsletter issue by talking about Google Docs and then transitioning into Java? Well, Markdown ate Google Docs too. Now you can paste Markdown content into Google Docs and it’ll be pasted as regular doc content. It even ate the right-click menu. If you select some text and right click it, you will see 3 Markdown-related options at the time of publishing. That’s a huge amount of vertical real estate in the context menu.
And in the official Google blog post, they don’t shy away from identifying developers as a motivating factor.
From Import and export Markdown in Google Docs
Who’s impacted
End users and developers
Why you’d use it
This update is particularly useful for technical content writers as they can now convert Docs content to/from Markdown. For example, developers can collaborate on software documentation in Docs and then export it as Markdown for use in other Markdown supporting tools.
And developers noticed. The Hacker News thread got over 650 upvotes. This is popular by Hacker News standards. The author of the change commented on the Hacker News thread. People showered him with praise [0] and asked a lot of questions. The answers were good and almost everyone was happy. It was wholesome to see a Google engineer get direct credit for something they worked on.
But let this be a lesson for you. Even if it’s not the most important feature you could support today, Markdown is inevitable. If you have a text field that renders into HTML, and even a single developer uses it, you’re doomed. You will get an increasing number of feature requests from developers that they should be able to write Markdown in that field. They will follow you. You will dream of them. Markdown is inevitable.
Footnotes
[0] The top comment is critical of the rollout strategy used by the feature. As a rule, the first comment on any Hacker News thread is critical of the thing it’s responding to. Even if it were something like “Mr Rogers was nice.” You can safely ignore this comment.