Updated documentation for 1.0.0

This commit is contained in:
squidfunk 2017-01-02 23:11:32 +01:00
parent 983e5bbf72
commit 1e590ba872
7 changed files with 283 additions and 150 deletions

66
docs/contributing.md Normal file
View File

@ -0,0 +1,66 @@
# Contributing
Interested in contributing to the Material theme? Before you do, please read
the following guidelines.
## Submission context
### Got a question or problem?
For quick questions there's no need to open an issue as you can reach us on
[gitter.im][1].
[1]: https://gitter.im/mkdocs-material/general
### Found a bug?
If you found a bug in the source code, you can help us by submitting an issue
to our GitHub Repository. Even better, you can submit a Pull Request with a
fix. However, before doing so, read the submission guidelines.
### Missing a feature?
You can request a new feature by submitting an issue to our GitHub Repository.
If you would like to implement a new feature, please submit an issue with a
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
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
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.
## Submission guidelines
### Submitting an issue
Before you submit an issue, please search the issue tracker, maybe an issue for
your problem already exists and the discussion might inform you of workarounds
readily available.
We want to fix all the issues as soon as possible, but before fixing a bug we
need to reproduce and confirm it. In order to reproduce bugs we will
systematically ask you to provide a minimal reproduction scenario using the
custom issue template.
Unfortunately we are not able to investigate / fix bugs without a minimal
reproduction, so if we don't hear back from you we are going to close issues
that don't have enough information to be reproduced.
### Submitting a Pull Request (PR)
Search GitHub for an open or closed PR that relates to your submission. You
don't want to duplicate effort. Fork the project, make your changes in **a new
git branch** and commit your changes with a descriptive commit message. Then
push your branch to GitHub and send a PR to `mkdocs-material:master`. If we
suggest changes, make the required updates, rebase your branch and push
the changes to your GitHub repository, which will automatiaclly update your PR.
After your PR is merged, you can safely delete your branch and pull the changes
from the main (upstream) repository.

View File

@ -1,100 +1,228 @@
# Customization
## A good starting point
## A great starting point
Project documentation is as diverse as the projects themselves and the Material
theme is a good starting point for making it look good. However, as you write
theme is a good starting point for making it look great. However, as you write
your documentation, you may reach some point where some small adjustments are
necessary to preserve the style.
## Small tweaks
## Adding assets
[MkDocs][] provides a simple way for making small adjustments, that is changing
some margins, centering text, etc. Simply put the CSS and Javascript files that
contain your adjustments in the `docs` directory (ideally in subdirectories of
their own) and include them via the `extra_css` and `extra_javascript`
variables in your `mkdocs.yml`:
[MkDocs][1] provides several ways to interfere with themes. In order to make a
few tweaks to an existing theme, you can just add your stylesheets and
JavaScript files to the `docs` directory.
``` yaml
extra_css: ['/stylesheets/extra.css']
extra_javascript: ['/javascripts/extra.js']
[1]: http://www.mkdocs.org
### Additional stylesheets
If you want to tweak some colors or change the spacing of certain elements,
you can do this in a separate stylesheet. The easiest way is by creating a
new stylesheet file in your docs directory:
``` sh
mkdir docs/stylesheets
touch docs/stylesheets/extra.css
```
Further assistance on including extra CSS and Javascript can be found in the
[MkDocs documentation][].
Then, add the following line to your `mkdocs.yml`:
## Fundamental changes
``` yaml
extra_css: ['stylesheets/extra.css']
```
If you want to make larger adjustments like changing the color palette or
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.
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?
### Setup
### Additional JavaScript
In order to compile the project, you need `node` with a version greater than
`0.11` up and running.
The same is true for additional JavaScript. If you want to integrate another
syntax highlighter or add some custom logic to your theme, create a new
JavaScript file in your docs directory:
The project itself is hosted on GitHub, so the next
thing you should do is clone the project from GitHub:
``` sh
mkdir docs/javascripts
touch docs/javascripts/extra.js
```
Then, add the following line to your `mkdocs.yml`:
``` yaml
extra_javascript: ['javascripts/extra.js']
```
Further assistance can be found in the [MkDocs documentation][2].
[2]: http://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme
## Extending the theme
If you want to alter the HTML source (e.g. add or remove some part), you can
extend the theme. From version 0.16 on MkDocs implements [theme extension][3],
an easy way to override parts of a theme without forking and changing the
main theme.
[3]: http://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme_dir
### Setup and theme structure
Reference the Material theme as usual in your `mkdocs.yml`, and create a
new folder for overrides, e.g. `theme`, which you reference using `theme_dir`:
``` yaml
theme: 'material'
theme_dir: 'theme'
```
!!! warning "Theme extension prerequisites"
As the `theme_dir` variable is used for the theme extension process, the
Material theme needs to be installed via `pip` and referenced with the
`theme` parameter in your `mkdocs.yml`.
The structure in the theme directory must mirror the directory structure of the
original theme, as any file in the theme directory will replace the file with
the same name which is part of the original theme. Besides, further assets
may also be put in the theme directory.
The directory layout of the Material theme is as follows:
``` sh
.
├─ assets/
│ ├─ images/ # Images and icons
│ ├─ javascripts/ # JavaScript
│ └─ stylesheets/ # Stylesheets
├─ partials/
│ ├─ fonts.html # Webfont definitions
│ ├─ footer.html # Footer bar
│ ├─ header.html # Header bar
│ ├─ nav-item.html # Main navigation item
│ ├─ nav.html # Main navigation
│ ├─ search.html # Search box
│ ├─ source.html # Repository information
│ ├─ svgs.html # Inline SVG definitions
│ ├─ toc-item.html # Table of contents item
│ └─ toc.html # Table of contents
├─ 404.html # 404 error page
├─ base.html # Base template
└─ main.html # Default page
```
### Overriding partials
In order to override the footer, we can replace the `footer.html` partial with
our own partial. To do this, create the file `partials/footer.html` in the
theme directory. MkDocs will now use the new partial when rendering the theme.
This can be done with any file.
### Overriding template blocks
Besides overriding partials, one can also override so called template blocks,
which are defined inside the Material theme and wrap specific features. To
override a template block, create a `main.html` inside the theme directory and
define the block, e.g.:
``` jinja
{% extends "base.html" %}
{% block htmltitle %}
<title>Lorem ipsum dolor sit amet</title>
{% endblock %}
```
The Material theme provides the following template blocks:
| Block name | Wrapped contents |
| ------------ | ----------------------------------------------- |
| `analytics` | Wraps the Google Analytics integration |
| `content` | Wraps the main content |
| `extrahead` | Empty block to define additional meta tags |
| `fonts` | Wraps the webfont definitions |
| `footer` | Wraps the footer with navigation and copyright |
| `header` | Wraps the fixed header bar |
| `htmltitle` | Wraps the `<title>` tag |
| `libs` | Wraps the JavaScript libraries, e.g. Modernizr |
| `repo` | Wraps the repository link in the header bar |
| `scripts` | Wraps the JavaScript application logic |
| `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 |
| `site_nav` | Wraps the site navigation and table of contents |
| `styles` | Wraps the stylesheets (also extra sources) |
For more on this topic refer to the [MkDocs documentation][4]
[4]: http://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
## Theme development
The Material theme is built on modern technologies like ES6, [Webpack][5],
[Babel][6] and [SASS][7]. If you want to make more fundamental changes, it may
be necessary to make the adjustments directly in the source of the Material
theme and recompile it. This is fairly easy.
[5]: https://webpack.github.io/
[6]: https://babeljs.io
[7]: http://sass-lang.com
### Environment setup
In order to start development on the Material theme, a [Node.js][8] version of
at least 4 is required. Clone the repository 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` with the following command:
Next, all dependencies need to be installed, which is done with:
``` sh
cd mkdocs-material
npm install
```
### Development
[8]: https://nodejs.org
The asset pipeline is contained in `Gulpfile.js`, which you can start with
`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.
### Development mode
The Material theme uses a sophisticated asset pipeline using [Gulp][9] and
Webpack which can be started with the following command:
``` sh
gulp watch --mkdocs
npm run start
```
For example, changing the color palette is as simple as changing the `$primary`
and `$accent` variables in `src/assets/stylesheets/_palette.scss`:
This will also start the MkDocs development server which will monitor changes
on assets, templates and documentation. Point your browser to
[localhost:8000](http://localhost:8000) and you should see this very
documentation in front of your eyes.
For example, changing the color palette is as simple as changing the
`$md-color-primary` and `$md-color-accent` variables in
`src/assets/stylesheets/_config.scss`:
``` css
$primary: $red-400;
$accent: $teal-a700;
$md-color-primary: $clr-red-400;
$md-color-accent: $clr-teal-a700;
```
The color variables are defined by the SASS library [quantum-colors][] and
resemble all the colors contained in the material design palette.
[This page][material-colors] offers a really good overview of the palette.
[9]: http://gulpjs.com
### Building
### Build process
When you finished making your changes, you can build the theme by invoking:
``` sh
gulp build --production
npm run build
```
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`:
``` yaml
theme_dir: 'mkdocs-material/material'
```
This triggers the production-level compilation and minification of all
stylesheets 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`.
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
[quantum-colors]: https://github.com/nkpfstr/quantum-colors
[material-colors]: http://www.materialui.co/colors

View File

@ -58,7 +58,7 @@ Result:
<a href="#fn:1">Jump to footnote at the bottom of the page</a>
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
#### on multiple lines
@ -76,9 +76,9 @@ Example:
Result:
[^2]:
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.
[^2]:
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.
<a href="#fn:2">Jump to footnote at the bottom of the page</a>

View File

@ -41,7 +41,7 @@ markdown_extensions:
- pymdownx.arithmatex
```
## Extensions
## Usage
### GitHub Flavored Markdown

View File

@ -26,8 +26,8 @@ pip install mkdocs && mkdocs --version
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:
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
@ -241,7 +241,7 @@ 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:
`link`, well, resembles the link:
``` yaml
extra:

View File

@ -1,9 +1,9 @@
# Material <small>for MkDocs</small>
## Beautiful documentation
## Build beautiful documentation
Material is a theme for [MkDocs][], an excellent static site generator geared
towards project documentation. It is built using Google's [material design][]
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, full responsive, optimized for touch and pointer devices as well
as all sorts of screen sizes.
@ -12,9 +12,12 @@ 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.
[1]: http://www.mkdocs.org
[2]: https://www.google.com/design/spec/material-design
## Quick start
Install with `pip`:
Install the latest version of Material with `pip`:
``` sh
pip install mkdocs-material
@ -52,8 +55,7 @@ theme: 'material'
See the [getting started guide](getting-started.md) for instructions how to get
it up and running.
[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
[easily customizable color palette]: getting-started.md#changing-the-color-palette

View File

@ -1,8 +1,6 @@
# Specimen
## Typography
### Body copy
## Body copy
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras arcu libero,
mollis sed massa vel, *ornare viverra ex*. Mauris a ullamcorper lacus. Nullam
@ -16,7 +14,9 @@ eros. [Nulla aliquam](/) orci sit amet nisl posuere malesuada. Proin aliquet
nulla velit, quis ultricies orci feugiat et. `Ut tincidunt sollicitudin`
tincidunt. Aenean ullamcorper sit amet nulla at interdum.
### Headings
## Headings
### The 3rd level
#### The 4th level
@ -24,7 +24,9 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
###### The 6th level
### Headings <small>with secondary text</small>
## Headings <small>with secondary text</small>
### The 3rd level <small>with secondary text</small>
#### The 4th level <small>with secondary text</small>
@ -32,7 +34,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
###### The 6th level <small>with secondary text</small>
### Blockquotes
## Blockquotes
> Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet rutrum.
Pellentesque aliquet quam enim, eu volutpat urna rutrum a. Nam vehicula nunc
@ -40,7 +42,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie
imperdiet consectetur.
#### Blockquote nesting
### Blockquote nesting
> **Sed aliquet**, neque at rutrum mollis, neque nisi tincidunt nibh, vitae
faucibus lacus nunc at lacus. Nunc scelerisque, quam id cursus sodales, lorem
@ -55,7 +57,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
Interdum et malesuada fames ac ante ipsum primis in faucibus. Sed nec leo
bibendum, sodales mauris ut, tincidunt massa.
#### Other content blocks
### Other content blocks
> Vestibulum vitae orci quis ante viverra ultricies ut eget turpis. Sed eu
lectus dapibus, eleifend nulla varius, lobortis turpis. In ac hendrerit nisl,
@ -76,9 +78,9 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
vel lacinia lacus. Suspendisse rhoncus nunc non nisi iaculis ultrices.
Donec consectetur mauris non neque imperdiet, eget volutpat libero.
### Lists
## Lists
#### Unordered lists
### Unordered lists
* Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus tellus
non sem sollicitudin, quis rutrum leo facilisis. Nulla tempor lobortis orci,
@ -96,7 +98,7 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
lacinia sed. Aenean in finibus diam.
#### Ordered lists
### Ordered lists
1. Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis
elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla
@ -135,9 +137,9 @@ tincidunt. Aenean ullamcorper sit amet nulla at interdum.
sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
nulla. Vivamus a pharetra leo.
### Code blocks
## Code blocks
#### Inline
### Inline
Morbi eget `dapibus felis`. Vivamus *`venenatis porttitor`* tortor sit amet
rutrum. Class aptent taciti sociosqu ad litora torquent per conubia nostra,
@ -148,7 +150,7 @@ Nam vehicula nunc `:::js return target` mauris, a ultricies libero efficitur
sed. Sed molestie imperdiet consectetur. Vivamus a pharetra leo. Pellentesque
eget ornare tellus, ut gravida mi. Fusce vel lacinia lacus.
#### Listing
### Listing
#!js hl_lines="8"
var _extends = function(target) {
@ -161,7 +163,7 @@ eget ornare tellus, ut gravida mi. Fusce vel lacinia lacus.
return target;
};
### Horizontal rules
## Horizontal rules
Aenean in finibus diam. Duis mollis est eget nibh volutpat, fermentum aliquet
dui mollis. Nam vulputate tincidunt fringilla. Nullam dignissim ultrices urna
@ -173,7 +175,7 @@ Integer vehicula feugiat magna, a mollis tellus. Nam mollis ex ante, quis
elementum eros tempor rutrum. Aenean efficitur lobortis lacinia. Nulla
consectetur feugiat sodales.
### Data tables
## Data tables
| Sollicitudo / Pellentesi | consectetur | adipiscing | elit | arcu | sed |
| ------------------------ | ----------- | ---------- | ------- | ---- | --- |
@ -224,68 +226,3 @@ sit amet laoreet nibh.
</tr>
</tbody>
</table>
## 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>