Added documentation on contribution + some formatting

docs/contributing.md

@@ -1,7 +1,7 @@
 # Contributing
 
-Interested in contributing to the Material theme? Before you do, please read
+Interested in contributing to the Material theme? Want to report a bug? Before
-the following guidelines.
+you do, please read the following guidelines.
 
 ## Submission context
 
@@ -15,8 +15,12 @@ For quick questions there's no need to open an issue as you can reach us on
 ### Found a bug?
 
 If you found a bug in the source code, you can help us by submitting an issue
-to our GitHub Repository. Even better, you can submit a Pull Request with a
+to the [issue tracker][2] in our GitHub repository. Even better, you can submit
-fix. However, before doing so, read the submission guidelines.
+a Pull Request with a fix. However, before doing so, please read the
+[submission guidelines][3].
+
+  [2]: https://github.com/squidfunk/mkdocs-material/issues
+  [3]: #submission-guidelines
 
 ### Missing a feature?
 
@@ -47,20 +51,31 @@ readily available.
 We want to fix all the issues as soon as possible, but before fixing a bug we
 need to reproduce and confirm it. In order to reproduce bugs we will
 systematically ask you to provide a minimal reproduction scenario using the
-custom issue template.
+custom issue template. Please stick to the issue template.
 
 Unfortunately we are not able to investigate / fix bugs without a minimal
-reproduction, so if we don't hear back from you we are going to close issues
+reproduction scenario, so if we don't hear back from you we may close the issue.
-that don't have enough information to be reproduced.
 
 ### Submitting a Pull Request (PR)
 
 Search GitHub for an open or closed PR that relates to your submission. You
-don't want to duplicate effort. Fork the project, make your changes in **a new
+don't want to duplicate effort. If you do not find a related issue or PR,
-git branch** and commit your changes with a descriptive commit message. Then
+go ahead.
-push your branch to GitHub and send a PR to `mkdocs-material:master`. If we
+
-suggest changes, make the required updates, rebase your branch and push
+1. **Development**: Fork the project, set up the [development environment][4],
-the changes to your GitHub repository, which will automatiaclly update your PR.
+  make your changes in a separate git branch and add descriptive messages to
+  your commits.
+
+2. **Build**: Before submitting a pull requests, build the theme. This is a
+  mandatory requirement for your PR to get accepted, as the theme should at
+  all times be installable through GitHub.
+
+3. **Pull Request**: After building the theme, commit the compiled output, push
+  your branch to GitHub and send a PR to `mkdocs-material:master`. If we
+  suggest changes, make the required updates, rebase your branch and push the
+  changes to your GitHub repository, which will automatically update your PR.
 
 After your PR is merged, you can safely delete your branch and pull the changes
 from the main (upstream) repository.
+
+  [4]: http://localhost:8000/customization/#theme-development

docs/customization.md

@@ -19,7 +19,7 @@ JavaScript files to the `docs` directory.
 
 If you want to tweak some colors or change the spacing of certain elements,
 you can do this in a separate stylesheet. The easiest way is by creating a
-new stylesheet file in your docs directory:
+new stylesheet file in your `docs` directory:
 
 ``` sh
 mkdir docs/stylesheets
@@ -40,7 +40,7 @@ saving, as the MkDocs development server implements live reloading. Cool, huh?
 
 The same is true for additional JavaScript. If you want to integrate another
 syntax highlighter or add some custom logic to your theme, create a new
-JavaScript file in your docs directory:
+JavaScript file in your `docs` directory:
 
 ``` sh
 mkdir docs/javascripts
@@ -99,6 +99,7 @@ The directory layout of the Material theme is as follows:
 │  ├─ fonts.html                       # Webfont definitions
 │  ├─ footer.html                      # Footer bar
 │  ├─ header.html                      # Header bar
+│  ├─ i18n.html                        # Localized labels
 │  ├─ nav-item.html                    # Main navigation item
 │  ├─ nav.html                         # Main navigation
 │  ├─ search.html                      # Search box
@@ -183,6 +184,7 @@ Next, all dependencies need to be installed, which is done with:
 
 ``` sh
 cd mkdocs-material
+pip install -r requirements.txt
 npm install
 ```
 
@@ -199,8 +201,7 @@ npm run start
 
 This will also start the MkDocs development server which will monitor changes
 on assets, templates and documentation. Point your browser to
-[localhost:8000](http://localhost:8000) and you should see this very
+[localhost:8000][10] and you should see this documentation in front of you.
-documentation in front of your eyes.
 
 For example, changing the color palette is as simple as changing the
 `$md-color-primary` and `$md-color-accent` variables in
@@ -211,7 +212,14 @@ $md-color-primary: $clr-red-400;
 $md-color-accent:  $clr-teal-a700;
 ```
 
+!!! warning "Automatically generated files"
+
+    Never make any changes in the `material` directory, as the contents of this
+    directory are automatically generated from the `src` directory and will be
+    overriden when the theme is built.
+
   [9]: http://gulpjs.com
+  [10]: http://localhost:8000
 
 ### Build process
 

docs/extensions/admonition.md

@@ -18,8 +18,8 @@ markdown_extensions:
 ## Usage
 
 Admonition blocks follow a simple syntax: every block is started with `!!!`,
-followed by a single keyword which is used as the [type qualifier](#types) of
+followed by a single keyword which is used as the [type qualifier][2] of the
-the block. The content of the block then follows on the next line, indented by
+block. The content of the block then follows on the next line, indented by
 four spaces.
 
 Example:
@@ -38,6 +38,8 @@ Result:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
+  [2]: #types
+
 ### Changing the title
 
 By default, the block title will equal the type qualifier. However, it can
@@ -61,8 +63,8 @@ Result:
 
 ### Removing the title
 
-Similar to setting a [custom title](#changing-the-title), the icon and title
+Similar to setting a [custom title][3], the icon and title can be omitted by
-can be omitted by providing an empty string after the type qualifier:
+providing an empty string after the type qualifier:
 
 Example:
 
@@ -80,18 +82,20 @@ Result:
     nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
     massa, nec semper lorem quam in massa.
 
+  [3]: #changing-the-title
+
 ### Embedded code blocks
 
 Blocks can contain all kinds of text content, including headlines, lists,
 paragraphs and other blocks – except code blocks, because the parser from the
 standard Markdown library does not account for those.
 
-However, the [PyMdown Extensions][2] package adds an extension called
+However, the [PyMdown Extensions][4] package adds an extension called
-[SuperFences][3], which makes it possible to nest code blocks within other
+[SuperFences][5], which makes it possible to nest code blocks within other
 blocks.
 
-  [2]: https://facelessuser.github.io/pymdown-extensions
+  [4]: https://facelessuser.github.io/pymdown-extensions
-  [3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
+  [5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
 
 Example:
 
@@ -125,7 +129,9 @@ Example:
 Admonition supports user-defined type qualifiers which may influence the style
 of the inserted block. Following is a list of type qualifiers supported by the
 Material theme, whereas the default type, and thus fallback for unknown type
-qualifiers, is [note](#note).
+qualifiers, is [note][6].
+
+  [6]: #note
 
 ### Note
 

docs/extensions/pymdown.md

@@ -15,8 +15,8 @@ The PyMdown Extensions package can be installed with the following command:
 pip install pymdown-extensions
 ```
 
-The following list of extensions that are part of the PyMdown Extensions package
+The following list of extensions that are part of the PyMdown Extensions
-are recommended to be used together with the Material theme:
+package are recommended to be used together with the Material theme:
 
 ``` yaml
 markdown_extensions:
@@ -33,14 +33,6 @@ markdown_extensions:
   - pymdownx.tilde
 ```
 
-Additionally, there is a [MathJax integration](#arithmatex) which should only
-be switched on if needed, as it adds a few hundred kb of JavaScript:
-
-``` yaml
-markdown_extensions:
-  - pymdownx.arithmatex
-```
-
 ## Usage
 
 ### GitHub Flavored Markdown
@@ -138,31 +130,32 @@ The portion of text that should be erased must be enclosed in two tildes
 
 #### Caret
 
-[Caret][11] is the sister extension of [Tilde](#tilde) and makes it possible to
+[Caret][11] is the sister extension of [Tilde][12] and makes it possible to
 highlight ^^inserted text^^. The portion of text that should be marked as added
 must be enclosed in two carets `^^...^^`.
 
   [11]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
+  [12]: #tilde
 
 #### Mark
 
-[Mark][12] adds the ability to ==highlight text== like it was marked with a
+[Mark][13] adds the ability to ==highlight text== like it was marked with a
 ==yellow text marker==. The portion of text that should be highlighted must be
 enclosed in two equal signs `==...==`.
 
-  [12]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
+  [13]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
 
 #### SmartSymbols
 
-[SmartSymbols][13] converts markup for special characters into their
+[SmartSymbols][14] converts markup for special characters into their
 corresponding symbols, e.g. arrows (<--, -->, <-->), trademark and copyright
 symbols ((c), (tm), (r)) and fractions (1/2, 1/4, ...).
 
-  [13]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
+  [14]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
 
 #### Critic
 
-[Critic][14] implements [Critic Markup][15], a Markdown extension that enables
+[Critic][15] implements [Critic Markup][16], a Markdown extension that enables
 the tracking of changes (additions, deletions and comments) on documents.
 During compilation of the Markdown document, changes can be rendered (default),
 accepted or rejected.
@@ -171,21 +164,21 @@ Text can be {--deleted--} and replacement text {++added++}. This can also be
 combined in {~~one~>a single~~} operation. {==Highlighting==} is also possible
 {>>and comments can be added inline<<}.
 
-  [14]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
+  [15]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
-  [15]: http://criticmarkup.com/
+  [16]: http://criticmarkup.com/
 
 ### Math and code highlighting
 
 #### Arithmatex
 
-[Arithmatex][16] integrates Material with [MathJax][17] which parses
+[Arithmatex][17] integrates Material with [MathJax][18] which parses
 block-style and inline equations written in TeX markup and outputs them in
-mathematical notation. See [this thread][18] for a short introduction and quick
+mathematical notation. See [this thread][19] for a short introduction and quick
 reference on how to write equations in TeX syntax.
 
-  [16]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
+  [17]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
-  [17]: https://www.mathjax.org/
+  [18]: https://www.mathjax.org/
-  [18]: http://meta.math.stackexchange.com/questions/5020/
+  [19]: http://meta.math.stackexchange.com/questions/5020/
 
 ##### Blocks
 
@@ -221,9 +214,9 @@ Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
 
 #### Inlinehilite
 
-[Inlinehilite][19] adds support for inline code highlighting. It's useful for
+[Inlinehilite][20] adds support for inline code highlighting. It's useful for
 short snippets included within body copy, e.g. `#!js var test = 0;` and can be
 achived by prefixing inline code with a shebang and language identifier,
 e.g. `#!js`.
 
-  [19]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
+  [20]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/

docs/getting-started.md

@@ -26,8 +26,8 @@ pip install mkdocs && mkdocs --version
 
     Material requires MkDocs >= 0.16.
 
-Furthermore, it is highly recommended to install [Pygments][2] and the [PyMdown
+Furthermore, it is highly recommended to install [Pygments][2] and the
-Extensions][3] to get the most out of the Material theme:
+[PyMdown Extensions][3] to get the most out of the Material theme:
 
 ```sh
 pip install pygments
@@ -71,8 +71,9 @@ repository into a subfolder of your project's root directory:
 git clone https://github.com/squidfunk/mkdocs-material.git
 ```
 
-This is especially useful if you want to extend the theme and use partials.
+This is especially useful if you want to extend the theme and override some
-The theme will reside in the folder `mkdocs-material/material`.
+parts of the theme. The theme will reside in the folder
+`mkdocs-material/material`.
 
 ## Usage
 
@@ -96,9 +97,11 @@ as you go - very handy. Spin it up with the following command:
 mkdocs serve
 ```
 
-Now you can point your browser to [localhost:8000](http://localhost:8000) and
+Now you can point your browser to [localhost:8000][4] and the Material theme
-the Material theme should be visible. You can now start writing your
+should be visible. You can now start writing your documentation, or read on and
-documentation, or read on and customize the theme through some options.
+customize the theme through some options.
+
+  [4]: http://localhost:8000
 
 ## Options
 
@@ -108,7 +111,7 @@ project's `mkdocs.yml`. See the following section for all available options.
 ### Changing the color palette
 
 Material defines a default hue for every primary and accent color on Google's
-material design [color palette][4]. This makes it very easy to change the
+material design [color palette][5]. This makes it very easy to change the
 overall look of the theme. Just set the primary and accent colors using the
 following variables in your `mkdocs.yml`:
 
@@ -127,10 +130,11 @@ green`, `lime`, `yellow`, `amber`, `orange`, `deep orange`, `brown`, `grey` and
 
 If the color is set via this configuration, an additional CSS file that
 defines the color palette is included. If you want to keep things lean, clone
-the repository and recompile the theme with your custom colors set. See [this
+the repository and recompile the theme with your custom colors set. See
-article](customization.md) for more information.
+[this article][6] for more information.
 
-  [4]: http://www.materialui.co/colors
+  [5]: http://www.materialui.co/colors
+  [6]: customization.md
 
 #### Primary colors
 
@@ -197,10 +201,10 @@ Click on a tile to change the accent color of the theme:
 
 ### Changing the font family
 
-Material uses the [Roboto font family][5] by default, specifically the regular
+Material uses the [Roboto font family][7] by default, specifically the regular
-sans-serif type for text and the monospaced type for code. Both fonts are
+sans-serif type for text and the `monospaced` type for code. Both fonts are
-loaded from [Google Fonts][6] and can easily be changed to other fonts, like
+loaded from [Google Fonts][8] and can easily be changed to other fonts, like
-for example the [Ubuntu font family][7]:
+for example the [Ubuntu font family][9]:
 
 ``` yaml
 extra:
@@ -209,7 +213,7 @@ extra:
     code: 'Ubuntu Mono'
 ```
 
-The text font will be loaded in font-weights 400 and **700**, the monospaced
+The text font will be loaded in font-weights 400 and **700**, the `monospaced`
 font in regular weight. If you want to load fonts from other destinations or
 don't want to use the Google Fonts loading magic, just set `font` to `'none'`:
 
@@ -218,9 +222,9 @@ extra:
   font: 'none'
 ```
 
-  [5]: https://fonts.google.com/specimen/Roboto
+  [7]: https://fonts.google.com/specimen/Roboto
-  [6]: https://fonts.google.com/
+  [8]: https://fonts.google.com/
-  [7]: https://fonts.google.com/specimen/Ubuntu
+  [9]: https://fonts.google.com/specimen/Ubuntu
 
 ### Adding a logo
 
@@ -239,7 +243,7 @@ extra:
 
 If you want to link your social accounts, the Material theme provides an easy
 way for doing this in the footer of the documentation using the automatically
-included [FontAwesome][8] webfont. The syntax is simple – the `type` denotes
+included [FontAwesome][10] webfont. The syntax is simple – the `type` denotes
 the name of the social service, e.g. `github`, `twitter` or `linkedin` and
 the `link`, well, resembles the link:
 
@@ -258,7 +262,7 @@ The links are generated in order and the type of the link must match the name
 of the FontAwesome glyph. The `fa` is automatically added, so `github` will
 result in `fa fa-github`.
 
-  [8]: http://fontawesome.io/icons/
+  [10]: http://fontawesome.io/icons/
 
 ### Google Analytics integration
 
@@ -291,19 +295,22 @@ inside the macro `t`:
 ```
 
 Just copy the file from the original theme and make your adjustments. See the
-section on [overriding partials](customization.md/#overriding-partials) in the
+section on [overriding partials][11] in the customization guide.
-customization guide.
+
+  [11]: customization.md#overriding-partials
 
 ### More advanced customization
 
 If you want to change the general appearance of the Material theme, see
-[this article](customization.md) for more information on advanced customization.
+[this article][12] for more information on advanced customization.
+
+  [12]: customization.md
 
 ## Extensions
 
-MkDocs supports several [Markdown extensions][9]. The following extensions are
+MkDocs supports several [Markdown extensions][13]. The following extensions
-not enabled by default (see the link for which are enabled by default) but
+are not enabled by default (see the link for which are enabled by default)
-highly recommended, so they should be switched on at all times:
+but highly recommended, so they should be switched on at all times:
 
 ``` yaml
 markdown_extensions:
@@ -312,16 +319,29 @@ markdown_extensions:
   - toc(permalink=true)
 ```
 
+!!! warning "Migrating from Material 0.2.x"
+
+    The [CodeHilite][14] extension was included with
+    `codehilite(css_class=code)` which switched the CSS class from
+    `.codehilite` to `.code`. The current version of the theme doesn't require
+    that and defines styles for the default `.codehilite` class, so the part
+    `css_class=code` needs to be removed.
+
 For more information, see the following list of extensions supported by the
 Material theme including more information regarding installation and usage:
 
-* [Admonition](extensions/admonition.md)
+* [Admonition][15]
-* [Codehilite](extensions/codehilite.md)
+* [Codehilite][14]
-* [Permalinks](extensions/permalinks.md)
+* [Permalinks][16]
-* [Footnotes](extensions/footnotes.md)
+* [Footnotes][17]
-* [PyMdown Extensions](extensions/pymdown.md)
+* [PyMdown Extensions][18]
 
-  [9]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
+  [13]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
+  [14]: extensions/codehilite.md
+  [15]: extensions/admonition.md
+  [16]: extensions/permalinks.md
+  [17]: extensions/footnotes.md
+  [18]: extensions/pymdown.md
 
 ## Full example
 

docs/license.md

@@ -2,7 +2,7 @@
 
 **MIT License**
 
-Copyright (c) 2016 Martin Donath
+Copyright © 2016 Martin Donath
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to