From 1248237d603405b596a8a436821e629e6e54174c Mon Sep 17 00:00:00 2001
From: squidfunk <scifish@gmail.com>
Date: Thu, 29 Dec 2016 17:55:08 +0100
Subject: [PATCH] Updated getting started guide [ci skip]

---
 docs/getting-started.md | 375 +++++++++++++++++++++-------------------
 1 file changed, 197 insertions(+), 178 deletions(-)

diff --git a/docs/getting-started.md b/docs/getting-started.md
index ca5bc007f..e58a91067 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -12,111 +12,113 @@ base_url: http://example.com
 
 ### 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
+Before installing [MkDocs][1], 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:
 
 ``` sh
 python --version
-# Python 2.7.2
+# Python 2.7.13
 pip --version
-# pip 1.5.2
+# pip 9.0.1
 ```
 
 Installing and verifying MkDocs is as simple as:
 
 ``` sh
 pip install mkdocs && mkdocs --version
-# mkdocs, version 0.15.2
+# mkdocs, version 0.16.0
 ```
 
+!!! warning "MkDocs for Material requirements"
+
+    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:
+
+```sh
+pip install pygments
+pip install pymdown-extensions
+```
+
+  [1]: http://www.mkdocs.org
+  [2]: http://pygments.org
+  [3]: http://facelessuser.github.io/pymdown-extensions/
+
 ### Installing Material
 
-Next, assuming you have MkDocs up and running `mkdocs-material` can be
-installed with `pip`:
+#### by using pip
+
+Material can be installed with `pip`:
 
 ``` sh
 pip install mkdocs-material
 ```
 
-## Usage
+!!! warning "Installation on Mac OS X"
 
-If you haven't already done it, creating a new documentation project is really
-simple in MkDocs:
+    When you're running the pre-installed version of Python on OS X, `pip` tries
+    to install packages in a folder for which your user might not have 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
+      location. This is the recommended way.
+
+    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`.
+
+#### by cloning from GitHub
+
+Material can also be used without system-wide installation by cloning the
+repository into a subfolder of your project's root directory:
 
 ``` sh
-mkdocs new my-project
-cd my-project
+git clone https://github.com/squidfunk/mkdocs-material.git
 ```
 
-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`:
+This is especially useful if you want to extend the theme and use partials.
+The theme will reside in the folder `mkdocs-material/material`.
+
+## Usage
+
+In order to enable the Material theme just add one of the following lines to
+your `mkdocs.yml`. If you installed Material using pip:
 
 ``` 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:
+When you cloned Material from GitHub, use:
 
 ``` yaml
-repo_name: 'GitHub'
-repo_url: 'https://github.com/my-github-handle/my-project'
+theme_dir: 'mkdocs-material/material'
 ```
 
-MkDocs includes a development server, so you can view your changes as you go -
-very handy. Spin it up with the following command:
+That's it. 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.
+Now you can point your browser 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'
-```
-
 ### 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:
+material design [color palette][4]. 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`:
 
 ``` yaml
 extra:
@@ -126,71 +128,150 @@ extra:
 ```
 
 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 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.
 
-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.
+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 [this
+article](customization.md) for more information.
+
+  [4]: http://www.materialui.co/colors
+
+#### Primary colors
+
+Click on a tile to change the primary color of the theme:
+
+<button data-md-color-primary="red">Red</button>
+<button data-md-color-primary="pink">Pink</button>
+<button data-md-color-primary="purple">Purple</button>
+<button data-md-color-primary="deep-purple">Deep Purple</button>
+<button data-md-color-primary="indigo">Indigo</button>
+<button data-md-color-primary="blue">Blue</button>
+<button data-md-color-primary="light-blue">Light Blue</button>
+<button data-md-color-primary="cyan">Cyan</button>
+<button data-md-color-primary="teal">Teal</button>
+<button data-md-color-primary="green">Green</button>
+<button data-md-color-primary="light-green">Light Green</button>
+<button data-md-color-primary="lime">Lime</button>
+<button data-md-color-primary="yellow">Yellow</button>
+<button data-md-color-primary="amber">Amber</button>
+<button data-md-color-primary="orange">Orange</button>
+<button data-md-color-primary="deep-orange">Deep Orange</button>
+<button data-md-color-primary="brown">Brown</button>
+<button data-md-color-primary="grey">Grey</button>
+<button data-md-color-primary="blue-grey">Blue Grey</button>
+
+<script>
+  var buttons = document.querySelectorAll("button[data-md-color-primary]");
+  Array.prototype.forEach.call(buttons, function(button) {
+    button.addEventListener("click", function() {
+      document.body.dataset.mdColorPrimary = this.dataset.mdColorPrimary;
+    })
+  })
+</script>
+
+#### Accent colors
+
+Click on a tile to change the accent color of the theme:
+
+<button data-md-color-accent="red">Red</button>
+<button data-md-color-accent="pink">Pink</button>
+<button data-md-color-accent="purple">Purple</button>
+<button data-md-color-accent="deep-purple">Deep Purple</button>
+<button data-md-color-accent="indigo">Indigo</button>
+<button data-md-color-accent="blue">Blue</button>
+<button data-md-color-accent="light-blue">Light Blue</button>
+<button data-md-color-accent="cyan">Cyan</button>
+<button data-md-color-accent="teal">Teal</button>
+<button data-md-color-accent="green">Green</button>
+<button data-md-color-accent="light-green">Light Green</button>
+<button data-md-color-accent="lime">Lime</button>
+<button data-md-color-accent="yellow">Yellow</button>
+<button data-md-color-accent="amber">Amber</button>
+<button data-md-color-accent="orange">Orange</button>
+<button data-md-color-accent="deep-orange">Deep Orange</button>
+
+<script>
+  var buttons = document.querySelectorAll("button[data-md-color-accent]");
+  Array.prototype.forEach.call(buttons, function(button) {
+    button.addEventListener("click", function() {
+      document.body.dataset.mdColorAccent = this.dataset.mdColorAccent;
+    })
+  })
+</script>
 
 ### Changing the font family
 
-Material uses the [Ubuntu font family][] by default, specifically the regular
+Material uses the [Roboto font family][5] 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][]:
+loaded from [Google Fonts][6] and can easily be changed to other fonts, like
+for example the [Ubuntu font family][7]:
 
 ``` yaml
 extra:
   font:
-    text: 'Roboto'
-    code: 'Roboto Mono'
+    text: 'Ubuntu'
+    code: 'Ubuntu 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'`:
+don't want to use the Google Fonts loading magic, just set `font` to `'none'`:
 
 ``` yaml
 extra:
   font: 'none'
 ```
 
-### Localization
+  [5]: https://fonts.google.com/specimen/Roboto
+  [6]: https://fonts.google.com/
+  [7]: https://fonts.google.com/specimen/Ubuntu
 
-The **Previous** and **Next** labels in the footer can easily be changed by
-defining the variables `extra.i18n.prev` and `extra.i18n.next`:
+### Adding a logo
+
+Material makes it easy to add your logo. Your logo should have rectangular
+shape with a minimum resolution of 128x128, leave some room towards the edges
+and be composed of high contrast areas on a transparent ground, as it will be
+placed on the colored header bar and drawer. Simply create the folder
+`docs/images`, add your logo and embed it with:
 
 ``` yaml
 extra:
-  i18n:
-    prev: 'Previous'
-    next: 'Next'
+  logo: 'images/logo.svg'
 ```
 
-### Adding a GitHub and Twitter account
+### Adding social links
 
-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:
+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:
 
 ``` yaml
 extra:
-  author:
-    github: 'my-github-handle'
-    twitter: 'my-twitter-handle'
+  social:
+    - type: 'github'
+      link: 'https://github.com/squidfunk'
+    - type: 'twitter'
+      link: 'https://twitter.com/squidfunk'
+    - type: 'linkedin'
+      link: 'https://de.linkedin.com/in/martin-donath-20a95039'
 ```
 
+The links are generated in order.
+
+  [8]: http://www.socicon.com/chart.php
+
 ### 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`:
+MkDocs makes it easy to integrate site tracking with Google Analytics.
+Besides basic tracking, clicks on all outgoing links can be tracked as well as
+how site search is used. Tracking can be activated in your project's
+`mkdocs.yml`:
 
 ``` yaml
 google_analytics:
@@ -205,78 +286,27 @@ If you want to change the general appearance of the Material theme, see
 
 ## 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 <small>recommended</small>
-
-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
-```
-
-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 <small>recommended</small>
-
-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`:
+MkDocs supports several [Markdown extensions][9]. 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:
 
 ``` yaml
 markdown_extensions:
   - admonition
+  - codehilite(guess_lang=false)
+  - toc(permalink=true)
 ```
 
-In order to add a note, use the following syntax inside your article:
+For more information, see the following list of extensions supported by the
+Material theme including more information regarding installation and usage:
 
-``` markdown
-!!! note
-    Nothing to see here, move along.
-```
+* [Admonition](extensions/admonition.md)
+* [Codehilite](extensions/codehilite.md)
+* [Permalinks](extensions/permalinks.md)
+* [Footnotes](extensions/footnotes.md)
+* [PyMdown Extensions](extensions/pymdown.md)
 
-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
-    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.
-```
-
-This will print:
-
-!!! warning
-    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.
-
-More colors can be freely defined.
+  [9]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
 
 ## Full example
 
@@ -294,28 +324,27 @@ repo_name: 'GitHub'
 repo_url: 'https://github.com/my-github-handle/my-project'
 
 # Copyright
-copyright: 'Copyright (c) 2016 John Doe'
+copyright: 'Copyright &copy; 2016 John Doe'
 
 # Documentation and theme
-docs_dir: 'docs'
 theme: 'material'
 
 # Options
 extra:
-  version: '0.1.0'
-  logo: 'images/logo.png'
+  logo: 'images/logo.svg'
   palette:
     primary: 'indigo'
-    accent: 'light blue'
+    accent: 'indigo'
   font:
     text: 'Roboto'
     code: 'Roboto Mono'
-  i18n:
-    prev: 'Previous'
-    next: 'Next'
-  author:
-    github: 'my-github-handle'
-    twitter: 'my-twitter-handle'
+  social:
+    - type: 'github'
+      link: 'https://github.com/squidfunk'
+    - type: 'twitter'
+      link: 'https://twitter.com/squidfunk'
+    - type: 'linkedin'
+      link: 'https://de.linkedin.com/in/martin-donath-20a95039'
 
 # Google Analytics
 google_analytics:
@@ -324,19 +353,9 @@ google_analytics:
 
 # Extensions
 markdown_extensions:
-  - codehilite(css_class=code)
   - admonition
-  - toc:
-      permalink: '¶'
+  - codehilite(guess_lang=false)
+  - footnotes
+  - meta
+  - toc(permalink=true)
 ```
-
-[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
-[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