diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 000000000..64b79ecd7
--- /dev/null
+++ b/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.
diff --git a/docs/customization.md b/docs/customization.md
index ab927c1a3..60ba2ae10 100644
--- a/docs/customization.md
+++ b/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
-some margins, centering text, etc. Simply put the CSS and Javascript files that
-contain your adjustments in the `docs` directory (ideally in subdirectories of
-their own) and include them via the `extra_css` and `extra_javascript`
-variables in your `mkdocs.yml`:
+[MkDocs][1] provides several ways to interfere with themes. In order to make a
+few tweaks to an existing theme, you can just add your stylesheets and
+JavaScript files to the `docs` directory.
-``` yaml
-extra_css: ['/stylesheets/extra.css']
-extra_javascript: ['/javascripts/extra.js']
+ [1]: http://www.mkdocs.org
+
+### 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
-[MkDocs documentation][].
+Then, add the following line to your `mkdocs.yml`:
-## Fundamental changes
+``` yaml
+extra_css: ['stylesheets/extra.css']
+```
-If you want to make larger adjustments like changing the color palette or
-typography, you should check out or download the repository of the project and
-compile the SASS sources with your changes. The project design is very modular,
-so most things can be tweaked by changing a few variables.
+Spin up the development server with `mkdocs serve` and start typing your
+changes in your additional stylesheet file – you can see them instantly after
+saving, as the MkDocs development server implements live reloading. Cool, huh?
-### Setup
+### Additional JavaScript
-In order to compile the project, you need `node` with a version greater than
-`0.11` up and running.
+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:
-The project itself is hosted on GitHub, so the next
-thing you should do is clone the project from GitHub:
+``` sh
+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 %}
+
Lorem ipsum dolor sit amet
+{% 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 `` 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
-`package.json` and `bower.json` with the following command:
+Next, all dependencies need to be installed, which is done with:
``` sh
cd mkdocs-material
npm install
```
-### Development
+ [8]: https://nodejs.org
-The asset pipeline is contained in `Gulpfile.js`, which you can start with
-`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
-documentation in front of your eyes.
+### Development mode
+
+The Material theme uses a sophisticated asset pipeline using [Gulp][9] and
+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`
-and `$accent` variables in `src/assets/stylesheets/_palette.scss`:
+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
+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;
-$accent: $teal-a700;
+$md-color-primary: $clr-red-400;
+$md-color-accent: $clr-teal-a700;
```
-The color variables are defined by the SASS library [quantum-colors][] and
-resemble all the colors contained in the material design palette.
-[This page][material-colors] offers a really good overview of the palette.
+ [9]: http://gulpjs.com
-### 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
-minification of all CSS and Javascript sources. When the command is ready,
-the final theme is located in the `material` directory. Add the `theme_dir`
-variable pointing to the aforementioned directory in your original
-`mkdocs.yml`:
-
-``` yaml
-theme_dir: 'mkdocs-material/material'
-```
+This triggers the production-level compilation and minification of all
+stylesheets and JavaScript sources. When the command is ready, the final
+theme is located in the `material` directory. Add the `theme_dir` variable
+pointing to the aforementioned directory in your original `mkdocs.yml`.
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
diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md
index 9967d526f..7f080547d 100644
--- a/docs/extensions/footnotes.md
+++ b/docs/extensions/footnotes.md
@@ -58,7 +58,7 @@ Result:
Jump to footnote at the bottom of the page
-[^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]:
- Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
- nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
- massa, nec semper lorem quam in massa.
+ [^2]:
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
+ nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
+ auctor massa, nec semper lorem quam in massa.
Jump to footnote at the bottom of the page
diff --git a/docs/extensions/pymdown.md b/docs/extensions/pymdown.md
index 13a7aeab0..b835f6e44 100644
--- a/docs/extensions/pymdown.md
+++ b/docs/extensions/pymdown.md
@@ -41,7 +41,7 @@ markdown_extensions:
- pymdownx.arithmatex
```
-## Extensions
+## Usage
### GitHub Flavored Markdown
diff --git a/docs/getting-started.md b/docs/getting-started.md
index c382938c0..dbe862ec5 100644
--- a/docs/getting-started.md
+++ b/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 Extensions][3] to get the most out of the Material theme:
+Furthermore, it is highly recommended to install [Pygments][2] and the [PyMdown
+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:
diff --git a/docs/index.md b/docs/index.md
index 1ac5b1ae2..a71195f7c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,9 +1,9 @@
# Material for MkDocs
-## Beautiful documentation
+## Build beautiful documentation
-Material is a theme for [MkDocs][], an excellent static site generator geared
-towards project documentation. It is built using Google's [material design][]
+Material is a theme for [MkDocs][1], an excellent static site generator geared
+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
diff --git a/docs/specimen.md b/docs/specimen.md
index 9dad11f0b..fefccdea0 100644
--- a/docs/specimen.md
+++ b/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 with secondary text
+## Headings with secondary text
+
+### The 3rd level with secondary text
#### The 4th level with secondary text
@@ -32,7 +34,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
###### The 6th level with secondary text
-### 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.
-
-## Colors
-
-### Primary colors
-
-Click on a tile to change the primary color of the theme:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-### Accent colors
-
-Click on a tile to change the accent color of the theme:
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-