Kristian Freeman Engineer at Simple, musician, and some dude in Portland.

Standard Markdown

Markdown powers a huge portion of the web. If you've used Reddit, you've used Markdown. As the story goes, John Gruber wrote Markdown, then left it be. For ten years. Seriously - the canonical Markdown has had one update, in 2004. At a point pretty early in Markdown's life, John considered it complete.

In the ten years after that, Markdown has become huge. If you're a programmer, there's a pretty high chance you write Markdown every day. For me, it is writing on the internet. I use it on GitHub to communicate with my team, I use it on Reddit in my free time, and I use it to write this website. There's no denying that it has been a huge success.

But it has problems. John left the spec intentionally ambiguous, with lots of room for interpretation. Some have taken this ambiguity and rolled with it; for instance, GitHub Flavored Markdown adds powerful syntax highlighting and task management features that are hugely helpful to programmers on a daily basis.

Enter Standard Markdown. Initially announced by Jeff Atwood, Standard Markdown intends to be the definitive version of Markdown, serving as a spec for writing new Markdown parsers, and testing existing ones. From Atwood's September post:

We formed a small private working group with key representatives from GitHub, from Reddit, from Stack Exchange, from the open source community. We spent months hashing out the details and agreeing on the necessary changes to turn Markdown into a language you can parse without feeling like you just walked through a sewer – while preserving the simple, clear, ASCII email inspired spirit of Markdown.

In programming, ambiguity is not good. Ambiguity can mean edge cases, spotty testing, or incomplete implementations. Markdown is most certainly ambiguous - the above-linked Babelmark highlights a large amount of edge cases that need resolution. It's very likely Markdown will never solve those problems: John isn't going to update it, and he is the sole owner of Markdown.

So a standard seems reasonable. GitHub, Reddit, and Discourse all heavily use Markdown, and are in a position of "authority" when it comes to a hypothetical Markdown spec. The heavy usage of Markdown on these sites means that the creators of Standard Markdown know what they're talking about. They've encountered some of Markdown's ambiguities and have, in most cases, written solutions to overcome them. No one is denying that if someone were to take over Markdown, these companies would be the ones to do it. Here's the problem: they don't own Markdown. Standard Markdown is an appropriation of something owned by someone else.

Markdown has forks: Fletcher Penny's MultiMarkdown and GitHub's GitHub Flavored Markdown are both hugely popular and add a ton of additional features that the modern web needs (tables, anyone?). But Standard Markdown doesn't position itself as a fork. Arguably the primary contributor, John MacFarlane, is an owner of the Markdown organization on GitHub. The official Markdown implementation doesn't appear on GitHub, yet it would appear, without prior knowledge of Markdown's origins, that the project is actually owned by the Standard Markdown group.

Interestingly enough, Jeff Atwood's post on Standard Markdown is titled "Standard Flavored Markdown", yet the additional "Flavored" isn't mentioned again at all in any other documentation on the project. It can't be accidental - the title and the slug of a blog post are so important that I think it's impossible Jeff missed it. Regardless, the website, the forum, everything regarding the project besides the CodingHorror post removes the "Flavored". It's almost as if they began with the intention of releasing it as an obvious fork, then later changed their minds.

The debate over Standard Markdown's validity has been taking place on Twitter for a couple days. Gruber, who is famously tight-lipped about Markdown, posted a set of tweets both under @gruber and @markdown (notice the ownership there) regarding Standard Markdown:

The solution? Just add "Flavored". Instead of appropriating a project that millions of people view a year, make the effort to show that this is another implementation. It might cost you a bit of money and time to re-brand and re-deploy servers, but if the option exists where all parties can be satisfied, why not take it? Standard Markdown is a good and useful idea - unfortunately, it will be hard to use in good conscience.

Finally, from the Markdown license:

Neither the name “Markdown” nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.


UPDATE: A couple hours after this post went live, Standard Markdown was renamed to Common Markdown. Atwood even elaborated on the naming process, which, as I suspected, started with Standard Flavored Markdown:

... So I originally wrote the blog post and the homepage using that terminology – "Standard Flavored Markdown" – and even kept that as the title of the blog post to signify our intent. We were building Yet Another Flavor of Markdown, one designed to remove ambiguity by specifying a standard, while preserving as much as possible the spirit of Markdown and compatibility with existing documents. Before we went live, I asked for feedback internally, and one of the bits of feedback I got was that it was inconsistent to say Standard Flavored Markdown on the homepage and blog when the spec says Standard Markdown throughout. So I changed them to match Standard Markdown, and that's what we launched with.

I'm glad to see this happened. Props to the Common Markdown team for listening to feedback, even when it was fairly angry.

Confirmable buttons in Ember

An interesting pattern I've run into a lot with Ember is the idea of "confirmable" actions. Actions are really easy in Handlebars templates, but for certain actions that are "destructive" (think saving, deleting), it'd be nice to have a "confirm" option.

In Rails, the usual pattern is to pass in data-confirm (fake code follows):

<%= link_to "Delete post", posts_path, method: :delete, data: { confirm: "Are you sure?" } %>

This could work in Ember too, using the confirm() function in JavaScript. In my last Ember project, I built something that was a bit more interesting, and would be worth sharing. Using Ember, we can build a confirmation flow that fits into our existing user interface. Here's an example:

Ember Starter Kit

Let's walk through that code.

// IndexController...
status: "not hacked",
hacked: Ember.computed.equal('status', 'hacked'),

This example deals with setting an attribute, namely status. status initializes as "not hacked" - our goal is for hacked, a computed property on status, to become true (when status == 'hacked'). If hacked is false, we show our component, AppConfirmableComponent.

The bulk of our code is here - when the component is "confirming", we show a new button similar to the confirm() function in native JS. Otherwise, we show our normal function - note that the text is passed in.

timeToConfirm: 5000,
confirming: false,

The beginning of our component sets two important attributes: the time the confirm button will stay active (here at five seconds), and confirming to default to false.

actions: {
  confirm: function() {
    this.sendAction();
  },

  startConfirming: function() {
    this.set('confirming', true);

    Ember.run.later(this, function() {
      this.set('confirming', false);
    }, this.timeToConfirm);
  }
}

The confirm action is simple: it calls the passed-in function from the controller view. Note that this.sendAction() is a Ember.Component method that relies on action being passed-in from the template.

startConfirming is a bit more complicated, and showcases the magic of Ember that allows this flow to be possible. It begins by setting confirming to true, which shows the "Are you sure?" button in the template. It then defers setting confirming to false by timeToConfirm, which is five seconds by default. An advantage to using Ember.run.later is that Ember defaults to asynchronous behavior - if you had multiple of these buttons (say, one per item in a list), each would independently operate and hide the "Are you sure?" button on their own timer. The example below shows two buttons operating on independent properties - try clicking on both and waiting for them to return to their normal state.

Ember Starter Kit

This is a pretty simple example of the power of Ember components and its async behavior that is super useful. "Confirmable" actions are a pattern that I see in REST applications all the time that can be a lot cooler with Ember's tight UI control.

Reactive development, with Ember

I've been thinking a lot over the past couple months about satisfaction, specifically in regards to work. Satisfaction is:

fulfillment of one's wishes, expectations, or needs

Satisfaction is different from happiness. I can be happy writing code; I almost always am happy when I'm writing code, even if it's a particularly difficult or frustrating day. Satisfaction is different. I tend to think of something as satisfying when I'm not working. If I can look back to a project or even just a particular day of writing code positively, that's satisfying.

I wrote in August about an Ember project that I had been almost entirely focused on at work in the last couple weeks. In the evenings, when I wasn't working on it, I couldn't stop thinking about it. It was a peculiar feeling, one that I don't feel that often.

I've been reflecting on why I felt that way about the project over the last couple weeks, and I think I can summarize it into one word: reactive.

Ember apps are live, for lack of a better word. Two-way bindings between variables and functions mean that everything in the app is composed in a way that it will never be out-of-date. For instance, updating your profile email on an account page could actually change your avatar live on the header of the website. It's a type of instant feedback that doesn't exist in Rails applications.

Developing an application like this quickly becomes a fun (yes, fun) process when you have to debug them. The Ember Inspector for Chrome allows you to play with everything client-side on your application. If you need to test an observer that updates on a rare basis, you can trigger it via the Chrome Console with ease. Testing controller methods in Rails is the opposite - you can either write it entirely in isolation and then write tests, or you can just do the action. If the action is something that is destructive or can't be reversed, this can be really dangerous. With the Ember console, you can pretty easily test functionality on the spot without actually destroying anything. The development process is incredibly rapid because of this - faster than any other development process I can think of.

I'm super excited for the future of Ember, and for web applications in general. I'm looking forward to EmberConf next year, and I'm hoping that as it matures, I can continue to move projects to a isolated backend and Ember frontend architecture. I really think client applications are the future of web apps, and I think Ember is leading the path.

Initial Ember.js impressions

I had the chance to write a fairly complex Ember.js app solo over the last couple weeks. While I had worked around the edges of one at my previous job, this was a great opportunity to start from square one and make design decisions on my own. The resulting application benefited from the tight UI handling that Ember provided, and it was a marked improvement over what a Rails-based solution (as it runs inside of a Rails app) would have looked like.

Spoiler: setting up an Ember app inside of a Rails app is not fun, or easy. I learned this through a couple versions of the app, all working around the Asset Pipeline's benefits and/or limitations:

  1. Single page. All the JS and Handlebars files lived in a single .html.erb file that was wrapped by a stripped down version of the app's application layout file. This was the simplest and bare-minimum implementation of an Ember app, and works great if you have an app of low complexity. This starts to become a problem when you're abstracting pieces of UI out into separate views or components and begin to have a pretty beefy tree of UI components. This version also didn't use Ember Data, so the concept of a model was more or less hard-coded into the view, by dealing with the JSON responses.

  2. Split JS files. By using Rails' great require_tree method, the actual JS source of the Ember app could be taken out of the view file and put in its own directory structure. I chose a structure mirroring ember-cli's, which is also pretty similar to Rails:

Directory structure for Ember App

  1. Handlebars in Asset Pipeline. This was the most difficult part of the process, but also the biggest win in terms of code structure. In ember-cli and other JS-based build tools for Ember, the Handlebars templates become JS as part of the compilation process. In a base Rails app, Handlebars templates live as script fragments with type="x/handlebars" set on them. This means that the closest thing you could get to separating them into separate folders is loading them as partials. They're still under .html.erb files, but they don't all live in one file. This solution worked, kind of - it quickly became a pain to load each partial into the main view every time a new file was made. The solution was a gem called handlebars_assets, which adds Handlebars templates to the Rails asset pipeline. Because we were already using it inside of the project, the set-up process wasn't too difficult. The only problems that I ran into were loading the Handlebars templates with other, non-Ember .hbs files in the project. The solution was two-told: the "Ember Support" section of the guide suggested setting .multiple_frameworks = true in a HandlebarsAssets initializer, which required renaming the templates to a .hbs.ember structure. Second, the Resolver on the app needed to be overridden to deal with the namespacing of the templates (for example: app/index):
Resolver: Ember.DefaultResolver.extend({
  resolveTemplate: function(parsedName) {
    parsedName.fullNameWithoutType = "app/" + parsedName.fullNameWithoutType;
    return this._super(parsedName);
  }
}),

The final implementation of the application structurally resembles a Rails app, in that all the files are loaded given that they're inside the correct directories. This kind of solution would have just worked if it was an ember-cli project, but it was useful to go through the different versions as the app grew in complexity. I think that for single-page applications, storing everything on a single page is fine. It can get unruly very quickly, but the process for dealing with loading of multiple files in a directory structure isn't super easy; it's up to the developer's discretion, in the end.

As for the project itself: Ember is great. The application is a queue process for dealing with various requests that fall under different categories and statuses - processing these through Ember's ArrayController was super easy, and the bindings were super useful in re-sorting the data when it changed. All of that, once again, just worked, and it was awesome to have the part of the application I was least excited about writing come for free.

One of the biggest wins in development came fairly late in the process, when I introduced Ember Data to the architecture. All the data in the application is retrieved with basic JSON calls to the supporting Rails controller: I opted to use RESTSerializer in this instance as it seemed to have more documentation. ActiveModelSerializer probably would've been a wiser choice in the long-run - I ran into a lot of problems with having to re-wrap the data with root keys and data relationship stuff that I hope would be fixed with the AM serializer. One of the more interesting problems I had to deal was the usage of UUIDs as a primary key: luckily, support for that came fairly easily, as you can override model-by-model serializers:

App.UserSerializer = DS.RESTSerializer.extend({
  primaryKey: 'uuid'
});

The win with Ember Data came when the application started to need to know more about the parent models for the primary data in the application. For instance, as we began to need to know more about the person who created the model instance and the user it was in regards to. Both of these came super easily with the addition of a hasMany or belongsTo in the Ember Data models for the base queue object. Because the service was powered by basic REST, it was literally the addition of about four lines of code to make it work. Awesome.

One of the most amazing parts of developing with Ember is the Ember Inspector for Chrome. The below image (from the extension page) is an example of what an Ember app looks like with the extension enabled:

Ember extension on Discourse

Every part of the app - from the UI-side (views, components) to the backend (controllers, models) are accessible and queryable from the extension. One of its killer features is the ability to send any section of the app to the console as the variable $E, which can then be explored like a REPL. It's a great way, for example, to test if your bindings work - by doing $E.set('something', 'new') you can see if the various computed property functions are updating as expected. It's also fun for the instances where you come across an Ember app in production: it's just as easy to explore as a development app. Vine's official site is a great example of this.

Overall, I'm super stoked with the last couple weeks I've spent with Ember. It's very well thought-out and any problems I've had have turned out to be user-error, not a framework problem. I'm really interested in, given the time, converting a good deal of my projects over to a light backend (maybe in Sinatra or rails-api) and a Ember-based frontend. It seems like this is the way that webapps are going in the future, and Ember (in my opinion) is leading that charge.

Robin Williams

Claire and I watched Mrs. Doubtfire last night. It's probably the only way you can memorialize an actor. Is there a different way to mourn someone you don't really know then appreciating and revisiting their work? Robin Williams was brilliant in that movie. One thing I didn't remember from seeing the film when I was younger was that it's not just a kids' movie. It's about something that's hard: losing people, whether for a month, or forever, is terrifying. Robin's character navigates that in the best way he knows: acting, playing, and learning. There's something we could all probably benefit a bit more from, in our own lives.

Depression is shitty, and scary. Sometimes it surrounds you like a big ocean and makes it hard to find your footing. Other times, it's like a rusty car that you can't quite clean: there's dark cruft around the edges, and in the cracks. You can't completely 'clean' it. There's an awful stigma in the world about mental illness, where people either deny that it exists or that the amount of people that it affects. It's not based on class, or race, or gender; it's everyone.

It's hard to help someone with depression. You think you know all the answers to their problems, and you just want to shout "HEY! Please listen to me." But that isn't the solution. Everyone is different, and to be there for someone with depression, start by just being there. It's been interesting to see the varied responses to Robin's suicide - frustrating to see responses like "why couldn't he just be happy", and inspiring to see the outpouring of support for those in a similar situation.

These things are really hard. If you need someone to talk to, shoot me an email or check out places like Reddit's /r/suicidewatch which, despite the fairly intense name, is full of people who are there to help. There's always help out there. <3