Port TRPL to mdbook

1. move everything under a src directory
2. add README.md to the SUMMARY.md

71 files changed, 146 insertions, 146 deletions

diff --git a/src/doc/book/SUMMARY.md b/src/doc/book/SUMMARY.md
deleted file mode 100644
index babbafa078f..00000000000
--- a/src/doc/book/SUMMARY.md
+++ /dev/null
@@ -1,70 +0,0 @@
-# Summary
-
-* [Getting Started](getting-started.md)
-* [Tutorial: Guessing Game](guessing-game.md)
-* [Syntax and Semantics](syntax-and-semantics.md)
-    * [Variable Bindings](variable-bindings.md)
-    * [Functions](functions.md)
-    * [Primitive Types](primitive-types.md)
-    * [Comments](comments.md)
-    * [if](if.md)
-    * [Loops](loops.md)
-    * [Vectors](vectors.md)
-    * [Ownership](ownership.md)
-    * [References and Borrowing](references-and-borrowing.md)
-    * [Lifetimes](lifetimes.md)
-    * [Mutability](mutability.md)
-    * [Structs](structs.md)
-    * [Enums](enums.md)
-    * [Match](match.md)
-    * [Patterns](patterns.md)
-    * [Method Syntax](method-syntax.md)
-    * [Strings](strings.md)
-    * [Generics](generics.md)
-    * [Traits](traits.md)
-    * [Drop](drop.md)
-    * [if let](if-let.md)
-    * [Trait Objects](trait-objects.md)
-    * [Closures](closures.md)
-    * [Universal Function Call Syntax](ufcs.md)
-    * [Crates and Modules](crates-and-modules.md)
-    * [`const` and `static`](const-and-static.md)
-    * [Attributes](attributes.md)
-    * [`type` aliases](type-aliases.md)
-    * [Casting between types](casting-between-types.md)
-    * [Associated Types](associated-types.md)
-    * [Unsized Types](unsized-types.md)
-    * [Operators and Overloading](operators-and-overloading.md)
-    * [Deref coercions](deref-coercions.md)
-    * [Macros](macros.md)
-    * [Raw Pointers](raw-pointers.md)
-    * [`unsafe`](unsafe.md)
-* [Effective Rust](effective-rust.md)
-    * [The Stack and the Heap](the-stack-and-the-heap.md)
-    * [Testing](testing.md)
-    * [Conditional Compilation](conditional-compilation.md)
-    * [Documentation](documentation.md)
-    * [Iterators](iterators.md)
-    * [Concurrency](concurrency.md)
-    * [Error Handling](error-handling.md)
-    * [Choosing your Guarantees](choosing-your-guarantees.md)
-    * [FFI](ffi.md)
-    * [Borrow and AsRef](borrow-and-asref.md)
-    * [Release Channels](release-channels.md)
-    * [Using Rust without the standard library](using-rust-without-the-standard-library.md)
-    * [Procedural Macros (and custom derive)](procedural-macros.md)
-* [Nightly Rust](nightly-rust.md)
-    * [Compiler Plugins](compiler-plugins.md)
-    * [Inline Assembly](inline-assembly.md)
-    * [No stdlib](no-stdlib.md)
-    * [Intrinsics](intrinsics.md)
-    * [Lang items](lang-items.md)
-    * [Advanced linking](advanced-linking.md)
-    * [Benchmark Tests](benchmark-tests.md)
-    * [Box Syntax and Patterns](box-syntax-and-patterns.md)
-    * [Slice Patterns](slice-patterns.md)
-    * [Associated Constants](associated-constants.md)
-    * [Custom Allocators](custom-allocators.md)
-* [Glossary](glossary.md)
-* [Syntax Index](syntax-index.md)
-* [Bibliography](bibliography.md)
diff --git a/src/doc/book/README.md b/src/doc/book/src/README.md
index 9f9b6a9b043..9162642b1cc 100644
--- a/src/doc/book/README.md
+++ b/src/doc/book/src/README.md
@@ -1,4 +1,4 @@
-% The Rust Programming Language
+# The Rust Programming Language
 
 Welcome! This book will teach you about the [Rust Programming Language][rust].
 Rust is a systems programming language focused on three goals: safety, speed,
diff --git a/src/doc/book/src/SUMMARY.md b/src/doc/book/src/SUMMARY.md
index 7390c82896e..74b9b7fa5b2 100644
--- a/src/doc/book/src/SUMMARY.md
+++ b/src/doc/book/src/SUMMARY.md
@@ -1,3 +1,72 @@
 # Summary
 
-- [Chapter 1](./chapter_1.md)
+[Introduction](README.md)
+
+* [Getting Started](getting-started.md)
+* [Tutorial: Guessing Game](guessing-game.md)
+* [Syntax and Semantics](syntax-and-semantics.md)
+    * [Variable Bindings](variable-bindings.md)
+    * [Functions](functions.md)
+    * [Primitive Types](primitive-types.md)
+    * [Comments](comments.md)
+    * [if](if.md)
+    * [Loops](loops.md)
+    * [Vectors](vectors.md)
+    * [Ownership](ownership.md)
+    * [References and Borrowing](references-and-borrowing.md)
+    * [Lifetimes](lifetimes.md)
+    * [Mutability](mutability.md)
+    * [Structs](structs.md)
+    * [Enums](enums.md)
+    * [Match](match.md)
+    * [Patterns](patterns.md)
+    * [Method Syntax](method-syntax.md)
+    * [Strings](strings.md)
+    * [Generics](generics.md)
+    * [Traits](traits.md)
+    * [Drop](drop.md)
+    * [if let](if-let.md)
+    * [Trait Objects](trait-objects.md)
+    * [Closures](closures.md)
+    * [Universal Function Call Syntax](ufcs.md)
+    * [Crates and Modules](crates-and-modules.md)
+    * [`const` and `static`](const-and-static.md)
+    * [Attributes](attributes.md)
+    * [`type` aliases](type-aliases.md)
+    * [Casting between types](casting-between-types.md)
+    * [Associated Types](associated-types.md)
+    * [Unsized Types](unsized-types.md)
+    * [Operators and Overloading](operators-and-overloading.md)
+    * [Deref coercions](deref-coercions.md)
+    * [Macros](macros.md)
+    * [Raw Pointers](raw-pointers.md)
+    * [`unsafe`](unsafe.md)
+* [Effective Rust](effective-rust.md)
+    * [The Stack and the Heap](the-stack-and-the-heap.md)
+    * [Testing](testing.md)
+    * [Conditional Compilation](conditional-compilation.md)
+    * [Documentation](documentation.md)
+    * [Iterators](iterators.md)
+    * [Concurrency](concurrency.md)
+    * [Error Handling](error-handling.md)
+    * [Choosing your Guarantees](choosing-your-guarantees.md)
+    * [FFI](ffi.md)
+    * [Borrow and AsRef](borrow-and-asref.md)
+    * [Release Channels](release-channels.md)
+    * [Using Rust without the standard library](using-rust-without-the-standard-library.md)
+    * [Procedural Macros (and custom derive)](procedural-macros.md)
+* [Nightly Rust](nightly-rust.md)
+    * [Compiler Plugins](compiler-plugins.md)
+    * [Inline Assembly](inline-assembly.md)
+    * [No stdlib](no-stdlib.md)
+    * [Intrinsics](intrinsics.md)
+    * [Lang items](lang-items.md)
+    * [Advanced linking](advanced-linking.md)
+    * [Benchmark Tests](benchmark-tests.md)
+    * [Box Syntax and Patterns](box-syntax-and-patterns.md)
+    * [Slice Patterns](slice-patterns.md)
+    * [Associated Constants](associated-constants.md)
+    * [Custom Allocators](custom-allocators.md)
+* [Glossary](glossary.md)
+* [Syntax Index](syntax-index.md)
+* [Bibliography](bibliography.md)
diff --git a/src/doc/book/advanced-linking.md b/src/doc/book/src/advanced-linking.md
index ddaebaf98d9..a882d6d2ebe 100644
--- a/src/doc/book/advanced-linking.md
+++ b/src/doc/book/src/advanced-linking.md
@@ -1,4 +1,4 @@
-% Advanced Linking
+# Advanced Linking
 
 The common cases of linking with Rust have been covered earlier in this book,
 but supporting the range of linking possibilities made available by other
diff --git a/src/doc/book/associated-constants.md b/src/doc/book/src/associated-constants.md
index 81f7ea104e4..61bad3d3948 100644
--- a/src/doc/book/associated-constants.md
+++ b/src/doc/book/src/associated-constants.md
@@ -1,4 +1,4 @@
-% Associated Constants
+# Associated Constants
 
 With the `associated_consts` feature, you can define constants like this:
 
diff --git a/src/doc/book/associated-types.md b/src/doc/book/src/associated-types.md
index f416e600415..4db2b9e5eec 100644
--- a/src/doc/book/associated-types.md
+++ b/src/doc/book/src/associated-types.md
@@ -1,4 +1,4 @@
-% Associated Types
+# Associated Types
 
 Associated types are a powerful part of Rust’s type system. They’re related to
 the idea of a ‘type family’, in other words, grouping multiple types together. That
diff --git a/src/doc/book/attributes.md b/src/doc/book/src/attributes.md
index 63496471b5a..9e3cdb7ec09 100644
--- a/src/doc/book/attributes.md
+++ b/src/doc/book/src/attributes.md
@@ -1,4 +1,4 @@
-% Attributes
+# Attributes
 
 Declarations can be annotated with ‘attributes’ in Rust. They look like this:
 
diff --git a/src/doc/book/benchmark-tests.md b/src/doc/book/src/benchmark-tests.md
index e054736eb30..a6ae2b3049a 100644
--- a/src/doc/book/benchmark-tests.md
+++ b/src/doc/book/src/benchmark-tests.md
@@ -1,4 +1,4 @@
-% Benchmark tests
+# Benchmark tests
 
 Rust supports benchmark tests, which can test the performance of your
 code. Let's make our `src/lib.rs` look like this (comments elided):
diff --git a/src/doc/book/bibliography.md b/src/doc/book/src/bibliography.md
index 6f6f51d1f60..07b2aa94a77 100644
--- a/src/doc/book/bibliography.md
+++ b/src/doc/book/src/bibliography.md
@@ -1,4 +1,4 @@
-% Bibliography
+# Bibliography
 
 This is a reading list of material relevant to Rust. It includes prior
 research that has - at one time or another - influenced the design of
diff --git a/src/doc/book/borrow-and-asref.md b/src/doc/book/src/borrow-and-asref.md
index c30b2e68665..a6e396571c6 100644
--- a/src/doc/book/borrow-and-asref.md
+++ b/src/doc/book/src/borrow-and-asref.md
@@ -1,4 +1,4 @@
-% Borrow and AsRef
+# Borrow and AsRef
 
 The [`Borrow`][borrow] and [`AsRef`][asref] traits are very similar, but
 different. Here’s a quick refresher on what these two traits mean.
diff --git a/src/doc/book/box-syntax-and-patterns.md b/src/doc/book/src/box-syntax-and-patterns.md
index cbf65dfa9ba..f03e881f474 100644
--- a/src/doc/book/box-syntax-and-patterns.md
+++ b/src/doc/book/src/box-syntax-and-patterns.md
@@ -1,4 +1,4 @@
-%  Box Syntax and Patterns
+#  Box Syntax and Patterns
 
 Currently the only stable way to create a `Box` is via the `Box::new` method.
 Also it is not possible in stable Rust to destructure a `Box` in a match
diff --git a/src/doc/book/casting-between-types.md b/src/doc/book/src/casting-between-types.md
index a8f8224c58b..853fb1ec254 100644
--- a/src/doc/book/casting-between-types.md
+++ b/src/doc/book/src/casting-between-types.md
@@ -1,4 +1,4 @@
-% Casting Between Types
+# Casting Between Types
 
 Rust, with its focus on safety, provides two different ways of casting
 different types between each other. The first, `as`, is for safe casts.
@@ -19,7 +19,7 @@ The most common case of coercion is removing mutability from a reference:
 * `&mut T` to `&T`
 
 An analogous conversion is to remove mutability from a
-[raw pointer](raw-pointers.md):
+[raw pointer](raw-pointers.html):
 
 * `*mut T` to `*const T`
 
@@ -29,7 +29,7 @@ References can also be coerced to raw pointers:
 
 * `&mut T` to `*mut T`
 
-Custom coercions may be defined using [`Deref`](deref-coercions.md).
+Custom coercions may be defined using [`Deref`](deref-coercions.html).
 
 Coercion is transitive.
 
@@ -101,7 +101,7 @@ The semantics of numeric casts are:
 
 ## Pointer casts
 
-Perhaps surprisingly, it is safe to cast [raw pointers](raw-pointers.md) to and
+Perhaps surprisingly, it is safe to cast [raw pointers](raw-pointers.html) to and
 from integers, and to cast between pointers to different types subject to
 some constraints. It is only unsafe to dereference the pointer:
 
diff --git a/src/doc/book/choosing-your-guarantees.md b/src/doc/book/src/choosing-your-guarantees.md
index 17741cac10b..89dd09e6704 100644
--- a/src/doc/book/choosing-your-guarantees.md
+++ b/src/doc/book/src/choosing-your-guarantees.md
@@ -1,4 +1,4 @@
-% Choosing your Guarantees
+# Choosing your Guarantees
 
 One important feature of Rust is that it lets us control the costs and guarantees
 of a program.
diff --git a/src/doc/book/closures.md b/src/doc/book/src/closures.md
index 115fe1f7662..5426ed0ff4c 100644
--- a/src/doc/book/closures.md
+++ b/src/doc/book/src/closures.md
@@ -1,4 +1,4 @@
-% Closures
+# Closures
 
 Sometimes it is useful to wrap up a function and _free variables_ for better
 clarity and reuse. The free variables that can be used come from the
diff --git a/src/doc/book/comments.md b/src/doc/book/src/comments.md
index 8fa397cd9a6..0e68ab218e8 100644
--- a/src/doc/book/comments.md
+++ b/src/doc/book/src/comments.md
@@ -1,4 +1,4 @@
-% Comments
+# Comments
 
 Now that we have some functions, it’s a good idea to learn about comments.
 Comments are notes that you leave to other programmers to help explain things
diff --git a/src/doc/book/compiler-plugins.md b/src/doc/book/src/compiler-plugins.md
index ff29358df94..1b7ce678982 100644
--- a/src/doc/book/compiler-plugins.md
+++ b/src/doc/book/src/compiler-plugins.md
@@ -1,6 +1,6 @@
-% Compiler Plugins
+# Compiler Plugins
 
-# Introduction
+## Introduction
 
 `rustc` can load compiler plugins, which are user-provided libraries that
 extend the compiler's behavior with new syntax extensions, lint checks, etc.
diff --git a/src/doc/book/concurrency.md b/src/doc/book/src/concurrency.md
index 67d89d5484c..a64178c26f2 100644
--- a/src/doc/book/concurrency.md
+++ b/src/doc/book/src/concurrency.md
@@ -1,4 +1,4 @@
-% Concurrency
+# Concurrency
 
 Concurrency and parallelism are incredibly important topics in computer
 science, and are also a hot topic in industry today. Computers are gaining more
diff --git a/src/doc/book/conditional-compilation.md b/src/doc/book/src/conditional-compilation.md
index 78ab3c18e45..938c1c51326 100644
--- a/src/doc/book/conditional-compilation.md
+++ b/src/doc/book/src/conditional-compilation.md
@@ -1,4 +1,4 @@
-% Conditional Compilation
+# Conditional Compilation
 
 Rust has a special attribute, `#[cfg]`, which allows you to compile code
 based on a flag passed to the compiler. It has two forms:
diff --git a/src/doc/book/const-and-static.md b/src/doc/book/src/const-and-static.md
index e8f17a41cbe..25b4bd94799 100644
--- a/src/doc/book/const-and-static.md
+++ b/src/doc/book/src/const-and-static.md
@@ -1,4 +1,4 @@
-% const and static
+# const and static
 
 Rust has a way of defining constants with the `const` keyword:
 
diff --git a/src/doc/book/crates-and-modules.md b/src/doc/book/src/crates-and-modules.md
index 0e336635235..84f5fac044e 100644
--- a/src/doc/book/crates-and-modules.md
+++ b/src/doc/book/src/crates-and-modules.md
@@ -1,4 +1,4 @@
-% Crates and Modules
+# Crates and Modules
 
 When a project starts getting large, it’s considered good software
 engineering practice to split it up into a bunch of smaller pieces, and then
diff --git a/src/doc/book/custom-allocators.md b/src/doc/book/src/custom-allocators.md
index 1996305f09e..154b5f0f4e2 100644
--- a/src/doc/book/custom-allocators.md
+++ b/src/doc/book/src/custom-allocators.md
@@ -1,4 +1,4 @@
-% Custom Allocators
+# Custom Allocators
 
 Allocating memory isn't always the easiest thing to do, and while Rust generally
 takes care of this by default it often becomes necessary to customize how
diff --git a/src/doc/book/deref-coercions.md b/src/doc/book/src/deref-coercions.md
index 864cd282d93..8552a7c8b34 100644
--- a/src/doc/book/deref-coercions.md
+++ b/src/doc/book/src/deref-coercions.md
@@ -1,4 +1,4 @@
-% `Deref` coercions
+# `Deref` coercions
 
 The standard library provides a special trait, [`Deref`][deref]. It’s normally
 used to overload `*`, the dereference operator:
diff --git a/src/doc/book/documentation.md b/src/doc/book/src/documentation.md
index d2402ddb2e9..69d49e2f96a 100644
--- a/src/doc/book/documentation.md
+++ b/src/doc/book/src/documentation.md
@@ -1,4 +1,4 @@
-% Documentation
+# Documentation
 
 Documentation is an important part of any software project, and it's
 first-class in Rust. Let's talk about the tooling Rust gives you to
diff --git a/src/doc/book/drop.md b/src/doc/book/src/drop.md
index 0b7ddcfbe88..53c507eba3f 100644
--- a/src/doc/book/drop.md
+++ b/src/doc/book/src/drop.md
@@ -1,4 +1,4 @@
-% Drop
+# Drop
 
 Now that we’ve discussed traits, let’s talk about a particular trait provided
 by the Rust standard library, [`Drop`][drop]. The `Drop` trait provides a way
diff --git a/src/doc/book/effective-rust.md b/src/doc/book/src/effective-rust.md
index 65873c80e55..ce2dfe4eae2 100644
--- a/src/doc/book/effective-rust.md
+++ b/src/doc/book/src/effective-rust.md
@@ -1,4 +1,4 @@
-% Effective Rust
+# Effective Rust
 
 So you’ve learned how to write some Rust code. But there’s a difference between
 writing *any* Rust code and writing *good* Rust code.
diff --git a/src/doc/book/enums.md b/src/doc/book/src/enums.md
index 790d6ff8546..9cf5e6bfa21 100644
--- a/src/doc/book/enums.md
+++ b/src/doc/book/src/enums.md
@@ -1,4 +1,4 @@
-% Enums
+# Enums
 
 An `enum` in Rust is a type that represents data that is one of
 several possible variants. Each variant in the `enum` can optionally
diff --git a/src/doc/book/error-handling.md b/src/doc/book/src/error-handling.md
index 0d9f49d66cb..c823c32a135 100644
--- a/src/doc/book/error-handling.md
+++ b/src/doc/book/src/error-handling.md
@@ -1,4 +1,4 @@
-% Error Handling
+# Error Handling
 
 Like most programming languages, Rust encourages the programmer to handle
 errors in a particular way. Generally speaking, error handling is divided into
diff --git a/src/doc/book/ffi.md b/src/doc/book/src/ffi.md
index 8d29f11aa05..cccefd8dfe7 100644
--- a/src/doc/book/ffi.md
+++ b/src/doc/book/src/ffi.md
@@ -1,4 +1,4 @@
-% Foreign Function Interface
+# Foreign Function Interface
 
 # Introduction
 
diff --git a/src/doc/book/functions.md b/src/doc/book/src/functions.md
index b453936fe00..eff77a54d83 100644
--- a/src/doc/book/functions.md
+++ b/src/doc/book/src/functions.md
@@ -1,4 +1,4 @@
-% Functions
+# Functions
 
 Every Rust program has at least one function, the `main` function:
 
diff --git a/src/doc/book/generics.md b/src/doc/book/src/generics.md
index eafad6a05fc..56655ac41d0 100644
--- a/src/doc/book/generics.md
+++ b/src/doc/book/src/generics.md
@@ -1,4 +1,4 @@
-% Generics
+# Generics
 
 Sometimes, when writing a function or data type, we may want it to work for
 multiple types of arguments. In Rust, we can do this with generics.
diff --git a/src/doc/book/getting-started.md b/src/doc/book/src/getting-started.md
index 5aae693ad6b..6208b1f4c12 100644
--- a/src/doc/book/getting-started.md
+++ b/src/doc/book/src/getting-started.md
@@ -1,4 +1,4 @@
-% Getting Started
+# Getting Started
 
 This first chapter of the book will get us going with Rust and its tooling.
 First, we’ll install Rust. Then, the classic ‘Hello World’ program. Finally,
diff --git a/src/doc/book/glossary.md b/src/doc/book/src/glossary.md
index 8aa7fdff948..b17b89633f3 100644
--- a/src/doc/book/glossary.md
+++ b/src/doc/book/src/glossary.md
@@ -1,4 +1,4 @@
-% Glossary
+# Glossary
 
 Not every Rustacean has a background in systems programming, nor in computer
 science, so we've added explanations of terms that might be unfamiliar.
diff --git a/src/doc/book/guessing-game.md b/src/doc/book/src/guessing-game.md
index c854b7c373d..7368d2184e5 100644
--- a/src/doc/book/guessing-game.md
+++ b/src/doc/book/src/guessing-game.md
@@ -1,4 +1,4 @@
-% Guessing Game
+# Guessing Game
 
 Let’s learn some Rust! For our first project, we’ll implement a classic
 beginner programming problem: the guessing game. Here’s how it works: Our
diff --git a/src/doc/book/if-let.md b/src/doc/book/src/if-let.md
index e76149ad270..17bf1369000 100644
--- a/src/doc/book/if-let.md
+++ b/src/doc/book/src/if-let.md
@@ -1,4 +1,4 @@
-% if let
+# if let
 
 `if let` permits [patterns][pattern] matching within the condition of an [if][if] statement.
 This allows us to reduce the overhead of certain kinds of [pattern][patterns] matches
diff --git a/src/doc/book/if.md b/src/doc/book/src/if.md
index 52d0dd888ef..d74503757bc 100644
--- a/src/doc/book/if.md
+++ b/src/doc/book/src/if.md
@@ -1,4 +1,4 @@
-% if
+# if
 
 Rust’s take on `if` is not particularly complex, but it’s much more like the
 `if` you’ll find in a dynamically typed language than in a more traditional
diff --git a/src/doc/book/inline-assembly.md b/src/doc/book/src/inline-assembly.md
index e531d5d7fc0..4262289acbf 100644
--- a/src/doc/book/inline-assembly.md
+++ b/src/doc/book/src/inline-assembly.md
@@ -1,4 +1,4 @@
-% Inline Assembly
+# Inline Assembly
 
 For extremely low-level manipulations and performance reasons, one
 might wish to control the CPU directly. Rust supports using inline
diff --git a/src/doc/book/intrinsics.md b/src/doc/book/src/intrinsics.md
index d1d836fe188..e1edce3e80f 100644
--- a/src/doc/book/intrinsics.md
+++ b/src/doc/book/src/intrinsics.md
@@ -1,4 +1,4 @@
-% Intrinsics
+# Intrinsics
 
 > **Note**: intrinsics will forever have an unstable interface, it is
 > recommended to use the stable interfaces of libcore rather than intrinsics
diff --git a/src/doc/book/iterators.md b/src/doc/book/src/iterators.md
index c174d2d6bac..1437c0f0b54 100644
--- a/src/doc/book/iterators.md
+++ b/src/doc/book/src/iterators.md
@@ -1,4 +1,4 @@
-% Iterators
+# Iterators
 
 Let's talk about loops.
 
diff --git a/src/doc/book/lang-items.md b/src/doc/book/src/lang-items.md
index 0d6a142ca4f..9bd64d38179 100644
--- a/src/doc/book/lang-items.md
+++ b/src/doc/book/src/lang-items.md
@@ -1,4 +1,4 @@
-% Lang items
+# Lang items
 
 > **Note**: lang items are often provided by crates in the Rust distribution,
 > and lang items themselves have an unstable interface. It is recommended to use
diff --git a/src/doc/book/lifetimes.md b/src/doc/book/src/lifetimes.md
index 2bf2beb8b74..8bca13c28f0 100644
--- a/src/doc/book/lifetimes.md
+++ b/src/doc/book/src/lifetimes.md
@@ -1,4 +1,4 @@
-% Lifetimes
+# Lifetimes
 
 This is the last of three sections presenting Rust’s ownership system. This is one of
 Rust’s most distinct and compelling features, with which Rust developers should
diff --git a/src/doc/book/loops.md b/src/doc/book/src/loops.md
index 688e8c55265..ec4acfa3112 100644
--- a/src/doc/book/loops.md
+++ b/src/doc/book/src/loops.md
@@ -1,4 +1,4 @@
-% Loops
+# Loops
 
 Rust currently provides three approaches to performing some kind of iterative activity. They are: `loop`, `while` and `for`. Each approach has its own set of uses.
 
diff --git a/src/doc/book/macros.md b/src/doc/book/src/macros.md
index 7f52b33948e..22d53779bb9 100644
--- a/src/doc/book/macros.md
+++ b/src/doc/book/src/macros.md
@@ -1,4 +1,4 @@
-% Macros
+# Macros
 
 By now you’ve learned about many of the tools Rust provides for abstracting and
 reusing code. These units of code reuse have a rich semantic structure. For
diff --git a/src/doc/book/match.md b/src/doc/book/src/match.md
index 52d3c6ae926..b1e26a9c9d3 100644
--- a/src/doc/book/match.md
+++ b/src/doc/book/src/match.md
@@ -1,4 +1,4 @@
-% Match
+# Match
 
 Often, a simple [`if`][if]/`else` isn’t enough, because you have more than two
 possible options. Also, conditions can get quite complex. Rust
diff --git a/src/doc/book/method-syntax.md b/src/doc/book/src/method-syntax.md
index b2532663339..0404a5c992b 100644
--- a/src/doc/book/method-syntax.md
+++ b/src/doc/book/src/method-syntax.md
@@ -1,4 +1,4 @@
-% Method Syntax
+# Method Syntax
 
 Functions are great, but if you want to call a bunch of them on some data, it
 can be awkward. Consider this code:
diff --git a/src/doc/book/mutability.md b/src/doc/book/src/mutability.md
index 18017cc4a5e..fa7a259392a 100644
--- a/src/doc/book/mutability.md
+++ b/src/doc/book/src/mutability.md
@@ -1,4 +1,4 @@
-% Mutability
+# Mutability
 
 Mutability, the ability to change something, works a bit differently in Rust
 than in other languages. The first aspect of mutability is its non-default
diff --git a/src/doc/book/nightly-rust.md b/src/doc/book/src/nightly-rust.md
index f55bb078420..5dfaa9e0fa8 100644
--- a/src/doc/book/nightly-rust.md
+++ b/src/doc/book/src/nightly-rust.md
@@ -1,8 +1,8 @@
-% Nightly Rust
+# Nightly Rust
 
 Rust provides three distribution channels for Rust: nightly, beta, and stable.
 Unstable features are only available on nightly Rust. For more details on this
-process, see ‘[Stability as a deliverable][stability]’.
+process, see [Stability as a deliverable][stability].
 
 [stability]: http://blog.rust-lang.org/2014/10/30/Stability.html
 
@@ -91,9 +91,10 @@ If not, there are a number of places where you can get help. The easiest is
 [the #rust IRC channel on irc.mozilla.org][irc], which you can access through
 [Mibbit][mibbit]. Click that link, and you'll be chatting with other Rustaceans
 (a silly nickname we call ourselves), and we can help you out. Other great
-resources include [the user’s forum][users], and [Stack Overflow][stackoverflow].
+resources include [the users forum][users], and [Stack Overflow][stackoverflow].
 
 [irc]: irc://irc.mozilla.org/#rust
 [mibbit]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust
 [users]: https://users.rust-lang.org/
 [stackoverflow]: http://stackoverflow.com/questions/tagged/rust
+
diff --git a/src/doc/book/no-stdlib.md b/src/doc/book/src/no-stdlib.md
index 79f0593be17..dcb0fbc8005 100644
--- a/src/doc/book/no-stdlib.md
+++ b/src/doc/book/src/no-stdlib.md
@@ -1,4 +1,4 @@
-% No stdlib
+# No stdlib
 
 Rust’s standard library provides a lot of useful functionality, but assumes
 support for various features of its host system: threads, networking, heap
diff --git a/src/doc/book/operators-and-overloading.md b/src/doc/book/src/operators-and-overloading.md
index 78ff871046e..a69cd6adb3b 100644
--- a/src/doc/book/operators-and-overloading.md
+++ b/src/doc/book/src/operators-and-overloading.md
@@ -1,4 +1,4 @@
-% Operators and Overloading
+# Operators and Overloading
 
 Rust allows for a limited form of operator overloading. There are certain
 operators that are able to be overloaded. To support a particular operator
diff --git a/src/doc/book/ownership.md b/src/doc/book/src/ownership.md
index 11eda399adc..21ebd6333f7 100644
--- a/src/doc/book/ownership.md
+++ b/src/doc/book/src/ownership.md
@@ -1,4 +1,4 @@
-% Ownership
+# Ownership
 
 This is the first of three sections presenting Rust’s ownership system. This is one of
 Rust’s most distinct and compelling features, with which Rust developers should
diff --git a/src/doc/book/patterns.md b/src/doc/book/src/patterns.md
index 24f71608a5b..1983927085c 100644
--- a/src/doc/book/patterns.md
+++ b/src/doc/book/src/patterns.md
@@ -1,4 +1,4 @@
-% Patterns
+# Patterns
 
 Patterns are quite common in Rust. We use them in [variable
 bindings][bindings], [match expressions][match], and other places, too. Let’s go
diff --git a/src/doc/book/primitive-types.md b/src/doc/book/src/primitive-types.md
index c4169d64ccc..8fd3d17c15e 100644
--- a/src/doc/book/primitive-types.md
+++ b/src/doc/book/src/primitive-types.md
@@ -1,4 +1,4 @@
-% Primitive Types
+# Primitive Types
 
 The Rust language has a number of types that are considered ‘primitive’. This
 means that they’re built-in to the language. Rust is structured in such a way
diff --git a/src/doc/book/procedural-macros.md b/src/doc/book/src/procedural-macros.md
index 37d3d20c06d..d286c3b7bdc 100644
--- a/src/doc/book/procedural-macros.md
+++ b/src/doc/book/src/procedural-macros.md
@@ -1,4 +1,4 @@
-% Procedural Macros (and custom Derive)
+# Procedural Macros (and custom Derive)
 
 As you've seen throughout the rest of the book, Rust provides a mechanism
 called "derive" that lets you implement traits easily. For example,
diff --git a/src/doc/book/raw-pointers.md b/src/doc/book/src/raw-pointers.md
index 2386475d15e..1f75665f4b8 100644
--- a/src/doc/book/raw-pointers.md
+++ b/src/doc/book/src/raw-pointers.md
@@ -1,4 +1,4 @@
-% Raw Pointers
+# Raw Pointers
 
 Rust has a number of different smart pointer types in its standard library, but
 there are two types that are extra-special. Much of Rust’s safety comes from
diff --git a/src/doc/book/references-and-borrowing.md b/src/doc/book/src/references-and-borrowing.md
index 6c9c4fa7dd4..f01aa45385a 100644
--- a/src/doc/book/references-and-borrowing.md
+++ b/src/doc/book/src/references-and-borrowing.md
@@ -1,4 +1,4 @@
-% References and Borrowing
+# References and Borrowing
 
 This is the second of three sections presenting Rust’s ownership system. This is one of
 Rust’s most distinct and compelling features, with which Rust developers should
diff --git a/src/doc/book/release-channels.md b/src/doc/book/src/release-channels.md
index 1e203c6553e..af89ca83484 100644
--- a/src/doc/book/release-channels.md
+++ b/src/doc/book/src/release-channels.md
@@ -1,4 +1,4 @@
-% Release Channels
+# Release Channels
 
 The Rust project uses a concept called ‘release channels’ to manage releases.
 It’s important to understand this process to choose which version of Rust
diff --git a/src/doc/book/slice-patterns.md b/src/doc/book/src/slice-patterns.md
index fcedf0c994f..3f7398dde5e 100644
--- a/src/doc/book/slice-patterns.md
+++ b/src/doc/book/src/slice-patterns.md
@@ -1,4 +1,4 @@
-% Slice patterns
+# Slice patterns
 
 If you want to match against a slice or array, you can use `&` with the
 `slice_patterns` feature:
diff --git a/src/doc/book/strings.md b/src/doc/book/src/strings.md
index a2146b669e3..ac41be11854 100644
--- a/src/doc/book/strings.md
+++ b/src/doc/book/src/strings.md
@@ -1,4 +1,4 @@
-% Strings
+# Strings
 
 Strings are an important concept for any programmer to master. Rust’s string
 handling system is a bit different from other languages, due to its systems
diff --git a/src/doc/book/structs.md b/src/doc/book/src/structs.md
index f10fb6274c6..51af343c130 100644
--- a/src/doc/book/structs.md
+++ b/src/doc/book/src/structs.md
@@ -1,4 +1,4 @@
-% Structs
+# Structs
 
 `struct`s are a way of creating more complex data types. For example, if we were
 doing calculations involving coordinates in 2D space, we would need both an `x`
diff --git a/src/doc/book/syntax-and-semantics.md b/src/doc/book/src/syntax-and-semantics.md
index e9ec26dccdc..aa4c1251024 100644
--- a/src/doc/book/syntax-and-semantics.md
+++ b/src/doc/book/src/syntax-and-semantics.md
@@ -1,4 +1,4 @@
-% Syntax and Semantics
+# Syntax and Semantics
 
 This chapter breaks Rust down into small chunks, one for each concept.
 
diff --git a/src/doc/book/syntax-index.md b/src/doc/book/src/syntax-index.md
index 5fa78001fad..d8bb4fadc0b 100644
--- a/src/doc/book/syntax-index.md
+++ b/src/doc/book/src/syntax-index.md
@@ -1,4 +1,4 @@
-% Syntax Index
+# Syntax Index
 
 ## Keywords
 
diff --git a/src/doc/book/testing.md b/src/doc/book/src/testing.md
index ef19c0dc7cc..291c4481d55 100644
--- a/src/doc/book/testing.md
+++ b/src/doc/book/src/testing.md
@@ -1,4 +1,4 @@
-% Testing
+# Testing
 
 > Program testing can be a very effective way to show the presence of bugs, but
 > it is hopelessly inadequate for showing their absence.
diff --git a/src/doc/book/the-stack-and-the-heap.md b/src/doc/book/src/the-stack-and-the-heap.md
index aee45299cf2..b9b3b801eae 100644
--- a/src/doc/book/the-stack-and-the-heap.md
+++ b/src/doc/book/src/the-stack-and-the-heap.md
@@ -1,4 +1,4 @@
-% The Stack and the Heap
+# The Stack and the Heap
 
 As a systems language, Rust operates at a low level. If you’re coming from a
 high-level language, there are some aspects of systems programming that you may
diff --git a/src/doc/book/trait-objects.md b/src/doc/book/src/trait-objects.md
index 00a841a75db..a77d5fe93b5 100644
--- a/src/doc/book/trait-objects.md
+++ b/src/doc/book/src/trait-objects.md
@@ -1,4 +1,4 @@
-% Trait Objects
+# Trait Objects
 
 When code involves polymorphism, there needs to be a mechanism to determine
 which specific version is actually run. This is called ‘dispatch’. There are
diff --git a/src/doc/book/traits.md b/src/doc/book/src/traits.md
index 4747869b65c..19a133f84b0 100644
--- a/src/doc/book/traits.md
+++ b/src/doc/book/src/traits.md
@@ -1,4 +1,4 @@
-% Traits
+# Traits
 
 A trait is a language feature that tells the Rust compiler about
 functionality a type must provide.
diff --git a/src/doc/book/type-aliases.md b/src/doc/book/src/type-aliases.md
index 3798336f0a5..1bd0f78e368 100644
--- a/src/doc/book/type-aliases.md
+++ b/src/doc/book/src/type-aliases.md
@@ -1,4 +1,4 @@
-% Type Aliases
+# Type Aliases
 
 The `type` keyword lets you declare an alias of another type:
 
diff --git a/src/doc/book/ufcs.md b/src/doc/book/src/ufcs.md
index 7725970564b..016ecc70976 100644
--- a/src/doc/book/ufcs.md
+++ b/src/doc/book/src/ufcs.md
@@ -1,4 +1,4 @@
-% Universal Function Call Syntax
+# Universal Function Call Syntax
 
 Sometimes, functions can have the same names. Consider this code:
 
diff --git a/src/doc/book/unsafe.md b/src/doc/book/src/unsafe.md
index a272afa70bb..e90a4b1c268 100644
--- a/src/doc/book/unsafe.md
+++ b/src/doc/book/src/unsafe.md
@@ -1,4 +1,4 @@
-% Unsafe
+# Unsafe
 
 Rust’s main draw is its powerful static guarantees about behavior. But safety
 checks are conservative by nature: there are some programs that are actually
diff --git a/src/doc/book/unsized-types.md b/src/doc/book/src/unsized-types.md
index a23470d39fa..2d090925d51 100644
--- a/src/doc/book/unsized-types.md
+++ b/src/doc/book/src/unsized-types.md
@@ -1,4 +1,4 @@
-% Unsized Types
+# Unsized Types
 
 Most types have a particular size, in bytes, that is knowable at compile time.
 For example, an `i32` is thirty-two bits big, or four bytes. However, there are
diff --git a/src/doc/book/using-rust-without-the-standard-library.md b/src/doc/book/src/using-rust-without-the-standard-library.md
index e66e1d05fff..8458f9314f9 100644
--- a/src/doc/book/using-rust-without-the-standard-library.md
+++ b/src/doc/book/src/using-rust-without-the-standard-library.md
@@ -1,4 +1,4 @@
-% Using Rust Without the Standard Library
+# Using Rust Without the Standard Library
 
 Rust’s standard library provides a lot of useful functionality, but assumes
 support for various features of its host system: threads, networking, heap
diff --git a/src/doc/book/variable-bindings.md b/src/doc/book/src/variable-bindings.md
index e1947310a9a..0c8324d83e0 100644
--- a/src/doc/book/variable-bindings.md
+++ b/src/doc/book/src/variable-bindings.md
@@ -1,4 +1,4 @@
-% Variable Bindings
+# Variable Bindings
 
 Virtually every non-'Hello World’ Rust program uses *variable bindings*. They
 bind some value to a name, so it can be used later. `let` is
diff --git a/src/doc/book/vectors.md b/src/doc/book/src/vectors.md
index b948a54f44a..aff078718df 100644
--- a/src/doc/book/vectors.md
+++ b/src/doc/book/src/vectors.md
@@ -1,4 +1,4 @@
-% Vectors
+# Vectors
 
 A ‘vector’ is a dynamic or ‘growable’ array, implemented as the standard
 library type [`Vec<T>`][vec]. The `T` means that we can have vectors