Updated documentation for 1.0.0

docs/contributing.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Interested in contributing to the Material theme? Before you do, please read
+the following guidelines.
+
+## Submission context
+
+### Got a question or problem?
+
+For quick questions there's no need to open an issue as you can reach us on
+[gitter.im][1].
+
+  [1]: https://gitter.im/mkdocs-material/general
+
+### 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
+fix. However, before doing so, read the submission guidelines.
+
+### Missing a feature?
+
+You can request a new feature by submitting an issue to our GitHub Repository.
+If you would like to implement a new feature, please submit an issue with a
+proposal for your work first, to be sure that it is of use for everyone, as
+the Material theme is highly opinionated. Please consider what kind of change
+it is:
+
+* For a **Major Feature**, first open an issue and outline your proposal so
+  that it can be discussed. This will also allow us to better coordinate our
+  efforts, prevent duplication of work, and help you to craft the change so
+  that it is successfully accepted into the project.
+
+* **Small Features** and bugs can be crafted and directly submitted as a Pull
+  Request. However, there is no guarantee that your feature will make it into
+  the master, as it's always a matter of opinion whether if benefits the
+  overall functionality of the theme.
+
+## Submission guidelines
+
+### Submitting an issue
+
+Before you submit an issue, please search the issue tracker, maybe an issue for
+your problem already exists and the discussion might inform you of workarounds
+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.
+
+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
+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
+git branch** and commit your changes with a descriptive commit message. Then
+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 automatiaclly update your PR.
+
+After your PR is merged, you can safely delete your branch and pull the changes
+from the main (upstream) repository.

docs/customization.md

@@ -1,100 +1,228 @@
 # Customization
 
-## A good starting point
+## A great starting point
 
 Project documentation is as diverse as the projects themselves and the Material
-theme is a good starting point for making it look good. However, as you write
+theme is a good starting point for making it look great. However, as you write
 your documentation, you may reach some point where some small adjustments are
 necessary to preserve the style.
 
-## Small tweaks
+## Adding assets
 
-[MkDocs][] provides a simple way for making small adjustments, that is changing
+[MkDocs][1] provides several ways to interfere with themes. In order to make a
-some margins, centering text, etc. Simply put the CSS and Javascript files that
+few tweaks to an existing theme, you can just add your stylesheets and
-contain your adjustments in the `docs` directory (ideally in subdirectories of
+JavaScript files to the `docs` directory.
-their own) and include them via the `extra_css` and `extra_javascript`
-variables in your `mkdocs.yml`:
 
-``` yaml
+  [1]: http://www.mkdocs.org
-extra_css: ['/stylesheets/extra.css']
+
-extra_javascript: ['/javascripts/extra.js']
+### Additional stylesheets
+
+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:
+
+``` sh
+mkdir docs/stylesheets
+touch docs/stylesheets/extra.css
 ```
 
-Further assistance on including extra CSS and Javascript can be found in the
+Then, add the following line to your `mkdocs.yml`:
-[MkDocs documentation][].
 
-## Fundamental changes
+``` yaml
+extra_css: ['stylesheets/extra.css']
+```
 
-If you want to make larger adjustments like changing the color palette or
+Spin up the development server with `mkdocs serve` and start typing your
-typography, you should check out or download the repository of the project and
+changes in your additional stylesheet file – you can see them instantly after
-compile the SASS sources with your changes. The project design is very modular,
+saving, as the MkDocs development server implements live reloading. Cool, huh?
-so most things can be tweaked by changing a few variables.
 
-### Setup
+### Additional JavaScript
 
-In order to compile the project, you need `node` with a version greater than
+The same is true for additional JavaScript. If you want to integrate another
-`0.11` up and running.
+syntax highlighter or add some custom logic to your theme, create a new
+JavaScript file in your docs directory:
 
-The project itself is hosted on GitHub, so the next
+``` sh
-thing you should do is clone the project from GitHub:
+mkdir docs/javascripts
+touch docs/javascripts/extra.js
+```
+
+Then, add the following line to your `mkdocs.yml`:
+
+``` yaml
+extra_javascript: ['javascripts/extra.js']
+```
+
+Further assistance can be found in the [MkDocs documentation][2].
+
+  [2]: http://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme
+
+## Extending the theme
+
+If you want to alter the HTML source (e.g. add or remove some part), you can
+extend the theme. From version 0.16 on MkDocs implements [theme extension][3],
+an easy way to override parts of a theme without forking and changing the
+main theme.
+
+  [3]: http://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme_dir
+
+### Setup and theme structure
+
+Reference the Material theme as usual in your `mkdocs.yml`, and create a
+new folder for overrides, e.g. `theme`, which you reference using `theme_dir`:
+
+``` yaml
+theme: 'material'
+theme_dir: 'theme'
+```
+
+!!! warning "Theme extension prerequisites"
+
+    As the `theme_dir` variable is used for the theme extension process, the
+    Material theme needs to be installed via `pip` and referenced with the
+    `theme` parameter in your `mkdocs.yml`.
+
+The structure in the theme directory must mirror the directory structure of the
+original theme, as any file in the theme directory will replace the file with
+the same name which is part of the original theme. Besides, further assets
+may also be put in the theme directory.
+
+The directory layout of the Material theme is as follows:
+
+``` sh
+.
+├─ assets/
+│  ├─ images/                          # Images and icons
+│  ├─ javascripts/                     # JavaScript
+│  └─ stylesheets/                     # Stylesheets
+├─ partials/
+│  ├─ fonts.html                       # Webfont definitions
+│  ├─ footer.html                      # Footer bar
+│  ├─ header.html                      # Header bar
+│  ├─ nav-item.html                    # Main navigation item
+│  ├─ nav.html                         # Main navigation
+│  ├─ search.html                      # Search box
+│  ├─ source.html                      # Repository information
+│  ├─ svgs.html                        # Inline SVG definitions
+│  ├─ toc-item.html                    # Table of contents item
+│  └─ toc.html                         # Table of contents
+├─ 404.html                            # 404 error page
+├─ base.html                           # Base template
+└─ main.html                           # Default page
+```
+
+### Overriding partials
+
+In order to override the footer, we can replace the `footer.html` partial with
+our own partial. To do this, create the file `partials/footer.html` in the
+theme directory. MkDocs will now use the new partial when rendering the theme.
+This can be done with any file.
+
+### Overriding template blocks
+
+Besides overriding partials, one can also override so called template blocks,
+which are defined inside the Material theme and wrap specific features. To
+override a template block, create a `main.html` inside the theme directory and
+define the block, e.g.:
+
+``` jinja
+{% extends "base.html" %}
+
+{% block htmltitle %}
+  <title>Lorem ipsum dolor sit amet</title>
+{% endblock %}
+```
+
+The Material theme provides the following template blocks:
+
+| Block name   | Wrapped contents                                |
+| ------------ | ----------------------------------------------- |
+| `analytics`  | Wraps the Google Analytics integration          |
+| `content`    | Wraps the main content                          |
+| `extrahead`  | Empty block to define additional meta tags      |
+| `fonts`      | Wraps the webfont definitions                   |
+| `footer`     | Wraps the footer with navigation and copyright  |
+| `header`     | Wraps the fixed header bar                      |
+| `htmltitle`  | Wraps the `<title>` tag                         |
+| `libs`       | Wraps the JavaScript libraries, e.g. Modernizr  |
+| `repo`       | Wraps the repository link in the header bar     |
+| `scripts`    | Wraps the JavaScript application logic          |
+| `search_box` | Wraps the search form in the header bar         |
+| `site_meta`  | Wraps the meta tags in the document head        |
+| `site_name`  | Wraps the site name in the header bar           |
+| `site_nav`   | Wraps the site navigation and table of contents |
+| `styles`     | Wraps the stylesheets (also extra sources)      |
+
+For more on this topic refer to the [MkDocs documentation][4]
+
+  [4]: http://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
+
+## Theme development
+
+The Material theme is built on modern technologies like ES6, [Webpack][5],
+[Babel][6] and [SASS][7]. If you want to make more fundamental changes, it may
+be necessary to make the adjustments directly in the source of the Material
+theme and recompile it. This is fairly easy.
+
+  [5]: https://webpack.github.io/
+  [6]: https://babeljs.io
+  [7]: http://sass-lang.com
+
+### Environment setup
+
+In order to start development on the Material theme, a [Node.js][8] version of
+at least 4 is required. Clone the repository from GitHub:
 
 ``` sh
 git clone https://github.com/squidfunk/mkdocs-material
 ```
 
-Then you change the directory and install all dependencies specified in the
+Next, all dependencies need to be installed, which is done with:
-`package.json` and `bower.json` with the following command:
 
 ``` sh
 cd mkdocs-material
 npm install
 ```
 
-### Development
+  [8]: https://nodejs.org
 
-The asset pipeline is contained in `Gulpfile.js`, which you can start with
+### Development mode
-`gulp watch`. If you specify the `--mkdocs` flag, this will also run
+
-`mkdocs serve`, to monitor changes to the documentation. Point your browser to [localhost:8000](http://localhost:8000) and you should see this very
+The Material theme uses a sophisticated asset pipeline using [Gulp][9] and
-documentation in front of your eyes.
+Webpack which can be started with the following command:
 
 ``` sh
-gulp watch --mkdocs
+npm run start
 ```
 
-For example, changing the color palette is as simple as changing the `$primary`
+This will also start the MkDocs development server which will monitor changes
-and `$accent` variables in `src/assets/stylesheets/_palette.scss`:
+on assets, templates and documentation. Point your browser to
+[localhost:8000](http://localhost:8000) and you should see this very
+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
+`src/assets/stylesheets/_config.scss`:
 
 ``` css
-$primary: $red-400;
+$md-color-primary: $clr-red-400;
-$accent:  $teal-a700;
+$md-color-accent:  $clr-teal-a700;
 ```
 
-The color variables are defined by the SASS library [quantum-colors][] and
+  [9]: http://gulpjs.com
-resemble all the colors contained in the material design palette.
-[This page][material-colors] offers a really good overview of the palette.
 
-### Building
+### Build process
 
 When you finished making your changes, you can build the theme by invoking:
 
 ``` sh
-gulp build --production
+npm run build
 ```
 
-The `--production` flag triggers the production-level compilation and
+This triggers the production-level compilation and minification of all
-minification of all CSS and Javascript sources. When the command is ready,
+stylesheets and JavaScript sources. When the command is ready, the final
-the final theme is located in the `material` directory. Add the `theme_dir`
+theme is located in the `material` directory. Add the `theme_dir` variable
-variable pointing to the aforementioned directory in your original
+pointing to the aforementioned directory in your original `mkdocs.yml`.
-`mkdocs.yml`:
-
-``` yaml
-theme_dir: 'mkdocs-material/material'
-```
 
 Now you can run `mkdocs build` and you should see your documentation with your
 changes to the original Material theme.
-
-[MkDocs]: http://www.mkdocs.org
-[MkDocs documentation]: http://www.mkdocs.org/user-guide/styling-your-docs/#customising-a-theme
-[quantum-colors]: https://github.com/nkpfstr/quantum-colors
-[material-colors]: http://www.materialui.co/colors

docs/extensions/footnotes.md

@@ -58,7 +58,7 @@ Result:
 
 <a href="#fn:1">Jump to footnote at the bottom of the page</a>
 
-[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+  [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 
 #### on multiple lines
 
@@ -76,9 +76,9 @@ Example:
 
 Result:
 
-[^2]:
+  [^2]:
-    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
-    nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
+      nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
-    massa, nec semper lorem quam in massa.
+      auctor massa, nec semper lorem quam in massa.
 
 <a href="#fn:2">Jump to footnote at the bottom of the page</a>

docs/extensions/pymdown.md

@@ -41,7 +41,7 @@ markdown_extensions:
   - pymdownx.arithmatex
 ```
 
-## Extensions
+## Usage
 
 ### GitHub Flavored Markdown
 

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
+Furthermore, it is highly recommended to install [Pygments][2] and the [PyMdown
-[PyMdown Extensions][3] to get the most out of the Material theme:
+Extensions][3] to get the most out of the Material theme:
 
 ```sh
 pip install pygments
@@ -241,7 +241,7 @@ 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 [Socicon][8] 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:
+`link`, well, resembles the link:
 
 ``` yaml
 extra:

docs/index.md

@@ -1,9 +1,9 @@
 # Material <small>for MkDocs</small>
 
-## Beautiful documentation
+## Build beautiful documentation
 
-Material is a theme for [MkDocs][], an excellent static site generator geared
+Material is a theme for [MkDocs][1], an excellent static site generator geared
-towards project documentation. It is built using Google's [material design][]
+towards project documentation. It is built using Google's [material design][2]
 guidelines, full responsive, optimized for touch and pointer devices as well
 as all sorts of screen sizes.
 
@@ -12,9 +12,12 @@ CSS that weighs less than 30kb (minified, gzipped and excluding Google Fonts
 and Analytics). Yet, it is highly customizable and degrades gracefully in older
 browsers.
 
+  [1]: http://www.mkdocs.org
+  [2]: https://www.google.com/design/spec/material-design
+
 ## Quick start
 
-Install with `pip`:
+Install the latest version of Material with `pip`:
 
 ``` sh
 pip install mkdocs-material
@@ -52,8 +55,7 @@ theme: 'material'
 See the [getting started guide](getting-started.md) for instructions how to get
 it up and running.
 
-[MkDocs]: http://www.mkdocs.org
+
-[material design]: https://www.google.com/design/spec/material-design
 [checkbox hack]: http://tutorialzine.com/2015/08/quick-tip-css-only-dropdowns-with-the-checkbox-hack/
 [project logo]: getting-started.md#adding-a-logo
 [easily customizable color palette]: getting-started.md#changing-the-color-palette

docs/specimen.md

@@ -1,8 +1,6 @@
 # Specimen
 
-## Typography
+## Body copy
-
-### Body copy
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras arcu libero,
 mollis sed massa vel, *ornare viverra ex*. Mauris a ullamcorper lacus. Nullam
@@ -16,7 +14,9 @@ eros. [Nulla aliquam](/) orci sit amet nisl posuere malesuada. Proin aliquet
 nulla velit, quis ultricies orci feugiat et. `Ut tincidunt sollicitudin`
 tincidunt. Aenean ullamcorper sit amet nulla at interdum.
 
-### Headings
+## Headings
+
+### The 3rd level
 
 #### The 4th level
 
@@ -24,7 +24,9 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
 
 ###### The 6th level
 
-### Headings <small>with secondary text</small>
+## Headings <small>with secondary text</small>
+
+### The 3rd level <small>with secondary text</small>
 
 #### The 4th level <small>with secondary text</small>
 
@@ -32,7 +34,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
 
 ###### The 6th level <small>with secondary text</small>
 
-### Blockquotes
+## Blockquotes
 
 > Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum.
   Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc
@@ -40,7 +42,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
   litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie
   imperdiet consectetur.
 
-#### Blockquote nesting
+### Blockquote nesting
 
 > **Sed aliquet**, neque at rutrum mollis, neque nisi tincidunt nibh, vitae
   faucibus lacus nunc at lacus. Nunc scelerisque, quam id cursus sodales, lorem
@@ -55,7 +57,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
       Interdum et malesuada fames ac ante ipsum primis in faucibus. Sed nec leo
       bibendum, sodales mauris ut, tincidunt massa.
 
-#### Other content blocks
+### Other content blocks
 
 > Vestibulum vitae orci quis ante viverra ultricies ut eget turpis. Sed eu
   lectus dapibus, eleifend nulla varius, lobortis turpis. In ac hendrerit nisl,
@@ -76,9 +78,9 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
       vel lacinia lacus. Suspendisse rhoncus nunc non nisi iaculis ultrices.
       Donec consectetur mauris non neque imperdiet, eget volutpat libero.
 
-### Lists
+## Lists
 
-#### Unordered lists
+### Unordered lists
 
 * Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus
   non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor lobortis orci,
@@ -96,7 +98,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
   accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
   lacinia sed. Aenean in finibus diam.
 
-#### Ordered lists
+### Ordered lists
 
 1. Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis
   elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla
@@ -135,9 +137,9 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
   sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
   nulla. Vivamus a pharetra leo.
 
-### Code blocks
+## Code blocks
 
-#### Inline
+### Inline
 
 Morbi eget `dapibus felis`. Vivamus *`venenatis porttitor`* tortor sit amet
 rutrum. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
@@ -148,7 +150,7 @@ Nam vehicula nunc `:::js return target` mauris, a ultricies libero efficitur
 sed. Sed molestie imperdiet consectetur. Vivamus a pharetra leo. Pellentesque
 eget ornare tellus, ut gravida mi. Fusce vel lacinia lacus.
 
-#### Listing
+### Listing
 
     #!js hl_lines="8"
     var _extends = function(target) {
@@ -161,7 +163,7 @@ eget ornare tellus, ut gravida mi. Fusce vel lacinia lacus.
       return target;
     };
 
-### Horizontal rules
+## Horizontal rules
 
 Aenean in finibus diam. Duis mollis est eget nibh volutpat, fermentum aliquet
 dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna
@@ -173,7 +175,7 @@ Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis
 elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla
 consectetur feugiat sodales.
 
-### Data tables
+## Data tables
 
 | Sollicitudo / Pellentesi | consectetur | adipiscing | elit    | arcu | sed |
 | ------------------------ | ----------- | ---------- | ------- | ---- | --- |
@@ -224,68 +226,3 @@ sit amet laoreet nibh.
     </tr>
   </tbody>
 </table>
-
-## Colors
-
-### Primary colors
-
-Click on a tile to change the primary color of the theme:
-
-<button data-md-color-primary="red">Red</button>
-<button data-md-color-primary="pink">Pink</button>
-<button data-md-color-primary="purple">Purple</button>
-<button data-md-color-primary="deep-purple">Deep Purple</button>
-<button data-md-color-primary="indigo">Indigo</button>
-<button data-md-color-primary="blue">Blue</button>
-<button data-md-color-primary="light-blue">Light Blue</button>
-<button data-md-color-primary="cyan">Cyan</button>
-<button data-md-color-primary="teal">Teal</button>
-<button data-md-color-primary="green">Green</button>
-<button data-md-color-primary="light-green">Light Green</button>
-<button data-md-color-primary="lime">Lime</button>
-<button data-md-color-primary="yellow">Yellow</button>
-<button data-md-color-primary="amber">Amber</button>
-<button data-md-color-primary="orange">Orange</button>
-<button data-md-color-primary="deep-orange">Deep Orange</button>
-<button data-md-color-primary="brown">Brown</button>
-<button data-md-color-primary="grey">Grey</button>
-<button data-md-color-primary="blue-grey">Blue Grey</button>
-
-<script>
-  var buttons = document.querySelectorAll("button[data-md-color-primary]");
-  Array.prototype.forEach.call(buttons, function(button) {
-    button.addEventListener("click", function() {
-      document.body.dataset.mdColorPrimary = this.dataset.mdColorPrimary;
-    })
-  })
-</script>
-
-### Accent colors
-
-Click on a tile to change the accent color of the theme:
-
-<button data-md-color-accent="red">Red</button>
-<button data-md-color-accent="pink">Pink</button>
-<button data-md-color-accent="purple">Purple</button>
-<button data-md-color-accent="deep-purple">Deep Purple</button>
-<button data-md-color-accent="indigo">Indigo</button>
-<button data-md-color-accent="blue">Blue</button>
-<button data-md-color-accent="light-blue">Light Blue</button>
-<button data-md-color-accent="cyan">Cyan</button>
-<button data-md-color-accent="teal">Teal</button>
-<button data-md-color-accent="green">Green</button>
-<button data-md-color-accent="light-green">Light Green</button>
-<button data-md-color-accent="lime">Lime</button>
-<button data-md-color-accent="yellow">Yellow</button>
-<button data-md-color-accent="amber">Amber</button>
-<button data-md-color-accent="orange">Orange</button>
-<button data-md-color-accent="deep-orange">Deep Orange</button>
-
-<script>
-  var buttons = document.querySelectorAll("button[data-md-color-accent]");
-  Array.prototype.forEach.call(buttons, function(button) {
-    button.addEventListener("click", function() {
-      document.body.dataset.mdColorAccent = this.dataset.mdColorAccent;
-    })
-  })
-</script>