Minor doc improvements and formatting (#142)

Also adds a simple .gitignore

.gitignore

@@ -0,0 +1,8 @@
+*.iml
+.idea
+.vscode
+
+.packages
+.pub
+
+build

README.md

@@ -1,4 +1,5 @@
-Content and infrastructure shared across Dart and Flutter websites. The following repos depend on this one:
+Content and infrastructure shared across Dart and Flutter websites. 
+The following repos depend on this one:
 
 * https://github.com/flutter/website
 * https://github.com/dart-lang/site-www

doc/code-excerpts.md

@@ -176,7 +176,7 @@ To make use of code diffs in a given page, add the following to the page's front
 diff2html: true
 ```
 
-A `<?code-excerpt?>` instruction will procduce a code diff when two files are named using either of the following methods:
+A `<?code-excerpt?>` instruction will produce a code diff when two files are named using either of the following methods:
 
 - Use the `diff-with` argument: `diff-with="path/to/second/file.ext"`.
 - Use the bash brace syntax in the instruction's first unnamed argument:

doc/examples.md

@@ -20,7 +20,8 @@ By doing so we ensure that our code excerpts are valid Dart code.
 
 ## How should I organize my example code?
 
-Organize our example code like any other Dart project, placing source files under the following folders:
+Organize our example code like any other Dart project, 
+placing source files under the following folders:
 
 - `examples/my_example_project/lib`
 - `examples/my_example_project/test`

doc/images.md

@@ -1,6 +1,6 @@
 ## Compressing
 
-Most site have a gulp task that can be used to compress all images, for example:
+Most sites have a gulp task that can be used to compress all images, for example:
 
 ```terminal
 npx gulp compress-images [--path=some/path]
@@ -15,7 +15,9 @@ Ways to center an image, while allowing it to be responsive:
 {:.text-center}
 ```
 
-The previous example must be be preceded and followed by a blank line so that the `text-center` class is applied to the paragraph that will be wrapping the image.
+The previous example must be preceded and followed by a blank line
+so that the `text-center` class is applied to the paragraph
+that will be wrapping the image.
 
 This one adds padding after the image too:
 
@@ -25,7 +27,9 @@ This one adds padding after the image too:
 </div>
 ```
 
-If you know that your image will fit within the page as rendered on your smallest target device, then you can use the following:
+If you know that your image will fit
+within the page as rendered on your smallest target device, 
+then you can use the following:
 
 ```
 {% asset path/file.ext class="d-block mx-auto" width="160px" ... %}

doc/infrastructure.md

@@ -18,10 +18,10 @@ the desired resource file. In some cases, you'll needed to adjust the site
 
 We use the [Jekyll][] site generator, leaving most of its configuration options
 at their [default settings][Default configuration], including use of Kramdown as
-the markdown processor and Rouge as the default syntax highlighter.
+the markdown processor and [Rouge][] as the default syntax highlighter.
 
-To see a list of the languages you can use with <code>```</code>, go to
-https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers.
+To see a list of the languages you can use with <code>```</code>, see
+Rouge's [list of supported languages and lexer][languages].
 The most common languages we use are `dart`, <code>console</code> (or its equivalent,
 <code>terminal</code>), <code>nocode</code>, and <code>yaml</code>.
 
@@ -95,6 +95,8 @@ JavaScript can be similarly imported:
 [Jekyll]: https://jekyllrb.com
 [jekyll-assets]: https://github.com/envygeeks/jekyll-assets
 [jekyll-toc]: https://github.com/toshimaru/jekyll-toc
+[languages]: https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers
+[Rouge]: https://github.com/rouge-ruby/rouge
 [src/_assets]: https://github.com/dart-lang/site-shared/tree/master/src/_assets
 [src/_plugins]: https://github.com/dart-lang/site-shared/tree/master/src/_plugins
 [src/_assets/css/_code_pre.scss]: https://github.com/dart-lang/site-shared/tree/master/src/_assets/css/_code_pre.scss

doc/mobile-friendly-pages.md

@@ -1,7 +1,11 @@
 Ensuring that a page is mobile friendly can take a little more effort than ensuring that images are responsive. Here are some points to consider:
 
-- Responsive **images**. A lot could be written here, including serving size-appropriate images depending on the client). When no other measures are taken, at a minimum, ensure that images are assigned the `mw-100` class.
-- **Videos** are a bit trickier to deal with. This is what we've used so far on flutter/website:
+- Responsive **images**. A lot could be written here, 
+  including serving size-appropriate images depending on the client. 
+  When no other measures are taken, at a minimum, 
+  ensure that images are assigned the `mw-100` class.
+- **Videos** are a bit trickier to deal with. 
+  This is what we've used so far on flutter/website:
 
   ```html
   <div class="embedded-video-wrapper">
@@ -11,14 +15,26 @@ Ensuring that a page is mobile friendly can take a little more effort than ensur
     </iframe>
   </div>
   ```
-- On narrow mobile displays, long words or strings that don't **word-break** (like program identifiers), can cause horizontal page overflow. In these cases consider the following options:
+- On narrow mobile displays, 
+  long words or strings that don't **word-break** (like program identifiers), 
+  can cause horizontal page overflow. In these cases consider the following options:
 
-  - Insert `&shy;` in your text, where appropriate, to allow word-breaks and have a hyphen displayed at the break
+  - Insert `&shy;` in your text, where appropriate, 
+    to allow word-breaks and have a hyphen displayed at the break
   - Insert `<wbr>` to indicate a possible word-break point (without having a hyphen displayed)
   - Use CSS: `word-break: break-word;`
 
-  Using the CSS style is simplest, but since you aren't choosing the word-break points, the result isn't
-  always aesthetically pleasing, but it has the advantage of allowing you to not alter the text. Inserting
-  `&shy;` or `<wbr>` gives nicer results but can throw off text-search/replace.
+  Using the CSS style is simplest, 
+  but since you aren't choosing the word-break points, 
+  the result isn't always aesthetically pleasing, 
+  but it has the advantage of allowing you to not alter the text. 
+  Inserting `&shy;` or `<wbr>` gives nicer results 
+  but can throw off text-search/replace.
 
-When checking whether a page is mobile-friendly, Chrome's device emulator is great for the bulk of the work but I've found it necessary to validate on a real device (or an official emulator -- like the iOS simulator). There is a tradeoff to be had: Chrome is easier to use (e.g., for page navigation and search), but official emulators/real devices are the final arbiters.
+When checking whether a page is mobile-friendly, 
+Chrome's device emulator is great for the bulk of the work 
+but we've found it necessary to validate on a real device 
+(or an official emulator -- like the iOS simulator). 
+There is a tradeoff to be had: 
+Chrome is easier to use (e.g., for page navigation and search),
+but official emulators/real devices are the final arbiters.

doc/writing-for-dart-and-flutter-websites.md

@@ -1,4 +1,5 @@
-This page has information and links that might come in handy as you develop content for Dart and Flutter websites.
+This page has information and links that might come in handy
+as you develop content for Dart and Flutter websites.
 
 Contents of this page:
 * [Semantic line breaks (<=80 chars)](#semantic-line-breaks)
@@ -80,15 +81,17 @@ Follow these rules when creating links:
 
 * Use jekyll variables if they exist; define new ones if necessary.
   You can find sitewide variables in `/_config.yml`.
-  For example, the [site-www `_config.yml` file](https://github.com/dart-lang/site-www/blob/master/_config.yml) defines variables like
-  `webdev`, `flutter`, and `dart_api`, so site-www has URLs like
+  For example, the [site-www `_config.yml` file][] defines variables like
+  `dartpad`, `flutter`, and `dart_api`, so site-www has URLs like
   the following:
-  * `{{site.webdev}}`
-  * `{{site.webdev}}/tools/dart2js`
+  * `{{site.dartpad}}`
+  * `{{site.flutter}}`
   * `{{site.flutter}}/debugging/#the-dart-analyzer`
   * `{{site.dart_api}}/dev`
   * `{{site.dart_api}}/{{site.data.pkg-vers.SDK.channel}}/dart-html`
 
+  [site-www `_config.yml` file]: https://github.com/dart-lang/site-www/blob/master/_config.yml
+
 * Simplify API URLs as much as possible. In particular,
   **do not embed the version** (unless you really want that).
   Consider omitting URL pieces that the server doesn't require.
@@ -104,7 +107,7 @@ Also see: https://github.com/dart-lang/site-www/wiki/Referring-to-API-docs
 
 ## Images
 
-Use zopfli to compress PNGs.
+Use [zopfli](https://github.com/google/zopfli) to compress PNGs.
 
 `brew install zopfli`
 
@@ -126,7 +129,10 @@ Keep code valid and foolproof. People love to copy-paste code.
 
 ## Markdown and HTML
 
-* You can use ordinary Markdown (or HTML, if necessary) on the Dart and Flutter sites. To test your markdown, you can either build the site or paste the code into Markdown previewer such as https://dart-lang.github.io/markdown/.
+* You can use ordinary Markdown (or HTML, if necessary) on the Dart and Flutter sites. 
+  To test your markdown, 
+  you can either build the site or paste the code into a Markdown previewer
+  such as https://dart-lang.github.io/markdown/.
 
 * If you're using HTML and want italics, use `<em>`. <br>
   The i-tag is used for icon fonts, such as font-awesome.
@@ -160,8 +166,8 @@ js:
 ---
 ```
 
-The **title:** tag is used for the title displayed on the page and (if no **short-title** tag is present)
-in the tab.
+The **title:** tag is used for the title displayed on the page 
+and (if no **short-title** tag is present) in the tab.
 
 The **description:** tag replaces the default sharing text
 (what you see on Twitter, Facebook, G+).