Begin the redesign process, starting with the navbar.

README.md

 This is the server that will be used on `pub.dartlang.org` as the default
 package repository for the Pub package manager.
 
-For license information, please see LICENSE.
+For license information, please see [LICENSE](LICENSE).
 
-### Repository Structure
+## Repository structure
 
-    pub_dartlang.py     The entry point for running the app.
-    app.yaml            App Engine configuration.
-    third_party/        External dependencies, included in the repo so that App
-                        Engine will see them.
-    handlers/           Code that handles HTTP requests.
-    models/             Models for persisting data to the App Engine Datastore.
-    views/              Mustache templates.
+    ┐
+    ├───┬ app/                    The app engine app.
+    │   ├───┬ doc/                Documentation and articles.

[Bob Nystrom, 2013/11/26 19:00:11]

"Source markdown for documentation"

[Andrei Mouravski, 2013/11/29 21:21:21]

Done.

+    │   │   └─...
+    │   ├───┬ handlers/           Core web server code.
+    │   │   └─...
+    │   ├───┬ models/             Models for persisting data to the datastore.
+    │   │   └─...
+    │   ├───┬ static/             Static assets.
+    │   │   ├───┬ img/
+    │   │   │   └─...
+    │   │   ├───┬ js/
+    │   │   │   └─...
+    │   │   ├──── favicon.ico
+    │   │   └──── style.css       Generated stylesheet. Modify /stylesheets/style.scss instead.

[Bob Nystrom, 2013/11/26 19:00:11]

Long line, here and below.

[nweiz, 2013/11/27 00:58:59]

I think long lines in code blocks are reasonable if they look okay in the
compiled output.

[Andrei Mouravski, 2013/11/29 21:21:21]

Ack.

[Andrei Mouravski, 2013/11/29 21:21:21]

Ack.

+    │   │
+    │   ├───┬ views/              Mustache templates.
+    │   │   ├───┬ doc/            Generated HTML. Modify /app/doc/ files instead.

[Bob Nystrom, 2013/11/26 19:00:11]

Ditto.

[Andrei Mouravski, 2013/11/29 21:21:21]

Ack.

+    │   │   │   └─...
+    │   │   └─...
+    │   ├──── app.yaml            AppEngine configuration.
+    │   ├──── appengine_config.py Python module configuration.
+    │   ├──── pub_dartlang.py     Entrypoint for app. Use dev_appserver.py to run.
+    │   └─...
+    │
+    ├───┬ stylesheets/
+    │   └───┬ partials/
+    │       ├──── _syntax.scss    Dart language syntax styles.

[Bob Nystrom, 2013/11/26 19:00:11]

Technically, this applies to other languages too, right? How about just "Syntax
highlighting styles."

[Andrei Mouravski, 2013/11/29 21:21:21]

Done.

+    │       ├──── _variables.scss Variables for theming.
+    │       └ style.scss          Main stylesheet.
+    │
+    ├───┬ test/                   Tests for app functionality.
+    │   └──── ...
+    │
+    ├───┬ third_party/            External dependencies to be include in the app.

[Bob Nystrom, 2013/11/26 19:00:11]

"to be include in" -> "used by"

[Andrei Mouravski, 2013/11/29 21:21:21]

Done.

+    │   └──── ...
+    │
+    ├──── _config.yml             Jekyll configuration.
+    ├──── Procfile                Process to be run with Foreman.
+    ├──── test.py                 Tests the app.

[Bob Nystrom, 2013/11/26 19:00:11]

"Runs all tests."

[Andrei Mouravski, 2013/11/29 21:21:21]

Done.

+    ├──── config.rb               Compass configuration.
+    └──── ...
 
-    test.py             The entry point for testing the app.
-    tests/              Code for testing the app.
+## Running the server locally
 
-### Running the Server Locally
+**tl;dr:** Run the app with ```dev_appserver.py app```.
 
+### Prerequisites

[nweiz, 2013/11/27 00:58:59]

Nit: newline after this.

[Andrei Mouravski, 2013/11/29 21:21:21]

Done.

 The server is written in Python and intended to run on Google App Engine. To run
 it locally, perform the following steps:
 
-  * Install the [App Engine SDK][] for Python.
+  1. Install the [App Engine SDK][] for Python.
   * Make sure the SDK is on your `$PATH`.<sup>1</sup>
   * Install required packages.<sup>2</sup>

[Bob Nystrom, 2013/11/26 19:00:11]

Convert the other bullets to numeric too.

[Andrei Mouravski, 2013/11/29 21:21:21]

Done.

 
         pip install beautifulsoup4 pycrypto webtest
 
+[app engine sdk]: https://developers.google.com/appengine/downloads
+
+### Running server

[nweiz, 2013/11/27 00:58:59]

Nit: "Running the server"

[Andrei Mouravski, 2013/11/29 21:21:21]

Done.

+
   * From the root directory of this repository, run:
 
         dev_appserver.py app
 
-[app engine sdk]: https://developers.google.com/appengine/downloads
-
   * Open your browser to <http://localhost:8080/> to see that it works.
 
-  * To run tests:
+### Running tests
+
+  * To run tests, run:
 
         ./test.py
 
+### Publishing packages locally
+
   * To publish packages to your local test server, visit <http://localhost:8080/admin>
     (sign in as administrator), go to the "Private Key" tab & enter any string 
     into the private key field.
 
 <sup>1</sup> This might have been done already if you allowed the Google App
              Engine launcher to add symbolic links to your `$PATH`.
 
 <sup>2</sup> On installing packages:
+
 * Beautiful Soup & WebTest are only required for running tests.
 * Some Linux distributions come with PyCrypto installed by default.  Make sure
   at least version 2.6 installed.
 * If using Mac and `pip` is not available, install [brew](http://brew.sh) and 
   run `brew install python`.
 
-### Deploying
+## Deploying to the web

[Bob Nystrom, 2013/11/26 19:00:11]

"the web" -> "production"

[Andrei Mouravski, 2013/11/29 21:21:21]

Done.

 
 See the docs on [branches and versions][].
 
 [branches and versions]: https://github.com/dart-lang/pub-dartlang/wiki/Branches-and-Versions
 
-### Modifying the CSS and Documentation
+## Modifying the CSS and documentation
 
-The CSS files are generated from the source [Sass][] files using [Compass][].
-The HTML documentation files are generated from the source [Markdown][] using
-[Jekyll][]. To get ready to make changes, you'll need [Ruby][] and [Python][].
+* The [CSS files](app/static/style.css) are generated from the source [Sass][] files using [Compass][].
+
+* The [HTML documentation files](app/views/doc/) are generated from the source [Markdown][] using
+[Jekyll][].

[Bob Nystrom, 2013/11/26 19:00:11]

Long lines.

[Andrei Mouravski, 2013/11/29 21:21:21]

Done.

+
+To get ready to make changes, you'll need [Ruby][] and [Python][].
 Then:
 
 [ruby]: http://ruby-lang.org
 [python]: http://python.org
 [sass]: http://sass-lang.com
 [compass]: http://compass-style.org
 [markdown]: http://daringfireball.net/projects/markdown/
 [jekyll]: http://jekyllrb.com/
 
  1. Ensure you have bundler installed:
 
         gem install bundler
 
  2. Run this to install the dependencies:
 
         bundle install
 
  3. Run this to install the latest version of Pygments for syntax highlighting:
 
         sudo pip install --upgrade pygments
 
-Note that this is only needed on your development machine to iterate on the CSS
+This is only needed on your development machine to iterate on the CSS
 and documentation. The deployed server just uses the pre-compiled CSS and HTML
 and only requires Python.
 
 Once you have everything installed, to modify the styles and documentation:
 
  1. Run [Foreman][] to automatically regenerate the CSS and HTML files when any
     Sass or Markdown files change:
 
         bundle exec foreman start
 
  1. Edit the `.scss` files under `css/sass` and the `.markdown` files under
     `doc`.
 
 [foreman]: http://ddollar.github.com/foreman/
 
-When you make changes to SCSS or Markdown files, make sure to check in the
-generated CSS or HTML files with them.
+**When you make changes to SCSS or Markdown files, make sure to check in the
+generated CSS or HTML files with them.**