I was recently talking to Adam Lehman, product manager for Brackets, about ways I could potentially help contribute to the product, perhaps by writing an extension or two. I wanted to learn how to write a Brackets extension, but I also wanted my efforts to go into something people would find useful, something of real value. It turns out, my timing was impeccable.
Web Platform Docs is mature enough that it is time to use it as a source for documentation in Brackets. Adam suggested that an extension that provided dynamic inline access to Web Platform Docs as users are editing code would be immensely valuable.
Web Platform Docs, in case you’re not aware, is this amazing initiative undertaken by the Web community as a whole to, well, document the Web. If you’re a Web developer, there are several different places to go for the latest set of CSS properties, for example, to understand what they are, what their potential values are, and so on, but there is no comprehensive and authoritative source. The docs.webplatform.org site is a Wiki designed for just that purpose. There you’ll find reference documentation, starter guides, best practices, and a whole lot more. And, since it’s a Wiki, the site is constantly growing and being revised.
But don’t be mistaken. This isn’t some random marketing effort. Web Platform Docs was initiated by the W3C, and is support by the Web Platform Stewards.
I thought this would be a great starter project, something to really sink my teeth into, until of course reality set in. I needed to provide some time estimates so the Brackets team could plan accordingly. I had never coded up a Brackets extension before. How could I even estimate a guess? We scheduled a meeting for a week later to check in, see how things were progressing and then come up with some reasonable time estimates.
By the time we had our first check-in meeting a week later, I had about 90% of the plugin finished. It turned out to be much more straightforward than I anticipated. Since Brackets itself is written in HTML/CSS/JS, and the extension architecture is so well thought-out and straightforward, if you know these core technologies, the learning curve is pretty minimal. Most of what you’d want to know can be found here, and there are a bunch of sample extensions in the distribution that are great starter points.
You can find what I created up on GitHub. To be honest though, there’s no real reason to use that code other than to see what you can create on your own in very little time. The Brackets team took my extension, cleaned up the code here and there, revised the UI layout, and released Brackets Sprint 24, with an improved version of the extension integrated right into Brackets core!
There are three ways to call up the CSS property documentation:
The left pane contains the summary, and the right pane is a scrollable list of potential property values. In addition, you’ll see a “Read More” button. Clicking that button will take you to the source Web Platform Docs page in case you want further information (or if you want to contribute). The information you see above is all gleaned from: http://docs.webplatform.org/wiki/css/properties/align-content
The naive implementation (and thus my first iteration) has the extension making the appropriate set of requests to webplatform.org for every user request for CSS property documentation.
But, if every Brackets user (and thus Edge Code users with free Creative Cloud memberships) were making these requests every time they wanted a particular property’s documentation, that would be incredibly slow and a completely unnecessary burden on the server.
As well, there are security implications of dynamically importing remote code into an application running on your desktop that need to be considered.
In the meantime I think you’ll agree that it smokes. The documentation response time is immediate.
You can find the latest milestone Brackets build here.
I have to admit I was hesitant at first, but more and more I’m finding that Brackets is my HTML editor of choice. And now with Web Platform Docs integration, it’s even more powerful.
Brackets and Web Platform Docs – Two Great Tastes That Taste Great Together!