Added documentation for Metadata extension

docs/customization.md

@@ -98,6 +98,7 @@ The directory layout of the Material theme is as follows:
 │  ├─ javascripts/                     # JavaScript
 │  └─ stylesheets/                     # Stylesheets
 ├─ partials/
+│  ├─ disqus.html                      # Disqus integration
 │  ├─ footer.html                      # Footer bar
 │  ├─ header.html                      # Header bar
 │  ├─ language.html                    # Localized labels
@@ -106,6 +107,8 @@ The directory layout of the Material theme is as follows:
 │  ├─ search.html                      # Search box
 │  ├─ social.html                      # Social links
 │  ├─ source.html                      # Repository information
+│  ├─ tabs-item.html                   # Tabs navigation item
+│  ├─ tabs.html                        # Tabs navigation
 │  ├─ toc-item.html                    # Table of contents item
 │  └─ toc.html                         # Table of contents
 ├─ 404.html                            # 404 error page
@@ -141,6 +144,7 @@ The Material theme provides the following template blocks:
 | ------------ | ----------------------------------------------- |
 | `analytics`  | Wraps the Google Analytics integration          |
 | `content`    | Wraps the main content                          |
+| `disqus`     | Wraps the disqus integration                    |
 | `extrahead`  | Empty block to define additional meta tags      |
 | `fonts`      | Wraps the webfont definitions                   |
 | `footer`     | Wraps the footer with navigation and copyright  |
@@ -149,6 +153,7 @@ The Material theme provides the following template blocks:
 | `libs`       | Wraps the JavaScript libraries, e.g. Modernizr  |
 | `repo`       | Wraps the repository link in the header bar     |
 | `scripts`    | Wraps the JavaScript application logic          |
+| `source`     | Wraps the linked source files                   |
 | `search_box` | Wraps the search form in the header bar         |
 | `site_meta`  | Wraps the meta tags in the document head        |
 | `site_name`  | Wraps the site name in the header bar           |

docs/extensions/metadata.md

@@ -0,0 +1,99 @@
+path: tree/master/docs/extensions
+source: metadata.md
+
+# Metadata
+
+The [Metadata][1] extension makes it possible to add metadata to a document
+which gives more control over the theme in a page-specific context.
+
+  [1]: https://pythonhosted.org/Markdown/extensions/meta_data.html
+
+## Installation
+
+Add the following lines to your `mkdocs.yml`:
+
+``` yaml
+markdown_extensions:
+  - metadata
+```
+
+## Usage
+
+Metadata is written as a series of key-value pairs at the beginning of the
+Markdown document, delimited by a blank line which ends the metadata context.
+Naturally, the metadata is stripped from the document before rendering the
+actual page content and made available to the theme.
+
+Example:
+
+``` markdown
+title: Lorem ipsum dolor sit amet
+description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
+path: tree/master/path/to/file
+source: file.js
+
+# Headline
+
+...
+```
+
+See the next section which covers the metadata that is supported by Material.
+
+### Overriding the title
+
+The page title can be overridden on a per-document level:
+
+``` markdown
+title: Lorem ipsum dolor sit amet
+```
+
+This will set the `title` tag inside the document `head` for the current page
+to the provided value. It will also override the default behaviour of Material
+for MkDocs which appends the site title using a dash as a separator to the page
+title.
+
+### Overriding the description
+
+The page description can also be overridden on a per-document level:
+
+``` yaml
+description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
+```
+
+This will set the `meta` tag containing the site description inside the
+document `head` for the current page to the provided value.
+
+### Linking sources
+
+When a document is related to a specific set of source files and the `repo_url`
+is defined inside the project's `mkdocs.yml`, the files can be linked using the
+`source` key:
+
+``` markdown
+source: file.js
+```
+
+A new entry at the bottom of the table of contents is generated that is linking
+to the section listing the linked source files. Multiple files can be linked by
+adding filenames on separate lines:
+
+``` markdown
+source: file.js
+        file.css
+```
+
+The filenames are appended to the `repo_url` set in your `mkdocs.yml`, but can
+be prefixed with a `path` to ensure correct path resolving:
+
+Example:
+
+``` markdown
+path: tree/master/docs/extensions
+source: metadata.md
+```
+
+Result:
+
+See the [source][2] section for the resulting output.
+
+  [2]: #__source

docs/getting-started.md

@@ -370,16 +370,18 @@ Material theme including more information regarding installation and usage:
 
 * [Admonition][20]
 * [Codehilite][21]
-* [Permalinks][22]
-* [Footnotes][23]
-* [PyMdown Extensions][24]
+* [Footnotes][22]
+* [Metadata][23]
+* [Permalinks][24]
+* [PyMdown Extensions][25]
 
   [19]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
   [20]: extensions/admonition.md
   [21]: extensions/codehilite.md
-  [22]: extensions/permalinks.md
-  [23]: extensions/footnotes.md
-  [24]: extensions/pymdown.md
+  [22]: extensions/footnotes.md
+  [23]: extensions/metadata.md
+  [24]: extensions/permalinks.md
+  [25]: extensions/pymdown.md
 
 ## Full example
 

mkdocs.yml

@@ -82,6 +82,7 @@ pages:
     - Admonition: extensions/admonition.md
     - CodeHilite: extensions/codehilite.md
     - Footnotes: extensions/footnotes.md
+    - Metadata: extensions/metadata.md
     - Permalinks: extensions/permalinks.md
     - PyMdown: extensions/pymdown.md
   - Specimen: specimen.md