docs(README): updates to make d.g.c/web/ happy (#1773)

Adds devsite's comment markers so we can pull sections of the readme into the site.
We lose a few syntax highlighting sections here on github, but everything looks great on developers.google.com!

README.md

@@ -1,4 +1,8 @@
-# Puppeteer [![Linux Build Status](https://img.shields.io/travis/GoogleChrome/puppeteer/master.svg)](https://travis-ci.org/GoogleChrome/puppeteer) [![Windows Build Status](https://img.shields.io/appveyor/ci/aslushnikov/puppeteer/master.svg?logo=appveyor)](https://ci.appveyor.com/project/aslushnikov/puppeteer/branch/master) [![NPM puppeteer package](https://img.shields.io/npm/v/puppeteer.svg)](https://npmjs.org/package/puppeteer)
+# Puppeteer 
+
+<!-- [START badges] -->
+[![Linux Build Status](https://img.shields.io/travis/GoogleChrome/puppeteer/master.svg)](https://travis-ci.org/GoogleChrome/puppeteer) [![Windows Build Status](https://img.shields.io/appveyor/ci/aslushnikov/puppeteer/master.svg?logo=appveyor)](https://ci.appveyor.com/project/aslushnikov/puppeteer/branch/master) [![NPM puppeteer package](https://img.shields.io/npm/v/puppeteer.svg)](https://npmjs.org/package/puppeteer)
+<!-- [END badges] -->
 
 <img src="https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png" height="200" align="right">
 
@@ -6,6 +10,7 @@
 
 > Puppeteer is a Node library which provides a high-level API to control [headless](https://developers.google.com/web/updates/2017/04/headless-chrome) Chrome or Chromium over the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). It can also be configured to use full (non-headless) Chrome or Chromium.
 
+<!-- [START usecases] -->
 ###### What can I do?
 
 Most things that you can do manually in the browser can be done using Puppeteer! Here are a few examples to get you started:
@@ -16,25 +21,27 @@ Most things that you can do manually in the browser can be done using Puppeteer!
 * Automate form submission, UI testing, keyboard input, etc.
 * Create an up-to-date, automated testing environment. Run your tests directly in the latest version of Chrome using the latest JavaScript and browser features.
 * Capture a [timeline trace](https://developers.google.com/web/tools/chrome-devtools/evaluate-performance/reference) of your site to help diagnose performance issues.
+<!-- [END usecases] -->
 
 Give it a spin: https://try-puppeteer.appspot.com/
 
+<!-- [START getstarted] -->
 ## Getting Started
 
 ### Installation
 
-> *Note: Puppeteer requires at least Node v6.4.0, but the examples below use async/await which is only supported in Node v7.6.0 or greater*
-
 To use Puppeteer in your project, run:
 ```
 yarn add puppeteer
 # or "npm i puppeteer"
 ```
 
-> **Note**: When you install Puppeteer, it downloads a recent version of Chromium (~71Mb Mac, ~90Mb Linux, ~110Mb Win) that is guaranteed to work with the API. To skip the download, see [Environment variables](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#environment-variables).
+Note: When you install Puppeteer, it downloads a recent version of Chromium (~71Mb Mac, ~90Mb Linux, ~110Mb Win) that is guaranteed to work with the API. To skip the download, see [Environment variables](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#environment-variables).
 
 ### Usage
 
+Caution: Puppeteer requires at least Node v6.4.0, but the examples below use async/await which is only supported in Node v7.6.0 or greater.
+
 Puppeteer will be familiar to people using other browser testing frameworks. You create an instance
 of `Browser`, open pages, and then manipulate them with [Puppeteer's API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#).
 
@@ -99,6 +106,9 @@ const puppeteer = require('puppeteer');
 
 See [`Page.evaluate()`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pageevaluatepagefunction-args) for more information on `evaluate` and related methods like `evaluateOnNewDocument` and `exposeFunction`.
 
+<!-- [END getstarted] -->
+
+<!-- [START runtimesettings] -->
 ## Default runtime settings
 
 **1. Uses Headless mode**
@@ -128,63 +138,60 @@ of the differences between Chromium and Chrome. [`This article`](https://chromiu
 
 Puppeteer creates its own Chromium user profile which it **cleans up on every run**.
 
+<!-- [END runtimesettings] -->
+
 ## API Documentation
 
 Explore the [API documentation](docs/api.md) and [examples](https://github.com/GoogleChrome/puppeteer/tree/master/examples/) to learn more.
 
+<!-- [START debugging] -->
+
 ## Debugging tips
 
 1. Turn off headless mode - sometimes it's useful to see what the browser is
    displaying. Instead of launching in headless mode, launch a full version of
    the browser using  `headless: false`:
 
-    ```js
+        const browser = await puppeteer.launch({headless: false});
-    const browser = await puppeteer.launch({headless: false});
-    ```
 
 1. Slow it down - the `slowMo` option slows down Puppeteer operations by the
    specified amount of milliseconds. It's another way to help see what's going on.
 
-    ```js
+        const browser = await puppeteer.launch({
-    const browser = await puppeteer.launch({
+          headless: false,
-      headless: false,
+          slowMo: 250 // slow down by 250ms
-      slowMo: 250 // slow down by 250ms
+        });
-    });
-    ```
 
 1. Capture console output - You can listen for the `console` event.
    This is also handy when debugging code in `page.evaluate()`:
 
-    ```js
+        page.on('console', msg => console.log('PAGE LOG:', ...msg.args));
-    page.on('console', msg => console.log('PAGE LOG:', ...msg.args));
+        
-
+        await page.evaluate(() => console.log(`url is ${location.href}`));
-    await page.evaluate(() => console.log(`url is ${location.href}`));
-    ```
 
 
 1. Enable verbose logging - All public API calls and internal protocol traffic
    will be logged via the [`debug`](https://github.com/visionmedia/debug) module under the `puppeteer` namespace.
 
-   ```sh
+        # Basic verbose logging
-   # Basic verbose logging
+        env DEBUG="puppeteer:*" node script.js
-   env DEBUG="puppeteer:*" node script.js
-
-   # Debug output can be enabled/disabled by namespace
-   env DEBUG="puppeteer:*,-puppeteer:protocol" node script.js # everything BUT protocol messages
-   env DEBUG="puppeteer:session" node script.js # protocol session messages (protocol messages to targets)
-   env DEBUG="puppeteer:mouse,puppeteer:keyboard" node script.js # only Mouse and Keyboard API calls
-
-   # Protocol traffic can be rather noisy. This example filters out all Network domain messages
-   env DEBUG="puppeteer:*" env DEBUG_COLORS=true node script.js 2>&1 | grep -v '"Network'
-   ```
 
+        # Debug output can be enabled/disabled by namespace
+        env DEBUG="puppeteer:*,-puppeteer:protocol" node script.js # everything BUT protocol messages
+        env DEBUG="puppeteer:session" node script.js # protocol session messages (protocol messages to targets)
+        env DEBUG="puppeteer:mouse,puppeteer:keyboard" node script.js # only Mouse and Keyboard API calls
 
+        # Protocol traffic can be rather noisy. This example filters out all Network domain messages
+        env DEBUG="puppeteer:*" env DEBUG_COLORS=true node script.js 2>&1 | grep -v '"Network'
 
+<!-- [END debugging] -->
 
 ## Contributing to Puppeteer
 
 Check out [contributing guide](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md) to get an overview of Puppeteer development.
 
+<!-- [START faq] -->
+
 # FAQ
 
 #### Q: Which Chromium version does Puppeteer use?
@@ -229,3 +236,5 @@ You may find that Puppeteer does not behave as expected when controlling pages t
 
 * Puppeteer is bundled with Chromium--not Chrome--and so by default, it inherits all of [Chromium's media-related limitations](https://www.chromium.org/audio-video). This means that Puppeteer does not support licensed formats such as AAC or H.264. (However, it is possible to force Puppeteer to use a separately-installed version Chrome instead of Chromium via the [`executablePath` option to `puppeteer.launch`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions). You should only use this configuration if you need an official release of Chrome that supports these media formats.)
 * Since Puppeteer (in all configurations) controls a desktop version of Chromium/Chrome, features that are only supported by the mobile version of Chrome are not supported. This means that Puppeteer [does not support HTTP Live Streaming (HLS)](https://caniuse.com/#feat=http-live-streaming).
+
+<!-- [END faq] -->