Welcome to Fuck Yeah Markdown

What? Where am I?

You’re at Fuck Yeah Markdown, one of the best places on the net to learn about Markdown: what it is, why you want it, who’s using it, and when and where it works. Well, it will be, anyway. Right now it’s just the home of Marky the Markdownifier, a tool to take existing HTML web pages off the web, extract the main content, and turn it into Markdown so you can store it as plain text. Whether you keep your notes in raw Markdown (text files, Notational Velocity, nvALT, etc.), or render them into HTML or Rich Text for another organizer (Evernote, Yojimbo, etc.), Marky will give you clean markup and easy-to-edit notes. Questions? I’m here for you.

Markdownifier

My name is Marky. I make the web smell like Markdown.

Enter a url below to convert the page to Markdown.

Try it out with a (somewhat) random link

Why didn’t it work? I want my money back!

The Markdownifier will do its darndest to get you some Markdown, but there are times that it just can’t pull it off. As a general rule: garbage in, garbage out. If the html markup on the page is incorrect or too complex, poor Marky will choke. There are plenty of other factors, such as redirection, SSL connections, timeouts and other fun, but he’s been doing a pretty good job in testing. If you have a specific page you think should be Markdownifiable, send it to me. I’ll see what I can do.

F.A.Q.

What’s a Markdown?

It’s actually just “Markdown,” and it’s a plain-text syntax for document markup built by John Gruber. It takes plain text and magically makes it into perfectly-formed HTML. It’s simple and intuitive, and once you learn 6 or 7 basics, you’re off and running (additional/alternative documentation at TUAW). Thanks to Fletcher Penny and his MultiMarkdown project, you can even create beautiful PDF’s and LaTeX documents. If you’re so inclined, you can turn Markdown into a Word file… without ever having to use a word processor.

All of this means that if you build a web-clipping system based on Markdown, you’re guaranteed a Spotlight-indexed (on a Mac), UNIX-searchable, easy to maintain and totally portable solution for storing information. Plus, with a few tools you can make look really pretty when you read it. This is where Marky finds his place in the world.

What’s a Markdownifier?

That one actually gets the singular article. It’s a tool that goes in the opposite direction, turning HTML into Markdown. It uses the Readability algorithm to determine what part of the page is actually of interest, cutting out the ads and comments and such. What you get back is a plain text representation of the page, ready for adding to any text-based note taking application, or just storing in text files on your disk. Sometimes it doesn’t work. I’m just letting you know.

I’m scared, can I just stick with HTML instead?

Yes, just check the “Preview as HTML” box, and you’ll never see Markdown. You really should try Markdown, though. It’s easy and fun at parties. The Preview as HTML option will actually do the Markdown conversion, and then convert back to HTML, giving you very clean source code that won’t cause issues when pasted elsewhere.

How much data are you collecting about me?

I’m running Google Analytics on these pages. I know how many people were here, what browsers and platform they were using, and that’s about all. If you want to, you can even block those and pretend you’re a ninja (you’re not, but if it makes you feel better…).

The pages you view are not recorded by me. There’s no database here at all. I’ll eventually get around to adding a means for voluntary submission of sites that work and sites that don’t for the improvement of the app, but right now… well, there’s no shame in being too lazy to put together a full-on web app in two days, is there?

Can I take it home with me?

You’re in luck. Bookmarklets that should work in your browser are available below. Appropriately, you’ll find them in the “Bookmarklets” section.

I have big ideas, got an API?

There’s something resembling an API for this thing. See the API section below.

Who are you and what are you doing here?

My name is Brett, and I don’t like sleeping. This insomnia leads to weird and sometimes silly projects. This is one of them, but I’m still uncertain as to whether it’s weird, silly or both.

To whom are you indebted for this thing?

John Gruber, creator of Markdown, for making the Markdown Kool-Aid.

Milian Wolff for Markdownify. You can spend all day messing around with XSL sheets and Pandoc tricks, but Markdownify is the hammer that smashes HTML into line. And into Markdown, more to the point.

Michel Fortin for PHP Markdown. Also, on an unrelated note, for Magic Launch. I love that app.

Keyvan Minoukadeh for PHP Readability. It’s one of the better ports of Arc90’s original. I’m working on tweaking a few things for my specific needs, but it was pretty darn cool to start with.

How frequently are these questions really asked?

At least once, each. Some more than others.

Bookmarklets

Copy this link to your toolbar to get your Markdown fix on any page
(with decent markup)
Readability→Markdown
Copy this one to your toolbar to get readable HTML for the current page
(again, clean markup needed)
Page→HTML
…and this one to get your markdown without using Readability
(markup shmarkup, but it might not be pretty)
Page→Markdown
This one returns the markdown with no frame or frills
(or squat if it can’t find the content section)
Readability→Markdown (raw)
This one clips the current page as Markdown
to Notational Velocity or nvALT (depending on which one your
system has assigned to the "nv://" url handler)
Clip to NV
Clip to nvALT
This one does the same as above, but gives
you a chance to add NV/nvALT tags before it runs.
Clip to NV w/tags
Clip to nvALT w/tags
More to see…

There are more options and combinations available. I’m working on a “bookmarklet builder,” but in the meantime see the API section below for additional parameters you can add to the bookmarklets to modify their behavior.

Marky also works well from the shell, and thus from Launchbar, Alfred, System Services and more. See the post on brettterpstra.com for more information.

API

All of the magic happens at http://fuckyeahmarkdown.com/go/. It will accept a GET or POST call, and the following query parameters may be added to the url to modify the results:

  • One of the following is required:
  • u: url encoded URI to parse
  • html: HTML text to be Markdownified. May be a full page or snippet, and can be submitted as urlencoded text in a GET call or straight using POST (suggested for larger requests).

  • read: (optional, default 1) whether to run Readability or not, 0 turns off
  • md: (optional, default 1) whether to run Markdownify or not, 0 turns off

  • output: (optional, default markdown) type of text to return (json*, url (encoded), or markdown). There's also an 'nv' output mode that will generate a Notational Velocity/nvALT url for creating a note from resulting text. If you need the 'nvalt://' handler for older versions, use 'nvalt' for the output mode instead. Might be useful for some people.
  • tags: (optional) if the output type is "nv" or "nvalt", adding this key with a url-encoded string of space or comma separated tags will include them when importing into NV/nvALT.
  • preview: (optional, default 0) whether to run the result back through Markdown and provide HTML instead of Markdown
  • showframe: determines whether or not the output is encased in the HTML frame for viewing/copying

  • domarkdown: (any value will run this) used without the other parameters (including u), and takes a text parameter containing url-encoded Markdown text. It returns raw HTML (snippet)

*Sample JSON output:

{
           "title":"Every Keyboard Needs A Share Button",
           "content":"# Every Keyboard Needs A Share Button\n\nFebruary 7th,
            2011\n\nI thought of this idea a few days ago and
            [...truncated...]
            "
        }

Special list

If a url matches a regex in the “special” list, some parameters will be overridden:

  • Twitter user streams
  • Lifehacker articles

This list will likely grow as people let me know where they’re having trouble using Marky and I work around issues.