Prepare release (continue)

bower.json

@@ -1,8 +1,8 @@
 {
-  "name": "mkdocs-material",
+  "name": "Material",
   "version": "0.1.0",
   "description": "A material design theme for MkDocs",
-  "homepage": "https://github.com/squidfunk/mkdocs-material",
+  "homepage": "http://squidfunk.github.io/mkdocs-material/",
   "authors": [
     "squidfunk <martin.donath@squidfunk.com>"
   ],

docs/customization.md

@@ -0,0 +1,86 @@
+# 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 the repository of the project and compile
+the SASS sources with your changes. The project design is very modular, so
+most things can be changed by tweaking a few variables.
+
+### Setup
+
+In order to compile the project, you need `node`, `bower` and `gulp` up and
+running. It's best to use the most recent versions, but it should also work if
+your installations are not too dated. 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`:
+
+``` sh
+cd mkdocs-material
+npm install && bower install
+```
+
+### Development
+
+The asset pipeline is contained in `Gulpfile.js`, which you can start with
+`gulp watch`. 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
+```
+
+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;
+```
+
+### 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` and you should see your documentation with your changes!
+
+[MkDocs]: http://www.mkdocs.org
+[MkDocs documentation]: http://www.mkdocs.org/user-guide/styling-your-docs/#customising-a-theme

docs/getting-started.md

@@ -0,0 +1,223 @@
+# Getting started
+
+## Installation
+
+### Installing MkDocs
+
+In order to install [MkDocs][], Python and `pip` - the Python package manager -
+need to be 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 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. 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'
+```
+
+### 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'
+```
+
+### 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'
+```
+
+### More advanced customization
+
+If you want to change the fonts or colors - you are lucky. The Material theme
+is built with a sophisticated asset pipeline. See
+[this article](/customization) 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 adds 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:
+
+!!! note
+    Nothing to see here, move along.
+
+The Material template adds a light color for the `note` class and a red color
+for the `warning` class. 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://github.com/my-github-handle/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'
+  author:
+    github: 'my-github-handle'
+    twitter: 'my-twitter-handle'
+
+# Extensions
+markdown_extensions:
+  - codehilite(css_class=code)
+  - admonition
+  - toc:
+      permalink: '¶'
+```
+
+[MkDocs]: http://www.mkdocs.org
+[Markdown extensions]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
+[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

docs/index.md

@@ -1 +1,47 @@
-A material design theme for MkDocs.
+# Material for MkDocs
+
+## Beautiful documentation
+
+You're currently looking at a full responsive [MkDocs][] theme in the spirit of
+Google's [material design][] guidelines. MkDocs is an excellent static site
+documentation generator that is meant for building good looking project
+documentation.
+
+![Material Screenshot](/images/screen.png)
+
+This theme is **optimized for all sorts of devices** and is built from scratch
+without any bloated Javascript or CSS Frameworks with **only 24kb of JS and
+CSS** (minified, gzipped and excluding Google WebFonts and Analytics). Yet, it
+is highly customizable in terms of fonts, colors and gracefully supports older
+browsers.
+
+## 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 color palette, great typography, as well as a beautiful
+  search interface and footer.
+
+- Well-tested and **optimized CSS and Javascript**, including a cross-browser
+  fixed/sticky header, a drawer that even works without Javascript using
+  the `checkbox:checked` hack with fallbacks, **responsive tables** that scroll
+  when the screen is too small and **well-defined print styles**.
+
+- Extra configuration options like **project logo**, links to the authors
+  **GitHub and Twitter accounts** and display of the **amount of stars** the
+  project has on GitHub.
+
+- **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) for instructions how to get
+it up and running.
+
+[material design]: https://www.google.com/design/spec/material-design
+[MkDocs]: http://www.mkdocs.org
+[Gulp]: http://gulpjs.com
+[SASS]: http://sass-lang.com/

docs/license.md

@@ -0,0 +1,21 @@
+# 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.

material/base.html

@@ -28,11 +28,15 @@
     <meta name="apple-mobile-web-app-title" content="{{ site_name }}">
     <meta name="apple-mobile-web-app-capable" content="yes">
     <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
-    <link rel="shortcut icon" type="image/x-icon" href="{{ icon | default(base_url + '/assets/images/favicon.ico') }}">
+    {% if config.extra.logo %}
-    <link rel="icon" type="image/x-icon" href="{{ icon | default(base_url + '/assets/images/favicon.ico') }}">
+      <link rel="apple-touch-icon" href="{{ base_url }}/{{ config.extra.logo }}">
+    {% endif %}
+    {% set icon = icon | default('assets/images/favicon-e565ddfa.ico') %}
+    <link rel="shortcut icon" type="image/x-icon" href="{{ base_url }}/{{ icon }}">
+    <link rel="icon" type="image/x-icon" href="{{ base_url }}/{{ icon }}">
     <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Ubuntu:400,700">
     <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Ubuntu+Mono">
-    <link rel="stylesheet" href="{{ base_url }}/assets/stylesheets/application.css">
+    <link rel="stylesheet" href="{{ base_url }}/assets/stylesheets/application-334f02ec.css">
     {% for path in extra_css %}
       <link rel="stylesheet" href="{{ path }}">
     {% endfor %}
@@ -90,13 +94,13 @@
         </div>
       </div>
     </main>
-    <script src="{{ base_url }}/assets/javascripts/modernizr.js"></script>
+    <script src="{{ base_url }}/assets/javascripts/modernizr-79394028.js"></script>
     {% set repo_id = repo_url | replace('https://github.com/', '') %}
     <script>
       var base_url = '{{ base_url }}';
       var repo_id  = '{{ repo_id }}';
     </script>
-    <script src="{{ base_url }}/assets/javascripts/application.js"></script>
+    <script src="{{ base_url }}/assets/javascripts/application-1a680198.js"></script>
     {% for path in extra_javascript %}
       <script src="{{ path }}"></script>
     {% endfor %}

material/drawer.html

@@ -6,7 +6,7 @@
     <div class="banner">
       {% if config.extra.logo %}
         <div class="logo">
-          <img src="{{ config.extra.logo }}">
+          <img src="{{ base_url }}/{{ config.extra.logo }}">
         </div>
       {% endif %}
       <div class="name">

material/manifest.json

@@ -2,5 +2,5 @@
   "assets/images/favicon.ico": "assets/images/favicon-e565ddfa.ico",
   "assets/javascripts/application.js": "assets/javascripts/application-1a680198.js",
   "assets/javascripts/modernizr.js": "assets/javascripts/modernizr-79394028.js",
-  "assets/stylesheets/application.css": "assets/stylesheets/application-9ec7095f.css"
+  "assets/stylesheets/application.css": "assets/stylesheets/application-334f02ec.css"
 }

mkdocs.yml

@@ -19,10 +19,10 @@
 # IN THE SOFTWARE.
 
 # Project information
-site_name: mkdocs-material
+site_name: Material
 site_description: A material design theme for MkDocs
 site_author: Martin Donath
-site_url: https://github.com/squidfunk/mkdocs-material
+site_url: http://squidfunk.github.io/mkdocs-material/
 
 # Repository
 repo_name: GitHub
@@ -33,19 +33,17 @@ copyright: Copyright (c) 2016 Martin Donath
 
 # Documentation and theme
 theme_dir: material
-theme: amelia
 
-# Extra variables
+# Options
 extra:
   version: 0.1.0
-  logo:
+  logo: images/logo.png
   author:
     github: squidfunk
     twitter: squidfunk
 
 # Extensions
 markdown_extensions:
-  - fenced_code
   - codehilite(css_class=code)
   - admonition
   - toc:
@@ -53,4 +51,7 @@ markdown_extensions:
 
 # Page tree
 pages:
-- Home: index.md
+  - Material: index.md
+  - Getting started: getting-started.md
+  - Customization: customization.md
+  - License: license.md

package.json

@@ -1,8 +1,8 @@
 {
-  "name": "mkdocs-material",
+  "name": "Material",
   "version": "0.1.0",
   "description": "A material design theme for MkDocs",
-  "homepage": "https://github.com/squidfunk/mkdocs-material",
+  "homepage": "http://squidfunk.github.io/mkdocs-material/",
   "authors": [
     "squidfunk <martin.donath@squidfunk.com>"
   ],

src/assets/stylesheets/_palette.scss

@@ -27,8 +27,8 @@
 /*
  * Primary and accent color
  */
-$primary: $indigo-500 !default;
+$primary: $red-400   !default;
-$accent:  $teal-500   !default;
+$accent:  $teal-a700 !default;
 
 /*
  * Black opacities

src/assets/stylesheets/fonts/_icon.scss

@@ -24,16 +24,22 @@
  * Font faces
  * ------------------------------------------------------------------------- */
 
+/*
+ * Base URL and path for icon font.
+ */
+$base: '../..';
+$path: $base + '/assets/fonts/';
+
 /*
  * Icon font
  */
 @font-face {
 	font-family: 'Icon';
-	src: url('/assets/fonts/icon.eot?52m981');
+	src: url($path + 'icon.eot?52m981');
-	src: url('/assets/fonts/icon.eot?#iefix52m981') format('embedded-opentype'),
+	src: url($path + 'icon.eot?#iefix52m981') format('embedded-opentype'),
-		   url('/assets/fonts/icon.woff?52m981') format('woff'),
+		   url($path + 'icon.woff?52m981') format('woff'),
-		   url('/assets/fonts/icon.ttf?52m981') format('truetype'),
+		   url($path + 'icon.ttf?52m981') format('truetype'),
-		   url('/assets/fonts/icon.svg?52m981#icon') format('svg');
+		   url($path + 'icon.svg?52m981#icon') format('svg');
 	font-weight: normal;
 	font-style: normal;
 }

src/assets/stylesheets/modules/article/_appearance.scss

@@ -152,7 +152,7 @@
  * Admonition support
  */
 .admonition {
-  background: mix($primary, $white, 10%);
+  background: mix($light-blue-500, $white, 10%);
 
   /*
    * Embedded code blocks

src/assets/stylesheets/modules/article/_layout.scss

@@ -30,7 +30,6 @@
 .article {
   font-size: 14px;
   line-height: 1.7em;
-  overflow-x: hidden;
 
   /* [tablet landscape+]: Indent to account for drawer */
   @include break-from-device(tablet landscape) {
@@ -154,7 +153,8 @@
    */
   ul li:before {
     content: "\e602";
-    display: inline-block;
+    display: block;
+    float: left;
     font-family: 'Icon';
     font-size: 16px;
     width: 1.2em;
@@ -333,7 +333,7 @@
  * Copyright and theme information
  */
 .copyright {
-  margin: 20px 0;
+  margin: 1.5em 0;
 
   /* [tablet landscape+]: Add bottom spacing */
   @include break-from-device(tablet landscape) {

src/base.html

@@ -45,11 +45,18 @@
     <meta name="apple-mobile-web-app-status-bar-style"
       content="black-translucent" />
 
+    <!-- Web application icon on iOS -->
+    {% if config.extra.logo %}
+      <link rel="apple-touch-icon"
+        href="{{ base_url }}/{{ config.extra.logo }}">
+    {% endif %}
+
     <!-- Favicon -->
+    {% set icon = icon | default('assets/images/favicon.ico') %}
     <link rel="shortcut icon" type="image/x-icon"
-      href="{{ icon | default(base_url + '/assets/images/favicon.ico') }}" />
+      href="{{ base_url }}/{{ icon }}" />
     <link rel="icon" type="image/x-icon"
-      href="{{ icon | default(base_url + '/assets/images/favicon.ico') }}" />
+      href="{{ base_url }}/{{ icon }}" />
 
     <!-- Webfonts -->
     <link rel="stylesheet" type="text/css"

src/drawer.html

@@ -14,7 +14,7 @@
       <!-- Version -->
       {% if config.extra.logo %}
         <div class="logo">
-          <img src="{{ config.extra.logo }}" />
+          <img src="{{ base_url }}/{{ config.extra.logo }}" />
         </div>
       {% endif %}