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 turned out, the timing of our meeting was perfect.
Web Platform Docs is mature enough to use it as a source for documentation in Brackets. Adam suggested we build an extension to provide dynamic inline access to Web Platform Docs as users are editing code.
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.
Building Brackets Extensions is Surprisingly Straightforward!
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 plugin 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!
Activating the Extension
There are three ways to call up the CSS property documentation:
- Put your cursor on a CSS Rule and press Ctrl-K on Windows / Cmd-K on Mac.
- Right-click to bring up the context menu and select ‘Quick Docs’
- From the menu toolbar, choose View -> Navigate Quick Docs
And this is what you’ll get:
The left pane contains the summary, and the right pane is a scrollable list of potential property values. In addition, you’ll see a button:
Clicking that button will take you to the source Web Platform Docs page in case you want further information.
The information you see above is all gleaned from:
http://docs.webplatform.org/wiki/css/properties/align-content
Performance and Security
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.
As a result, we decided that for this initial release, the documentation results would be preprocessed and packaged with Brackets and Edge Code. Moving forward, we are working with webplatform.org to develop a suitable API that is fast and secure. In subsequent releases of Brackets we will have updates to the packaged CSS documentation, and ultimately the results will be dynamically updated in a secure and efficient fashion.
In the meantime I think you’ll agree that it smokes. The documentation response time is immediate.
Try It Out
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!
