diff --git a/docs/customization.md b/docs/customization.md index 365ee2aeb..99a1626b6 100644 --- a/docs/customization.md +++ b/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 | diff --git a/docs/extensions/metadata.md b/docs/extensions/metadata.md new file mode 100644 index 000000000..e01618f12 --- /dev/null +++ b/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 diff --git a/docs/getting-started.md b/docs/getting-started.md index cfb636991..9f763e0da 100644 --- a/docs/getting-started.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index c340001c5..8fcea4d84 100755 --- a/mkdocs.yml +++ b/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