Tumblr, Footnotes and Markdown

Tumblr, Footnotes and Markdown

Update: Hi, users of a popular search engine! You might be looking for how to use footnotes in Markdown. Here’s the TL;DR on that:

• Footnotes are just like links, except they have a caret (^) before the identifier. Like this:

• Footnotes don’t work in John Gruber’s original version of Markdown, but they do work in some variants like the one Tumblr uses.

That’s really it!

The original point of this entry was not to answer the above question–it was a long, rambling diatribe on my feelings about Markdown in general–but apparently a popular search engine has decided to show this page when people search for it! I suppose, in the end, we all exist only to serve the algorithm. Have a nice day!

–

Original entry:

When I was writing this post, I wanted to insert a footnote about the ‘first-class citizen’ reference. I’ve struggled with this before with Tumblr: there’s no easily apparent way to do this through the WYSIWYG editor, and writing the HTML by hand would be so laborious. Eventually, I gave up and posted it without the information I would have put in the footnote, because it was too much trouble.

But I was reading this blog post by Marco Arment, one of the creators of Tumblr, and noticed he had very nice footnotes. A glance at his HTML source code shows they are fairly obviously automatically-generated. So how does he do it?

My first inclination was to ask him directly, because I was sure that Googling for the issue would turn up obscenely hackish methods (later confirmed). But he’s a popular guy, and who knows if I’ll ever get a reply, and he’s going on vacation, etc. So I eventually¹ relented and did my Google search, and found the page linked in the header², which indicates that this is only possible if you use Markdown.

I didn’t even know Tumblr had an option to use Markdown; yet, I’ve always had a strong distaste for Markdown, BBCode, Wiki formatting, and all of their various siblings. They are programmer languages ³; written by programmers, for programmers, occasionally under the extremely naive assumption that they can make it ‘so easy to use’ that non-programmers could use them.

Just read this account by Jeff Atwood, one of the creators of StackOverflow. This site has a highly technical audience which is still getting confused by Markdown. I disagree with Atwood’s conclusion, though: he treats this as a user-interface design problem, but I think it’s a user interaction design problem. In that: Markdown and similar languages are too much trouble for most people to use, and if you try to force it on them, you will fail.

Please, web developers, read this quote from John Gruber (creator of Markdown) over and over again until it finally sinks in (emphasis mine):

Markdown’s popularity — still growing — is incredibly gratifying. But I never intended for it to be used by people who don’t actually know the Markdown formatting rules. I created Markdown for my own use, and, well, I know the formatting rules pretty well.

He goes on to suggest that GitHub’s variant might be improved for this audience–people who don’t know the rules–but the point is that it was never an original design goal, and GitHub and others are trying to fit it into someplace it wasn’t designed to be.

Like any type of design, user interaction design should happen from the ground up.

But, although those feelings of distaste may have contributed to my avoidance of Markdown, it’s not the root cause; I am a programmer, and I can use a programming language. But I also like to write, sometimes, and when I write, the last thing I want to be doing is programming.⁴

Writing is hard; whether it’s writing an essay or asking a question on a forum, if you want to write well, it takes a considerable amount of effort. Trying to force someone to think about conforming to a logical syntax at the same time as everything else that’s involved in writing is like throwing mental roadblocks in their way. It’s just cruel.⁵

Tumblr is very well-designed, and I suspect it is for one or more of these reasons that the default is WYSIWYG. But some people do like Markdown, so it’s nice that it’s an option.

In any case, I have tended towards WYSIWYG widgets, even though I know HTML and dozens of other markup languages: I want to write without the hassle of coding.

But I have felt for a while now that I am still spending an inordinate amount of time appeasing the system when I’m trying to write. I have to click to make a link. Click to make a quote. And when I copy and paste a quote, I have to first paste it into TextEdit to remove the font size and colour⁶, so that it won’t look weird on my site. In a post like this, where I might have nearly a dozen links, it feels like a lot of distractions.

Indeed, sometimes when I have an idea I want to jot down quickly without going through that trouble, I end up putting it in a plain text file and marking up links with [square bracket numbers], with the intention of going back and inserting them later. It ends up being halfway to Markdown anyway.

So I am giving Markdown a chance. I went back and added that crucial footnote to the earlier post. And so far, I have written this post in entirely in Markdown⁷, and it’s surprisingly bearable. I think I will continue to do so and see how it goes.

Still, I wouldn’t recommend it to any of my non-programmer friends. And, going back to the original point of this post, there really should be some way to make footnotes using the WYSIWYG editor.

---

1. This may be obvious, but in case it isn’t: if you’re ever writing to an even somewhat famous person, try to keep your question to no more than 1-2 sentences if at all possible. It drastically increases the likelihood that you’ll get a response.

2. This post I’m writing here is a ‘link’ post, which, to me, means its content is principally related to a link to somewhere else on the web. On Tumblr, this means it gets linked as the header text of the post. Yet, often times, the post is a journey of discovery, wherein I don’t end up mentioning this primary link until halfway down the post. At that point, it’s clumsy for me to refer back to the link all the way at the top, and I haven’t figured out a good way of doing it. I could link it again, but that would be redundant. I could just make the post a ‘text’ post instead of a ‘link’ post, but that would be favouring presentation over semantics. ↩︎

3. Not to be confused with programming languages , which Markdown is not. Let’s not even go there. ↩︎

4. Even if I’m writing about programming. ↩︎

5. And if you’re providing a service that you’re making a profit from, it’s a bad way to treat your customers. Spend some extra time and effort on programming and make it easier for them. ↩︎

6. Incredibly stupid default. Probably not Tumblr’s fault. ↩︎

7. As you can probably tell from the footnotes. ↩︎

What exactly is '3G', anyway?

What exactly is ‘3G’, anyway?

Turns out it’s ‘whatever your cell phone company wants you to buy right now’ (paraphrasing).

If the carrier sold you “384 kbps Internet access anywhere in the coverage area, outdoors,” that would be something you could hold them accountable for. The carrier might even have to put a brake on signing up new customers until it could build new towers or license more spectrum for everybody to share, if it made that guarantee.

Ars user comments on an SQL injection story

Ars user comments on an SQL injection story

Incredible display of cluelessness.

How to disable Facebook's new location tracking

How to disable Facebook’s new location tracking

The latest stupid thing you have to turn off.

It sounds like a DJ remixing a recording of R2-D2 being eaten by a Bantha.

It sounds like a DJ remixing a recording of R2-D2 being eaten by a Bantha.

—Ars Technica’s Ryan Paul, on Droid 2’s default ringtone

We pay the fear tax every time we spend time or money seeking reassurance. We pay it twice when the act of seeking that reassurance actually makes us more anxious, not less.

We pay the fear tax every time we spend time or money seeking reassurance. We pay it twice when the act of seeking that reassurance actually makes us more anxious, not less.

—Seth Godin

Initially, I saw Chopper 2 as roughly twice as complicated as Chopper 1, so thought it would take twice as long. But this was a mistake. I’d neglected to think about all the complexities introduced by the relationships between all of the new features. An analogy would be a number of people shaking hands. Two people means one handshake, but double it to four people and you get six handshakes. Much of the coding complexity is in the handshakes.

Initially, I saw Chopper 2 as roughly twice as complicated as Chopper 1, so thought it would take twice as long. But this was a mistake. I’d neglected to think about all the complexities introduced by the relationships between all of the new features. An analogy would be a number of people shaking hands. Two people means one handshake, but double it to four people and you get six handshakes. Much of the coding complexity is in the handshakes.

—David Frampton

James Gosling's interesting aside

James Gosling’s interesting aside

As an interesting aside, that commitment to interoperability is why Apple dislikes Java. Having OS X apps run on Linux or Windows doesn’t make them happy. Apple wants to add your technological distinctiveness to their own.

That’s ignorant. Apple made Java a ‘First-Class Citizen’ (cf. WWDC 2000¹) on Mac OS X. Their goal was to make Java apps on the Mac look just like native apps. They even went so far with this notion that they wrote the first version of System Preferences in Java. (This had to be pulled and rewritten before the final release because performance was so awful.)

Apple bought into Sun’s hype that Java was The Future. When Java languished in consumer obscurity, that was Sun’s doing, not Apple’s. And yet, Apple continues maintaining Java on Mac OS X, to this day, 10 years later, in order to make sure it’s integrated well. What other operating system vendor does this?

Java isn’t on iPhone because third-party runtimes are not on iPhone, and Java is a third-party runtime. Just like Adobe, Sun decided to take this personally. But since they want to go that route, fine: everyone knows Sun had their chance in the consumer marketplace, and they blew it.

---

1. I couldn’t find a primary source for this, presumably because it was so long ago in internet time. But if you Google ’java first-class citizen wwdc 2000’ you’ll find a lot of offhand references to it. ↩︎

By the way

Hi again. Yeah, I’ve been busy.

iTunes option to fit more songs on your iPhone/iPod - Marco Arment

iTunes option to fit more songs on your iPhone/iPod - Marco Arment

I noticed this when it first appeared (not sure when) and have been using it ever since. Highly recommended.

If you only buy music from the iTunes Store (at 256kbps), this effectively doubles the capacity of your device. For music from other sources, it will vary depending on the import settings, but there is likely to be some improvement.