Hey, You Got Your Web Platform Docs in my Brackets!

bracketsI 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.

webplatform

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.

w3c_home

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:

  1. Put your cursor on a CSS Rule and press Ctrl-K on Windows / Cmd-K on Mac.
  2. Right-click to bring up the context menu and select ‘Quick Docs’
  3. From the menu toolbar, choose View -> Navigate Quick Docs

And this is what you’ll get:

Screen Shot 2013-04-29 at 2.45.52 PM

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:

Screen Shot 2013-04-29 at 3.41.35 PM

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.

edge_code_mnemonicBut, 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!

Tagged , , , , . Bookmark the permalink.

5 Responses to Hey, You Got Your Web Platform Docs in my Brackets!

  1. Pingback: Hey, You Got Your Web Platform Docs in my Brackets! – Brackets Blog

  2. Tri Nguyen says:

    If you are to create an API with the web platform docs and make requests there each time it is used in Brackets instead of having it come installed, would that mean it won’t work if a developer is coding without any Internet access? Probably a small use case, but I’m interested in how you solve that issue.

    • agreenblatt says:

      I don’t think that’s a small use case at all Tri. If you are building a mobile application that relies on Web Platform Docs, it’s important to take into account the case that people might not always have Internet access. Access could be intermittent. As explained in the article, Brackets does not make calls to webplatform.org every time the extension is used. Instead it uses a locally cached version of the results. I would recommend you do something like what I have in the version of the extension on GitHub: https://github.com/awgreenblatt/InlineWPD. Cache the results, and update the local cache on some regular basis (perhaps check the time of the local cache and only update once every few days), and when you have Internet access. Otherwise, just use the values from the local cache.

  3. Pingback: Web Platform Docs API used in Brackets | Web Platform Blog

  4. Pingback: First Web Platform Docs Tool Integration! | Digital Media Blog

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>