OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Updated getting started guide [ci skip]

Browse Source
This commit is contained in:
squidfunk
2016-12-29 17:55:08 +01:00
parent 763c23eebb
commit 1248237d60
1 changed files with 197 additions and 178 deletions
Download Patch File Download Diff File Expand all files Collapse all files

375
docs/getting-started.md
View File

@@ -12,111 +12,113 @@ base_url: http://example.com
### Installing MkDocs ### Installing MkDocs
Before installing [MkDocs][], you need to make sure you have Python and `pip` Before installing [MkDocs][1], you need to make sure you have Python and `pip`
– the Python package manager – up and running. Assuming you are a developer and – the Python package manager – up and running. You can verify if you're already
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
good to go with the following commands: good to go with the following commands:
``` sh ``` sh
python --version python --version
# Python 2.7.2 # Python 2.7.13
pip --version pip --version
# pip 1.5.2 # pip 9.0.1
``` ```
Installing and verifying MkDocs is as simple as: Installing and verifying MkDocs is as simple as:
``` sh ``` sh
pip install mkdocs && mkdocs --version 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 ### Installing Material
Next, assuming you have MkDocs up and running `mkdocs-material` can be #### by using pip
installed with `pip`:
Material can be installed with `pip`:
``` sh ``` sh
pip install mkdocs-material 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 When you're running the pre-installed version of Python on OS X, `pip` tries
simple in MkDocs: 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 ``` sh
mkdocs new my-project git clone https://github.com/squidfunk/mkdocs-material.git
cd my-project
``` ```
MkDocs will create the necessary files and base directory structure inside the This is especially useful if you want to extend the theme and use partials.
folder `my-project`. In order to enable the theme just add the following line The theme will reside in the folder `mkdocs-material/material`.
to the auto-generated `mkdocs.yml`:
## 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 ``` yaml
theme: 'material' theme: 'material'
``` ```
If your project is hosted on GitHub, add the repository link to the When you cloned Material from GitHub, use:
configuration. If the `repo_name` equals **GitHub**, the Material theme will
add a download and star button, and display the number of stars:
``` yaml ``` yaml
repo_name: 'GitHub' theme_dir: 'mkdocs-material/material'
repo_url: 'https://github.com/my-github-handle/my-project'
``` ```
MkDocs includes a development server, so you can view your changes as you go - That's it. MkDocs includes a development server, so you can view your changes
very handy. Spin it up with the following command: as you go - very handy. Spin it up with the following command:
``` sh ``` sh
mkdocs serve mkdocs serve
``` ```
Now you can go to [localhost:8000](http://localhost:8000) and the Material Now you can point your browser to [localhost:8000](http://localhost:8000) and
theme should be visible. You can now start writing your documentation, or read the Material theme should be visible. You can now start writing your
on and customize the theme through some options. documentation, or read on and customize the theme through some options.
## Options ## Options
The Material theme adds some extra variables for configuration via your The Material theme adds some extra variables for configuration via your
project's `mkdocs.yml`. See the following section for all available options. 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 ### Changing the color palette
Material defines a default hue for every primary and accent color on Google's 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 material design [color palette][4]. This makes it very easy to change the
overall look of the theme. Just set the variables `extra.palette.primary` and overall look of the theme. Just set the primary and accent colors using the
`extra.palette.accent` to one of the colors defined in the palette: following variables in your `mkdocs.yml`:
``` yaml ``` yaml
extra: extra:
@@ -126,71 +128,150 @@ extra:
``` ```
Color names can be written upper- or lowercase but must match the names of the 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_, material design color palette. Valid values are: `red`, `pink`, `purple`,
_deep purple_, _indigo_, _blue_, _light blue_, _cyan_, _teal_, _green_, _light `deep purple`, `indigo`, `blue`, `light blue`, `cyan`, `teal`, `green`, `light
green_, _lime_, _yellow_, _amber_, _orange_, _deep orange_, _brown_, _grey_ and green`, `lime`, `yellow`, `amber`, `orange`, `deep orange`, `brown`, `grey` and
_blue grey_. The last three colors can only be used as a primary color. `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 If the color is set via this configuration, an additional CSS file that
`palettes.css` is included that defines the color palettes. If you want to defines the color palette is included. If you want to keep things lean, clone
keep things lean, clone the repository and recompile the theme with your the repository and recompile the theme with your custom colors set. See [this
custom colors set. See [this article](customization.md) for more information. 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 ### 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 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 loaded from [Google Fonts][6] and can easily be changed to other fonts, like
example Google's own [Roboto font][]: for example the [Ubuntu font family][7]:
``` yaml ``` yaml
extra: extra:
font: font:
text: 'Roboto' text: 'Ubuntu'
code: 'Roboto Mono' code: 'Ubuntu Mono'
``` ```
The text font will be loaded in font-weights 400 and **700**, the monospaced 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 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 don't want to use the Google Fonts loading magic, just set `font` to `'none'`:
`'none'`:
``` yaml ``` yaml
extra: extra:
font: 'none' 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 ### Adding a logo
defining the variables `extra.i18n.prev` and `extra.i18n.next`:
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 ``` yaml
extra: extra:
i18n: logo: 'images/logo.svg'
prev: 'Previous'
next: 'Next'
``` ```
### Adding a GitHub and Twitter account ### Adding social links
If you have a GitHub and/or Twitter account, you can add links to your If you want to link your social accounts, the Material theme provides an easy
accounts to the drawer by setting the variables `extra.author.github` and way for doing this in the footer of the documentation using the automatically
`extra.author.twitter` respectively: 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 ``` yaml
extra: extra:
author: social:
github: 'my-github-handle' - type: 'github'
twitter: 'my-twitter-handle' 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 ### Google Analytics integration
Material makes it easy to integrate site tracking with Google Analytics. MkDocs makes it easy to integrate site tracking with Google Analytics.
Besides basic tracking, clicks on all outgoing links can be tracked, clicks on Besides basic tracking, clicks on all outgoing links can be tracked as well as
the download and star button, as well as how site search is used. Tracking can how site search is used. Tracking can be activated in your project's
be activated in your project's `mkdocs.yml`: `mkdocs.yml`:
``` yaml ``` yaml
google_analytics: google_analytics:
@@ -205,78 +286,27 @@ If you want to change the general appearance of the Material theme, see
## Extensions ## Extensions
MkDocs supports several [Markdown extensions][]. The following extensions are MkDocs supports several [Markdown extensions][9]. The following extensions are
not enabled by default (see the link for which are enabled by default), so you not enabled by default (see the link for which are enabled by default) but
have to switch them on explicitly. highly recommended, so they should be switched on at all times:
### 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`:
``` yaml ``` yaml
markdown_extensions: markdown_extensions:
- admonition - 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 * [Admonition](extensions/admonition.md)
!!! note * [Codehilite](extensions/codehilite.md)
Nothing to see here, move along. * [Permalinks](extensions/permalinks.md)
``` * [Footnotes](extensions/footnotes.md)
* [PyMdown Extensions](extensions/pymdown.md)
This will print the following block: [9]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
!!! 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.
## Full example ## Full example
@@ -294,28 +324,27 @@ repo_name: 'GitHub'
repo_url: 'https://github.com/my-github-handle/my-project' repo_url: 'https://github.com/my-github-handle/my-project'
# Copyright # Copyright
copyright: 'Copyright (c) 2016 John Doe' copyright: 'Copyright &copy; 2016 John Doe'
# Documentation and theme # Documentation and theme
docs_dir: 'docs'
theme: 'material' theme: 'material'
# Options # Options
extra: extra:
version: '0.1.0' logo: 'images/logo.svg'
logo: 'images/logo.png'
palette: palette:
primary: 'indigo' primary: 'indigo'
accent: 'light blue' accent: 'indigo'
font: font:
text: 'Roboto' text: 'Roboto'
code: 'Roboto Mono' code: 'Roboto Mono'
i18n: social:
prev: 'Previous' - type: 'github'
next: 'Next' link: 'https://github.com/squidfunk'
author: - type: 'twitter'
github: 'my-github-handle' link: 'https://twitter.com/squidfunk'
twitter: 'my-twitter-handle' - type: 'linkedin'
link: 'https://de.linkedin.com/in/martin-donath-20a95039'
# Google Analytics # Google Analytics
google_analytics: google_analytics:
@@ -324,19 +353,9 @@ google_analytics:
# Extensions # Extensions
markdown_extensions: markdown_extensions:
- codehilite(css_class=code)
- admonition - admonition
- toc: - codehilite(guess_lang=false)
permalink: '¶' - 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