very early checkin of template for user-docs, only a few pages filled out

7 files changed, 546 insertions, 0 deletions

diff --git a/mkdocs-material/docs/customization.md b/mkdocs-material/docs/customization.md
new file mode 100644
index 00000000..7814b6a8
--- /dev/null
+++ b/mkdocs-material/docs/customization.md
@@ -0,0 +1,104 @@
+# Customization
+
+## A good 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
+your documentation, you may reach some point where some small adjustments are
+necessary to preserve the style.
+
+## Small tweaks
+
+[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`:
+
+``` yaml
+extra_css: ['/stylesheets/extra.css']
+extra_javascript: ['/javascripts/extra.js']
+```
+
+Further assistance on including extra CSS and Javascript can be found in the
+[MkDocs documentation][].
+
+## Fundamental changes
+
+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.
+
+### Setup
+
+In order to compile the project, you need `node` with a version greater than
+`0.11` up and running. Then, make sure `bower` is installed or install it:
+
+``` sh
+npm install -g bower
+```
+
+The project itself is hosted on GitHub, so the next
+thing you should do is clone the project 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:
+
+``` sh
+cd mkdocs-material
+npm install && bower install
+```
+
+### Development
+
+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.
+
+``` sh
+gulp watch --mkdocs
+```
+
+For example, changing the color palette is as simple as changing the `$primary`
+and `$accent` variables in `src/assets/stylesheets/_palette.scss`:
+
+``` css
+$primary: $red-400;
+$accent:  $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.
+
+### Building
+
+When you finished making your changes, you can build the theme by invoking:
+
+``` sh
+gulp build --production
+```
+
+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'
+```
+
+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
\ No newline at end of file
diff --git a/mkdocs-material/docs/getting-started.md b/mkdocs-material/docs/getting-started.md
new file mode 100644
index 00000000..d8cf1907
--- /dev/null
+++ b/mkdocs-material/docs/getting-started.md
@@ -0,0 +1,353 @@
+# Getting started
+
+## Installation
+
+### Installing MkDocs
+
+Before installing [MkDocs][], you need to make sure you have Python and `pip`
+– the Python package manager – up and running. Assuming you are a developer and
+have a basic understanding of how things work and what StackOverflow is, we
+won't provide guidelines on setting those up. You can verify if you're already
+good to go with the following commands:
+
+``` sh
+python --version
+# Python 2.7.2
+pip --version
+# pip 1.5.2
+```
+
+Installing and verifying MkDocs is as simple as:
+
+``` sh
+pip install mkdocs && mkdocs --version
+# mkdocs, version 0.15.2
+```
+
+### Installing Material
+
+Next, assuming you have MkDocs up and running `mkdocs-material` can be
+installed with `pip`:
+
+``` sh
+pip install mkdocs-material
+```
+
+## Usage
+
+If you haven't already done it, creating a new documentation project is really
+simple in MkDocs:
+
+``` sh
+mkdocs new my-project
+cd my-project
+```
+
+MkDocs will create the necessary files and base directory structure inside the
+folder `my-project`. In order to enable the theme just add the following line
+to the auto-generated `mkdocs.yml`:
+
+``` yaml
+theme: 'material'
+```
+
+If your project is hosted on GitHub, add the repository link to the
+configuration. If the `repo_name` equals **GitHub**, the Material theme will
+add a download and star button, and display the number of stars:
+
+``` yaml
+repo_name: 'GitHub'
+repo_url: 'https://github.com/my-github-handle/my-project'
+```
+
+MkDocs includes a development server, so you can view your changes as you go -
+very handy. Spin it up with the following command:
+
+``` sh
+mkdocs serve
+```
+
+Now you can go to [localhost:8000](http://localhost:8000) and the Material
+theme should be visible. You can now start writing your documentation, or read
+on and customize the theme through some options.
+
+## Options
+
+The Material theme adds some extra variables for configuration via your
+project's `mkdocs.yml`. See the following section for all available options.
+
+### Adding a version
+
+In order to add the current version next to the project banner inside the
+drawer, you can set the variable `extra.version`:
+
+``` yaml
+extra:
+  version: '0.1.0'
+```
+
+This will also change the link behind the download button to point to the
+archive with the respective version on GitHub, assuming a release tagged with
+this exact version identifier.
+
+### Adding a logo
+
+If your project has a logo, you can add it to the drawer/navigation by defining
+the variable `extra.logo`. Ideally, the image of your logo should have
+rectangular shape with a minimum resolution of 128x128 and leave some room
+towards the edges. The logo will also be used as a web application icon on iOS.
+Simply create the folder `docs/images`, add your image and reference it via:
+
+``` yaml
+extra:
+  logo: 'images/logo.png'
+```
+
+### Link to GitHub releases page
+
+If your project has a GitHub url configured, the default behavior is that a
+downlink button is displayed, linking to the source download of the given
+`extra.version` or `master` branch. To link to the releases page instead,
+set `extra.github.download_release` to `true`. It will link to the release of
+the given `extra.version` or when no `extra.version` is given, the latest
+release:
+
+``` yaml
+repo_name: GitHub
+repo_url: https://github.com/squidfunk/mkdocs-material
+
+extra:
+  github:
+    download_release: true
+```
+
+
+### Changing the color palette
+
+Material defines a default hue for every primary and accent color on Google's
+material design [color palette][]. This makes it very easy to change the
+overall look of the theme. Just set the variables `extra.palette.primary` and
+`extra.palette.accent` to one of the colors defined in the palette:
+
+``` yaml
+extra:
+  palette:
+    primary: 'indigo'
+    accent: 'light blue'
+```
+
+Color names can be written upper- or lowercase but must match the names of the
+material design [color palette][]. Valid values are: _red_, _pink_, _purple_,
+_deep purple_, _indigo_, _blue_, _light blue_, _cyan_, _teal_, _green_, _light
+green_, _lime_, _yellow_, _amber_, _orange_, _deep orange_, _brown_, _grey_ and
+_blue grey_. The last three colors can only be used as a primary color.
+
+![Material Screenshot](images/colors.png)
+
+If the color is set via this configuration, an additional CSS file called
+`palettes.css` is included that defines the color palettes. If you want to
+keep things lean, clone the repository and recompile the theme with your
+custom colors set. See [this article](customization.md) for more information.
+
+### Changing the font family
+
+Material uses the [Ubuntu font family][] by default, specifically the regular
+sans-serif type for text and the monospaced type for code. Both fonts are
+loaded from [Google Fonts][] and can be easily changed to other fonts, like for
+example Google's own [Roboto font][]:
+
+``` yaml
+extra:
+  font:
+    text: 'Roboto'
+    code: 'Roboto Mono'
+```
+
+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 `extra.font` to
+`'none'`:
+
+``` yaml
+extra:
+  font: 'none'
+```
+
+### Localization
+
+The **Previous** and **Next** labels in the footer can easily be changed by
+defining the variables `extra.i18n.prev` and `extra.i18n.next`:
+
+``` yaml
+extra:
+  i18n:
+    prev: 'Previous'
+    next: 'Next'
+```
+
+### Adding a GitHub and Twitter account
+
+If you have a GitHub and/or Twitter account, you can add links to your
+accounts to the drawer by setting the variables `extra.author.github` and
+`extra.author.twitter` respectively:
+
+``` yaml
+extra:
+  author:
+    github: 'my-github-handle'
+    twitter: 'my-twitter-handle'
+```
+
+### Google Analytics integration
+
+Material makes it easy to integrate site tracking with Google Analytics.
+Besides basic tracking, clicks on all outgoing links can be tracked, clicks on
+the download and star button, as well as how site search is used. Tracking can
+be activated in your project's `mkdocs.yml`:
+
+``` yaml
+google_analytics:
+  - 'UA-XXXXXXXX-X'
+  - 'auto'
+```
+
+### 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.
+
+## Extensions
+
+MkDocs supports several [Markdown extensions][]. The following extensions are
+not enabled by default (see the link for which are enabled by default), so you
+have to switch them on explicitly.
+
+### CodeHilite (recommended)
+
+This extensions uses [Pygments][] (install with `pip install pygments`) to add
+code highlighting to fenced code blocks. It might not be the best code
+highlighter, but it works without JavaScript and on the server:
+
+``` yaml
+markdown_extensions:
+  - codehilite(css_class=code)
+```
+
+If you want more extensive highlighting, you can use a JavaScript library like
+[highlight.js][], which is not included in Material. See [this link][extra] for
+further instructions
+
+### Permalinks
+
+In order to add [permalinks][] to the headers of your article, set the
+`markdown_extensions.toc.permalink` variable to a symbol, e.g. `#`:
+
+``` yaml
+markdown_extensions:
+  - toc:
+    permalink: '#'
+```
+
+The symbol can be chosen freely, it can even be a WebFont icon.
+
+### Admonition
+
+[Admonition][] is a handy extension that adds block-styled side content to your
+documentation, for example hints, notes or warnings. It can be enabled by
+setting the variable `markdown_extensions.admonition`:
+
+``` yaml
+markdown_extensions:
+  - admonition
+```
+
+In order to add a note, use the following syntax inside your article:
+
+``` markdown
+!!! note
+    Nothing to see here, move along.
+```
+
+This will print the following block:
+
+!!! note
+    Nothing to see here, move along.
+
+The Material template adds a neutral color for the `note` class and a red color
+for the `warning` class. You can also add a custom title:
+
+``` markdown
+!!! warning "Don't try this at home"
+    If you do, you will regret it.
+```
+
+This will print:
+
+!!! warning "Don't try this at home"
+    If you do, you will regret it.
+
+More colors can be freely defined.
+
+## Full example
+
+Below is a full example configuration for a mkdocs.yml:
+
+``` yaml
+# Project information
+site_name: 'My Project'
+site_description: 'A short description of my project'
+site_author: 'John Doe'
+site_url: 'https://my-github-handle.github.io/my-project'
+
+# Repository
+repo_name: 'GitHub'
+repo_url: 'https://github.com/my-github-handle/my-project'
+
+# Copyright
+copyright: 'Copyright (c) 2016 John Doe'
+
+# Documentation and theme
+docs_dir: 'docs'
+theme: 'material'
+
+# Options
+extra:
+  version: '0.1.0'
+  logo: 'images/logo.png'
+  palette:
+    primary: 'indigo'
+    accent: 'light blue'
+  font:
+    text: 'Roboto'
+    code: 'Roboto Mono'
+  i18n:
+    prev: 'Previous'
+    next: 'Next'
+  author:
+    github: 'my-github-handle'
+    twitter: 'my-twitter-handle'
+
+# Google Analytics
+google_analytics:
+  - 'UA-XXXXXXXX-X'
+  - 'auto'
+
+# Extensions
+markdown_extensions:
+  - codehilite(css_class=code)
+  - admonition
+  - toc:
+      permalink: '#'
+```
+
+[MkDocs]: http://www.mkdocs.org
+[color palette]: http://www.materialui.co/colors
+[Ubuntu font family]: http://font.ubuntu.com
+[Google Fonts]: https://www.google.com/fonts
+[Roboto font]: https://www.google.com/fonts/specimen/Roboto
+[Markdown extensions]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
+[Pygments]: http://pygments.org
+[highlight.js]: https://highlightjs.org
+[extra]: http://www.mkdocs.org/user-guide/styling-your-docs/#customising-a-theme
+[permalinks]: https://en.wikipedia.org/wiki/Permalink
+[Admonition]: https://pythonhosted.org/Markdown/extensions/admonition.html
\ No newline at end of file
diff --git a/mkdocs-material/docs/images/colors.png b/mkdocs-material/docs/images/colors.png
new file mode 100644
index 00000000..45e4b604
--- /dev/null
+++ b/mkdocs-material/docs/images/colors.png
diff --git a/mkdocs-material/docs/images/logo.png b/mkdocs-material/docs/images/logo.png
new file mode 100644
index 00000000..573aca13
--- /dev/null
+++ b/mkdocs-material/docs/images/logo.png
diff --git a/mkdocs-material/docs/images/screen.png b/mkdocs-material/docs/images/screen.png
new file mode 100644
index 00000000..cb10504b
--- /dev/null
+++ b/mkdocs-material/docs/images/screen.png
diff --git a/mkdocs-material/docs/index.md b/mkdocs-material/docs/index.md
new file mode 100644
index 00000000..9fdad9c4
--- /dev/null
+++ b/mkdocs-material/docs/index.md
@@ -0,0 +1,66 @@
+# Material for MkDocs
+
+## 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][]
+guidelines, full responsive, optimized for touch and pointer devices as well
+as all sorts of screen sizes.
+
+![Material Screenshot](images/screen.png)
+
+Material is very lightweight – it is built from scratch using Javascript and
+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.
+
+## Quick start
+
+Install with `pip`:
+
+``` sh
+pip install mkdocs-material
+```
+
+Add the following line to your `mkdocs.yml`:
+
+``` yaml
+theme: 'material'
+```
+
+## Features
+
+- Beautiful, readable and very user-friendly design based on Google's material
+  design guidelines, packed in a full responsive template with a well-defined
+  and [easily customizable color palette][], great typography, as well as a
+  beautiful search interface and footer.
+
+- Well-tested and optimized Javascript and CSS including a cross-browser
+  fixed/sticky header, a drawer that even works without Javascript using
+  the [checkbox hack][] with fallbacks, responsive tables that scroll when
+  the screen is too small and well-defined print styles.
+
+- Extra configuration options like a [project logo][], links to the authors
+  [GitHub and Twitter accounts][], display of the amount of stars the
+  project has on GitHub and [Google Analytics integration][].
+
+- Easily [extendable and customizable][] due to a well-designed asset pipeline
+  built on-top of [Gulp][] with `npm` and `bower` and modular and abstracted
+  style definitions built with [SASS][].
+
+- Web application capability on iOS – when the page is saved to the homescreen,
+  it behaves and looks like a native application.
+
+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
+[GitHub and Twitter accounts]: getting-started.md#adding-a-github-and-twitter-account
+[Google Analytics integration]: getting-started.md#google-analytics-integration
+[extendable and customizable]: customization.md
+[Gulp]: http://gulpjs.com
+[SASS]: http://sass-lang.com
\ No newline at end of file
diff --git a/mkdocs-material/docs/license.md b/mkdocs-material/docs/license.md
new file mode 100644
index 00000000..27d4332b
--- /dev/null
+++ b/mkdocs-material/docs/license.md
@@ -0,0 +1,23 @@
+# License
+
+**MIT License**
+
+Copyright (c) 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
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
\ No newline at end of file