Docs: fix markdown in various files, update the README mildly

sky/specs/apis.md

 APIS
 ====
 
 The Sky core API
 ----------------
 
-```
+```javascript
 module 'sky:core' {
 
   // EVENTS
 
   interface Event {
     constructor (String type, Boolean bubbles, any data); // O(1)
     readonly attribute String type; // O(1)
     readonly attribute Boolean bubbles; // O(1)
     attribute any data; // O(1)
 
@@ skipping 193 matching lines @@
 The Sky IDL language is used to describe JS APIs found in Sky, in
 particular, the JS APIs exposed by the four magical imports defined in
 this document.
 
 Sky IDL definitions are typically compiled to C++ that exposes the C++
 implementations of the APIs to JavaScript.
 
 Sky IDL works more or less the same as Web IDL but the syntax is a bit
 different.
 
-```
+```javascript
 module 'sky:modulename' {
 
   // this is a comment
 
   typedef NewType OldType; // useful when OldType is a commonly-used union
 
   interface InterfaceName {
     // an interface corresponds to a JavaScript prototype
   }
 
@@ skipping 28 matching lines @@
 
   // the module can have properties and methods also
   attribute String Foo;
   void method();
 
 }
 ```
 
 The following types are available:
 
-* ```Integer``` - WebIDL ```long long```
-* ```Float``` - WebIDL ```double```
-* ```String``` - WebIDL ```USVString```
-* ```Boolean``` - WebIDL ```boolean```
-# ```Object``` - WebIDL ```object```
-* ```InterfaceName``` - an instance of the interface InterfaceName
-* ```Promise<Type>``` - WebIDL ```Promise<T>```
-* ```Array<Type>``` - WebIDL ```sequence<T>```
-* ```Dictionary``` - unordered set of name-value String-String pairs with no duplicate names
-* ```Type?``` - union of Type and the singleton type with value "null" (WebIDL nullable)
-* ```(Type1 or Type2)``` - union of Type1 and Type2 (WebIDL union)
-* ```any``` - union of all types (WebIDL ```any```)
+* ``Integer`` - WebIDL ``long long``
+* ``Float`` - WebIDL ``double``
+* ``String`` - WebIDL ``USVString``
+* ``Boolean`` - WebIDL ``boolean``
+# ``Object`` - WebIDL ``object``
+* ``InterfaceName`` - an instance of the interface InterfaceName
+* ``Promise<Type>`` - WebIDL ``Promise<T>``
+* ``Array<Type>`` - WebIDL ``sequence<T>``
+* ``Dictionary`` - unordered set of name-value String-String pairs with no duplicate names
+* ``Type?`` - union of Type and the singleton type with value "null" (WebIDL nullable)
+* ``(Type1 or Type2)`` - union of Type1 and Type2 (WebIDL union)
+* ``any`` - union of all types (WebIDL ``any``)
 
 Methods that return nothing (undefined, in JS) use the keyword "void"
 instead of a type.
 
 TODO(ianh): Figure out what should happen with omitted and extraneous parameters
 
 TODO(ianh): Define in detail how this actually works
 
 Mojom IDL
 ---------
 
 The Mojom IDL language is used to describe the APIs exposed over Mojo
 pipes.
 
 Mojom IDL definitions are typically compiled to wrappers in each
 language, which are then used as imports.
 
 TODO(ianh): Define in detail how this actually works
 
 
 Notes
 -----
-```
+```javascript
 global object = {} // with Math, RegExp, etc
 
 magical imports:
   the core mojo fabric JS API   sky:mojo:fabric:core
   the asyncWait/cancelWait mojo fabric JS API (interface to IPC thread)  sky:mojo:fabric:ipc
   the mojom for the shell, proxying through C++ so that the shell pipe isn't exposed  sky:mojo:shell
   the sky API  sky:core
 ```
 
 TODO(ianh): determine if we want to separate the "this" from the
 Document, especially for Modules, so that exposing a module's element
 doesn't expose the module's exports attribute.