Updated documentation

README.md

@@ -28,6 +28,7 @@ http://squidfunk.github.io/mkdocs-material/
 ## License
 
 **MIT License**
+
 Copyright (c) 2016 Martin Donath
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

docs/customization.md

@@ -26,23 +26,28 @@ Further assistance on including extra CSS and Javascript can be found in the
 ## 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.
+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`, `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:
+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`:
+`package.json` and `bower.json` with the following command:
 
 ``` sh
 cd mkdocs-material
@@ -52,12 +57,12 @@ 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.
+`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
+gulp watch --mkdocs
 ```
 
 For example, changing the color palette is as simple as changing the `$primary`
@@ -80,11 +85,18 @@ When you finished making your changes, you can build the theme by invoking:
 gulp build --production
 ```
 
-The `production` flag triggers the production-level compilation and
+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.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

docs/getting-started.md

@@ -4,7 +4,7 @@
 
 ### Installing MkDocs
 
-In order to install [MkDocs][], Python and `pip` - the Python package manager -
+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
@@ -76,27 +76,54 @@ on and customize the theme through some 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. 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:
+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'
 ```
 
-### Adding a version
+### Changing the font family
 
-In order to add the current version next to the project banner inside the
-drawer, you can set the variable `extra.version`:
+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:
-  version: '0.1.0'
+  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'
 ```
 
 ### Adding a GitHub and Twitter account
@@ -114,9 +141,8 @@ extra:
 
 ### 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.md) for more information on advanced
+If you want to change the colors or general appearance of the Material theme,
+see [this article](customization.md) for more information on advanced
 customization.
 
 ## Extensions
@@ -170,7 +196,7 @@ In order to add a note, use the following syntax inside your article:
     Nothing to see here, move along.
 ```
 
-This will print the following:
+This will print the following block:
 
 !!! note
     Nothing to see here, move along.
@@ -209,6 +235,9 @@ theme: 'material'
 extra:
   version: '0.1.0'
   logo: 'images/logo.png'
+  font:
+    text: 'Roboto'
+    code: 'Roboto Mono'
   author:
     github: 'my-github-handle'
     twitter: 'my-twitter-handle'
@@ -222,8 +251,11 @@ markdown_extensions:
 ```
 
 [MkDocs]: http://www.mkdocs.org
+[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
-[highlight.js]: https://highlightjs.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

docs/index.md

@@ -2,46 +2,49 @@
 
 ## 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 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)
 
-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
+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.
 
 ## 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.
+- 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
+- Well-tested and optimized Javascript and CSS including a cross-browser
   fixed/sticky header, a drawer that even works without Javascript using
-  the `:checked` hack with fallbacks, **responsive tables** that scroll when
-  the screen is too small and **well-defined print styles**.
+  the [checkbox 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
+- Extra configuration options like a [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
+- 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.
+- 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.
 
-[material design]: https://www.google.com/design/spec/material-design
 [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
+[GitHub and Twitter accounts]: getting-started.md#adding-a-github-and-twitter-account
+[extendable and customizable]: customization.md
 [Gulp]: http://gulpjs.com
-[SASS]: http://sass-lang.com/
\ No newline at end of file
+[SASS]: http://sass-lang.com
\ No newline at end of file

docs/license.md

 # License
 
 **MIT License**
+
 Copyright (c) 2016 Martin Donath
 
 Permission is hereby granted, free of charge, to any person obtaining a copy

material/base.html

@@ -63,7 +63,7 @@
       {% if config.extra.font and config.extra.font.code %}
         {% set code = config.extra.font.code %}
       {% endif %}
-      {% set font = text + ':400,700|' + code | replace('+', ' ') %}
+      {% set font = text + ':400,700|' + code | replace(' ', '+') %}
       <link rel="stylesheet" href="//fonts.googleapis.com/css?family={{ font }}">
       <style>
         body, input {

src/base.html

@@ -96,7 +96,7 @@
       {% if config.extra.font and config.extra.font.code %}
         {% set code = config.extra.font.code %}
       {% endif %}
-      {% set font = text + ':400,700|' + code | replace('+', ' ') %}
+      {% set font = text + ':400,700|' + code | replace(' ', '+') %}
       <link rel="stylesheet" type="text/css"
         href="//fonts.googleapis.com/css?family={{ font }}" />
       <style>