Updated documentation

.gitignore

@@ -18,7 +18,7 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
-# Mac OS X internals
+# macOS internals
 .DS_Store
 
 # NPM-related

CHANGELOG

@@ -7,7 +7,7 @@ mkdocs-material-1.0.0 (2017-01-13)
   * Introduced git-hooks for better development workflow
   * Rewrite of CSS using the BEM methodology and SassDoc guidelines
   * Rewrite of JavaScript using ES6 and Babel as a transpiler
-  * Rewrite of Admonition, Permalinks and Codehilite integration
+  * Rewrite of Admonition, Permalinks and CodeHilite integration
   * Rewrite of the complete typographical system
   * Rewrite of Gulp asset pipeline in ES6 and separation of tasks
   * Removed Bower as a dependency in favor of NPM

README.md

@@ -4,7 +4,7 @@
 [![Codacy][codacy-image]][codacy-link]
 [![PyPI][pypi-image]][pypi-link]
 
-A material design theme for [MkDocs](http://www.mkdocs.org).
+A Material Design theme for [MkDocs](http://www.mkdocs.org).
 
 TBD: [![_](docs/images/screen.png)](http://squidfunk.github.io/mkdocs-material/)
 

docs/contributing.md

@@ -30,12 +30,12 @@ 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
+* 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
+* **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.

docs/customization.md

@@ -35,7 +35,7 @@ extra_css:
 
 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?
+saving, as the MkDocs development server implements live reloading.
 
 ### Additional JavaScript
 

docs/extensions/admonition.md

@@ -34,6 +34,7 @@ Example:
 Result:
 
 !!! note
+
     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.
@@ -42,8 +43,8 @@ Result:
 
 ### Changing the title
 
-By default, the block title will equal the type qualifier. However, it can
+By default, the block title will equal the type qualifier in titlecase. However,
-easily be changed by adding a quoted string after the type qualifier.
+it can easily be changed by adding a quoted string after the type qualifier.
 
 Example:
 
@@ -57,6 +58,7 @@ Example:
 Result:
 
 !!! note "Phasellus posuere in sem ut cursus"
+
     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.
@@ -78,6 +80,7 @@ Example:
 Result:
 
 !!! note ""
+
     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.
@@ -100,6 +103,7 @@ blocks.
 Example:
 
 !!! note
+
     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.
@@ -147,6 +151,7 @@ Example:
 Result:
 
 !!! note
+
     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.
@@ -170,6 +175,7 @@ Example:
 Result:
 
 !!! summary
+
     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.
@@ -193,6 +199,7 @@ Example:
 Result:
 
 !!! tip
+
     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.
@@ -217,6 +224,7 @@ Example:
 Result:
 
 !!! success
+
     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.
@@ -241,6 +249,7 @@ Example:
 Result:
 
 !!! warning
+
     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.
@@ -265,6 +274,7 @@ Example:
 Result:
 
 !!! failure
+
     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.
@@ -289,6 +299,7 @@ Example:
 Result:
 
 !!! danger
+
     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.
@@ -312,6 +323,7 @@ Example:
 Result:
 
 !!! bug
+
     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.

docs/extensions/codehilite.md

@@ -1,7 +1,7 @@
 # CodeHilite
 
-[CodeHilite][1] is an extension that adds syntax highlighting to codeblocks and
+[CodeHilite][1] is an extension that adds syntax highlighting to code blocks
-is included in the standard Markdown library. The highlighting process is
+and is included in the standard Markdown library. The highlighting process is
 executed during compilation of the Markdown file.
 
   [1]: https://pythonhosted.org/Markdown/extensions/code_hilite.html
@@ -621,7 +621,7 @@ module.exports = _extends(exports['default'], exports);
 {
   "name": "mkdocs-material",
   "version": "0.2.4",
-  "description": "A material design theme for MkDocs",
+  "description": "A Material Design theme for MkDocs",
   "homepage": "http://squidfunk.github.io/mkdocs-material/",
   "authors": [
     "squidfunk <martin.donath@squidfunk.com>"

docs/extensions/footnotes.md

@@ -39,7 +39,7 @@ Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
 
 ### Inserting the content
 
-The footnote content is also initiated with a label, which must match the label
+The footnote content is also declared with a label, which must match the label
 used for the footnote reference. It can be inserted at an arbitrary position in
 the document and is always rendered at the bottom of the page. Furthermore, a
 backlink is automatically added to the footnote reference.

docs/extensions/pymdown.md

@@ -45,7 +45,7 @@ the Markdown experience closer to GitHub Flavored Markdown (GFM).
 The PyMdown Extensions package adds a shorthand to enable all of the included
 extensions that provide the GFM experience. However, usage of the shorthand is
 discouraged, because some extensions are not supported, as the Material theme
-uses the counterparts included in the standard Markdown library.
+uses some incompatible extensions included in the standard Markdown library.
 
 #### BetterEm
 
@@ -132,7 +132,7 @@ Result:
 
 [Tilde][13] provides an easy way to ~~strike through~~ cross out text.
 The portion of text that should be erased must be enclosed in two tildes
-`~~...~~`, and the extension will take care of the rest.
+`~~...~~` and the extension will take care of the rest.
 
   [13]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
 
@@ -171,13 +171,13 @@ During compilation of the Markdown document, changes can be rendered (default),
 accepted or rejected.
 
 Text can be {--deleted--} and replacement text {++added++}. This can also be
-combined in {~~one~>a single~~} operation. {==Highlighting==} is also possible
+combined into {~~one~>a single~~} operation. {==Highlighting==} is also
-{>>and comments can be added inline<<}.
+possible {>>and comments can be added inline<<}.
 
 {==
 
-This can also be applied to blocks, by putting the opening and closing tags on
+Formatting can also be applied to blocks, by putting the opening and closing
-separate lines and adding a new line between the tag and the content each.
+tags on separate lines and adding new lines between the tags and the content.
 
 ==}
 
@@ -194,7 +194,7 @@ mathematical notation. See [this thread][22] for a short introduction and quick
 reference on how to write equations in TeX syntax.
 
 Besides activating the extension in the `mkdocs.yml`, the MathJax JavaScript
-runtime needs to be included. This can be done with
+runtime needs to be included. This must be done with
 [additional JavaScript][23]:
 
 ``` yaml
@@ -233,7 +233,7 @@ In your `mkdocs.yml`, include it with:
 
 ``` yaml
 extra_javascript:
-  - 'extra.js'
+  - 'javascripts/extra.js'
   - 'https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML'
 ```
 

docs/getting-started.md

@@ -4,7 +4,7 @@
 
 ### Installing MkDocs
 
-Before installing [MkDocs][1], you need to make sure you have Python and `pip`
+Before installing [MkDocs][2], you need to make sure you have Python and `pip`
 – the Python package manager – up and running. You can verify if you're already
 good to go with the following commands:
 
@@ -26,17 +26,18 @@ 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][3] and the
-[PyMdown Extensions][3] to get the most out of the Material theme:
+[PyMdown Extensions][4] to get the most out of the Material theme:
 
 ```sh
 pip install pygments
 pip install pymdown-extensions
 ```
 
-  [1]: http://www.mkdocs.org
+  [1]: https://hub.docker.com/r/squidfunk/mkdocs-material/
-  [2]: http://pygments.org
+  [2]: http://www.mkdocs.org
-  [3]: http://facelessuser.github.io/pymdown-extensions/
+  [3]: http://pygments.org
+  [4]: http://facelessuser.github.io/pymdown-extensions/
 
 ### Installing Material
 
@@ -48,11 +49,11 @@ Material can be installed with `pip`:
 pip install mkdocs-material
 ```
 
-!!! warning "Installation on Mac OS X"
+!!! warning "Installation on macOS"
 
-    When you're running the pre-installed version of Python on OS X, `pip` tries
+    When you're running the pre-installed version of Python on macOS, `pip`
-    to install packages in a folder for which your user might not have the
+    tries to install packages in a folder for which your user might not have
-    adequate permissions. There are two possible solutions to this:
+    the adequate permissions. There are two possible solutions to this:
 
     1. **Installing in user space** (recommended): Provide the `--user` flag
       to the install command and `pip` will install the package in a user-site
@@ -60,11 +61,11 @@ pip install mkdocs-material
 
     2. **Switching to a homebrewed Python**: Upgrade your Python installation
       to a self-contained solution by installing Python with Homebrew. This
-      will also eliminate any problems you may be having with `pip`.
+      should eliminate a lot of problems you may be having with `pip`.
 
 #### by cloning from GitHub
 
-Material can also be used without system-wide installation by cloning the
+Material can also be used without a system-wide installation by cloning the
 repository into a subfolder of your project's root directory:
 
 ``` sh
@@ -84,24 +85,24 @@ your `mkdocs.yml`. If you installed Material using pip:
 theme: 'material'
 ```
 
-When you cloned Material from GitHub, use:
+If you cloned Material from GitHub:
 
 ``` yaml
 theme_dir: 'mkdocs-material/material'
 ```
 
-That's it. MkDocs includes a development server, so you can view your changes
+MkDocs includes a development server, so you can view your changes as you go.
-as you go - very handy. Spin it up with the following command:
+The development server can be started with the following command:
 
 ``` sh
 mkdocs serve
 ```
 
-Now you can point your browser to [localhost:8000][4] and the Material theme
+Now you can point your browser to [localhost:8000][5] and the Material theme
-should be visible. You can now start writing your documentation, or read on and
+should be visible. From here on, you can start writing your documentation, or
-customize the theme through some options.
+read on and customize the theme through some options.
 
-  [4]: http://localhost:8000
+  [5]: http://localhost:8000
 
 ## Options
 
@@ -111,7 +112,7 @@ project's `mkdocs.yml`. See the following section for all available options.
 ### Changing the color palette
 
 Material defines a default hue for every primary and accent color on Google's
-material design [color palette][5]. This makes it very easy to change the
+Material Design [color palette][6]. This makes it very easy to change the
 overall look of the theme. Just set the primary and accent colors using the
 following variables in your `mkdocs.yml`:
 
@@ -122,19 +123,19 @@ extra:
     accent: 'light blue'
 ```
 
-Color names can be written upper- or lowercase but must match the names of the
+Color names are case-insensitive, but must match the names of the Material
-material design color palette. Valid values are: `red`, `pink`, `purple`,
+Design color palette. Valid values are: `red`, `pink`, `purple`, `deep purple`,
-`deep purple`, `indigo`, `blue`, `light blue`, `cyan`, `teal`, `green`, `light
+`indigo`, `blue`, `light blue`, `cyan`, `teal`, `green`, `light green`, `lime`,
-green`, `lime`, `yellow`, `amber`, `orange`, `deep orange`, `brown`, `grey` and
+`yellow`, `amber`, `orange`, `deep orange`, `brown`, `grey` and `blue grey`.
-`blue grey`. The last three colors can only be used as a primary color.
+The last three colors can only be used as a primary color.
 
 If the color is set via this configuration, an additional CSS file that
 defines the color palette is included. If you want to keep things lean, clone
-the repository and recompile the theme with your custom colors set. See
+the repository and recompile the theme with your custom colors set. See the
-[this article][6] for more information.
+guide on [customization][7] for more information.
 
-  [5]: http://www.materialui.co/colors
+  [6]: http://www.materialui.co/colors
-  [6]: customization.md
+  [7]: customization.md
 
 #### Primary colors
 
@@ -201,10 +202,10 @@ Click on a tile to change the accent color of the theme:
 
 ### Changing the font family
 
-Material uses the [Roboto font family][7] by default, specifically the regular
+Material uses the [Roboto font family][8] by default, specifically the regular
 sans-serif type for text and the `monospaced` type for code. Both fonts are
-loaded from [Google Fonts][8] and can easily be changed to other fonts, like
+loaded from [Google Fonts][9] and can easily be changed to other fonts, like
-for example the [Ubuntu font family][9]:
+for example the [Ubuntu font family][10]:
 
 ``` yaml
 extra:
@@ -222,9 +223,9 @@ extra:
   font: 'none'
 ```
 
-  [7]: https://fonts.google.com/specimen/Roboto
+  [8]: https://fonts.google.com/specimen/Roboto
-  [8]: https://fonts.google.com/
+  [9]: https://fonts.google.com/
-  [9]: https://fonts.google.com/specimen/Ubuntu
+  [10]: https://fonts.google.com/specimen/Ubuntu
 
 ### Adding a logo
 
@@ -243,9 +244,9 @@ extra:
 
 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 [FontAwesome][10] webfont. The syntax is simple – the `type` denotes
+included [FontAwesome][11] webfont. The syntax is simple – the `type` must
-the name of the social service, e.g. `github`, `twitter` or `linkedin` and
+denote the name of the social service, e.g. `github`, `twitter` or `linkedin`
-the `link`, well, resembles the link:
+and the `link` must contain the URL you want to link to:
 
 ``` yaml
 extra:
@@ -258,11 +259,11 @@ extra:
       link: 'https://de.linkedin.com/in/martin-donath-20a95039'
 ```
 
-The links are generated in order and the type of the link must match the name
+The links are generated in order and the `type` of the links must match the
-of the FontAwesome glyph. The `fa` is automatically added, so `github` will
+name of the FontAwesome glyph. The `fa` is automatically added, so `github`
-result in `fa fa-github`.
+will result in `fa fa-github`.
 
-  [10]: http://fontawesome.io/icons/
+  [11]: http://fontawesome.io/icons/
 
 ### Google Analytics integration
 
@@ -295,7 +296,7 @@ inside the macro `t`:
 ```
 
 Just copy the file from the original theme and make your adjustments. See the
-section on [overriding partials][11] in the customization guide.
+section on [overriding partials][12] in the customization guide.
 
 !!! warning "Migrating from Material 0.2.x"
 
@@ -303,18 +304,18 @@ section on [overriding partials][11] in the customization guide.
     `mkdocs.yml`. With 1.0.0 this is no longer possible as the configuration
     will be ignored.
 
-  [11]: customization.md#overriding-partials
+  [12]: customization.md#overriding-partials
 
 ### More advanced customization
 
 If you want to change the general appearance of the Material theme, see
-[this article][12] for more information on advanced customization.
+[this article][13] for more information on advanced customization.
 
-  [12]: customization.md
+  [13]: customization.md
 
 ## Extensions
 
-MkDocs supports several [Markdown extensions][13]. The following extensions
+MkDocs supports several [Markdown extensions][14]. The following extensions
 are not enabled by default (see the link for which are enabled by default)
 but highly recommended, so they should be switched on at all times:
 
@@ -328,18 +329,18 @@ markdown_extensions:
 For more information, see the following list of extensions supported by the
 Material theme including more information regarding installation and usage:
 
-* [Admonition][14]
+* [Admonition][15]
-* [Codehilite][15]
+* [Codehilite][16]
-* [Permalinks][16]
+* [Permalinks][17]
-* [Footnotes][17]
+* [Footnotes][18]
-* [PyMdown Extensions][18]
+* [PyMdown Extensions][19]
 
-  [13]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
+  [14]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
-  [14]: extensions/admonition.md
+  [15]: extensions/admonition.md
-  [15]: extensions/codehilite.md
+  [16]: extensions/codehilite.md
-  [16]: extensions/permalinks.md
+  [17]: extensions/permalinks.md
-  [17]: extensions/footnotes.md
+  [18]: extensions/footnotes.md
-  [18]: extensions/pymdown.md
+  [19]: extensions/pymdown.md
 
 ## Full example
 

docs/index.md

@@ -1,15 +1,10 @@
 # Material <small>for MkDocs</small>
 
-## Build beautiful documentation
+## Beautiful project documentation
 
 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, fully responsive and optimized for touch and pointer devices.
+guidelines.
-
-Material is very lightweight – it is built from scratch using Javascript and
-CSS that weighs approximately 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
@@ -31,31 +26,3 @@ theme: 'material'
 For detailed instructions see the [getting started guide][3].
 
   [3]: getting-started.md
-
-## 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][4], great typography, as well as a
-  beautiful search interface.
-
-* Responsive specimen like code blocks, tables that work on all screen sizes,
-  working with and without JavaScript which makes it gracefully degrade in
-  older browsers.
-
-- Extra configuration options like a [project logo][5], links to
-  [social accounts][6], display of the amount of stars your project has on
-  GitHub and [Google Analytics integration][7].
-
-- Easily [extendable and customizable][8] due to a well-designed asset pipeline
-  built on-top of modern web technologies and modular and abstracted
-  style definitions..
-
-- Web application capability on iOS – when the page is saved to the homescreen,
-  it behaves and looks like a native application.
-
-  [4]: getting-started.md#changing-the-color-palette
-  [5]: getting-started.md#adding-a-logo
-  [6]: getting-started.md#adding-social-links
-  [7]: getting-started.md#google-analytics-integration
-  [8]: customization.md

docs/release-notes.md

@@ -26,7 +26,7 @@ pip show mkdocs-material | grep -E ^Version
 * Introduced git-hooks for better development workflow
 * Rewrite of CSS using the BEM methodology and SassDoc guidelines
 * Rewrite of JavaScript using ES6 and Babel as a transpiler
-* Rewrite of Admonition, Permalinks and Codehilite integration
+* Rewrite of Admonition, Permalinks and CodeHilite integration
 * Rewrite of the complete typographical system
 * Rewrite of Gulp asset pipeline in ES6 and separation of tasks
 * Removed Bower as a dependency in favor of NPM

mkdocs.yml

@@ -20,7 +20,7 @@
 
 # Project information
 site_name: Material for MkDocs
-site_description: A material design theme for MkDocs
+site_description: A Material Design theme for MkDocs
 site_author: Martin Donath
 site_url: http://squidfunk.github.io/mkdocs-material/
 
@@ -39,9 +39,6 @@ extra:
   palette:
     primary: indigo
     accent: indigo
-  font:
-    text: Roboto
-    mono: Roboto Mono
   social:
     - type: github-alt
       link: https://github.com/squidfunk

package.json

@@ -1,7 +1,7 @@
 {
   "name": "mkdocs-material",
   "version": "1.0.0",
-  "description": "A material design theme for MkDocs",
+  "description": "A Material Design theme for MkDocs",
   "keywords": [
     "mkdocs",
     "documentation",

setup.py

@@ -26,7 +26,7 @@ setup(
     version = "1.0.0",
     url = "http://squidfunk.github.io/mkdocs-material/",
     license = "MIT",
-    description = "A material design theme for MkDocs",
+    description = "A Material Design theme for MkDocs",
     author = "Martin Donath",
     author_email = "martin.donath@squidfunk.com",
     keywords = ["mkdocs", "documentation", "theme"],