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

Added note on examples

Browse Source
This commit is contained in:
squidfunk 2017-06-21 10:25:00 +02:00 committed by Martin Donath
parent a2261041dd
commit 32f6d63a29
1 changed files with 73 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

153
docs/getting-started.md
View File

@ -6,7 +6,7 @@
The official [Docker image][1] for Material comes with all dependencies The official [Docker image][1] for Material comes with all dependencies
pre-installed and ready-to-use with the latest version published on PyPI, pre-installed and ready-to-use with the latest version published on PyPI,
packaged in a very small image (28MB compressed). packaged in a very small image (23MB compressed).
[1]: https://hub.docker.com/r/squidfunk/mkdocs-material/ [1]: https://hub.docker.com/r/squidfunk/mkdocs-material/
@ -34,17 +34,7 @@ pip install mkdocs && mkdocs --version
Material requires MkDocs >= 0.16. Material requires MkDocs >= 0.16.
Furthermore, it is highly recommended to install [Pygments][3] and the
[PyMdown Extensions][4] to get the most out of the Material theme:
```sh
pip install pygments
pip install pymdown-extensions
```
[2]: http://www.mkdocs.org [2]: http://www.mkdocs.org
[3]: http://pygments.org
[4]: http://facelessuser.github.io/pymdown-extensions/
### Installing Material ### Installing Material
@ -58,19 +48,18 @@ pip install mkdocs-material
#### using choco #### using choco
If you're on Windows you can use [Chocolatey][5] to install [Material][6]: If you're on Windows you can use [Chocolatey][3] to install [Material][4]:
``` dos ``` dos
choco install mkdocs-material choco install mkdocs-material
``` ```
This will also install all required dependencies like [Python][7] and This will install all required dependencies like [Python][5] and [MkDocs][6].
[MkDocs][8].
[5]: https://chocolatey.org [3]: https://chocolatey.org
[6]: https://chocolatey.org/packages/mkdocs-material [4]: https://chocolatey.org/packages/mkdocs-material
[7]: https://chocolatey.org/packages/python [5]: https://chocolatey.org/packages/python
[8]: https://chocolatey.org/packages/mkdocs [6]: https://chocolatey.org/packages/mkdocs
#### cloning from GitHub #### cloning from GitHub
@ -81,10 +70,13 @@ repository into a subfolder of your project's root directory:
git clone https://github.com/squidfunk/mkdocs-material.git git clone https://github.com/squidfunk/mkdocs-material.git
``` ```
This is especially useful if you want to extend the theme and override some This is especially useful if you want to [extend the theme][7] and
parts of the theme. The theme will reside in the folder [override some parts][8] of the theme. The theme will reside in the folder
`mkdocs-material/material`. `mkdocs-material/material`.
[7]: customization.md#extending-the-theme
[8]: customization.md#overriding-partials
### Troubleshooting ### Troubleshooting
!!! warning "Installation on macOS" !!! warning "Installation on macOS"
@ -110,8 +102,8 @@ parts of the theme. The theme will reside in the folder
## Usage ## Usage
In order to enable the Material theme just add one of the following lines to In order to enable the theme just add one of the following lines to your
your `mkdocs.yml`. If you installed Material using pip: project's `mkdocs.yml`. If you installed Material using pip:
``` yaml ``` yaml
theme: 'material' theme: 'material'
@ -130,9 +122,9 @@ The development server can be started with the following command:
mkdocs serve mkdocs serve
``` ```
Now you can point your browser to [localhost:8000][9] and the Material theme Now you can point your browser to [http://localhost:8000][9] and the Material
should be visible. From here on, you can start writing your documentation, or theme should be visible. From here on, you can start writing your documentation,
read on and customize the theme through some options. or read on and customize the theme through some options.
[9]: http://localhost:8000 [9]: http://localhost:8000
@ -143,10 +135,10 @@ project's `mkdocs.yml`. See the following sections for all available options.
### Changing the color palette ### Changing the color palette
Material defines a default hue for every primary and accent color on Google's A default is hue is defined for every primary and accent color on Google's
Material Design [color palette][10]. This makes it very easy to change the Material Design [color palette][10], which makes it very easy to change the
overall look of the theme. Just set the primary and accent colors using the overall look of the theme. Just set the primary and accent colors using the
following variables in your `mkdocs.yml`: following variables:
``` yaml ``` yaml
extra: extra:
@ -162,9 +154,9 @@ Design color palette. Valid values are: `red`, `pink`, `purple`, `deep purple`,
The last three colors can only be used as a primary color. The last three colors can only be used as a primary color.
If the color is set via this configuration, an additional CSS file that 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 defines the color palette is automatically included. If you want to keep things
the repository and recompile the theme with your custom colors set. See the lean, clone the repository and recompile the theme with your custom colors set.
guide on [customization][11] for more information. See the guide on [customization][11] for more information.
[10]: http://www.materialui.co/colors [10]: http://www.materialui.co/colors
[11]: customization.md [11]: customization.md
@ -234,10 +226,10 @@ Click on a tile to change the accent color of the theme:
### Changing the font family ### Changing the font family
Material uses the [Roboto font family][12] by default, specifically the regular By default the [Roboto font family][12] is included with the theme, specifically
sans-serif type for text and the `monospaced` type for code. Both fonts are the regular sans-serif type for text and the `monospaced` type for code. Both
loaded from [Google Fonts][13] and can easily be changed to other fonts, like fonts are loaded from [Google Fonts][13] and can be changed to other fonts,
for example the [Ubuntu font family][14]: like for example the [Ubuntu font family][14]:
``` yaml ``` yaml
extra: extra:
@ -246,9 +238,9 @@ extra:
code: 'Ubuntu 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 weights 400 and **700**, the `monospaced` font
font in regular weight. If you want to load fonts from other destinations or in regular weight. If you want to load fonts from other destinations or don't
don't want to use the Google Fonts loading magic, just set `font` to `false`: want to use the Google Fonts loading magic, just set `font` to `false`:
``` yaml ``` yaml
extra: extra:
@ -269,8 +261,8 @@ repo_name: 'my-github-handle/my-project'
repo_url: 'https://github.com/my-github-handle/my-project' repo_url: 'https://github.com/my-github-handle/my-project'
``` ```
Material will render the name of the repository next to the search bar on The name of the repository will be rendered next to the search bar on big
big screens and as part of the main navigation drawer on smaller screen sizes. screens and as part of the main navigation drawer on smaller screen sizes.
Furthermore, if `repo_url` points to a GitHub, BitBucket or GitLab repository, Furthermore, if `repo_url` points to a GitHub, BitBucket or GitLab repository,
the respective service logo will be shown next to the name of the repository. the respective service logo will be shown next to the name of the repository.
Additionally, for GitHub, the number of stars and forks is shown. Additionally, for GitHub, the number of stars and forks is shown.
@ -288,8 +280,8 @@ Additionally, for GitHub, the number of stars and forks is shown.
### Adding a favicon ### Adding a favicon
Adding a favicon to your site is very easy. Simply set the following variable A favicon can be added by setting the `site_favicon` variable to an `.ico` or
via your project's `mkdocs.yml`: image file:
``` yaml ``` yaml
site_favicon: 'images/favicon.ico' site_favicon: 'images/favicon.ico'
@ -297,11 +289,10 @@ site_favicon: 'images/favicon.ico'
### Adding a logo ### Adding a logo
Material makes it easy to add your logo. Your logo should have rectangular Your logo should have rectangular shape with a minimum resolution of 128x128,
shape with a minimum resolution of 128x128, leave some room towards the edges leave some room towards the edges and be composed of high contrast areas on a
and be composed of high contrast areas on a transparent ground, as it will be transparent ground, as it will be placed on the colored header bar and drawer.
placed on the colored header bar and drawer. Simply create the folder Simply create the folder `docs/images`, add your logo and embed it with:
`docs/images`, add your logo and embed it with:
``` yaml ``` yaml
extra: extra:
@ -310,11 +301,10 @@ extra:
### Adding social links ### Adding social links
If you want to link your social accounts, the Material theme provides an easy Social accounts can be linked in the footer of the documentation using the
way for doing this in the footer of the documentation using the automatically automatically included [FontAwesome][16] webfont. The `type` must denote the
included [FontAwesome][16] webfont. The syntax is simple – the `type` must name of the social service, e.g. `github`, `twitter` or `linkedin` and the
denote the name of the social service, e.g. `github`, `twitter` or `linkedin` `link` must contain the URL you want to link to:
and the `link` must contain the URL you want to link to:
``` yaml ``` yaml
extra: extra:
@ -397,13 +387,18 @@ macro `t`:
Just copy the file from the original theme and make your adjustments. See the Just copy the file from the original theme and make your adjustments. See the
section on [overriding partials][18] and the general guide on section on [overriding partials][18] and the general guide on
[theme extension][19] in the customization guide. [theme extension][19] in the customization guide. Furthermore, see the
[example configuration][20] for a head start.
[18]: customization.md#overriding-partials
[19]: customization.md#extending-the-theme
[20]: https://github.com/squidfunk/mkdocs-material/tree/master/examples/language
#### Site search #### Site search
Site search is implemented using [lunr.js][20], which includes stemmers for the Site search is implemented using [lunr.js][21], which includes stemmers for the
English language by default. The community package [lunr-languages][21] adds English language by default, while stemmers for other languages are included
stemmers for other languages, which is also integrated with this theme. Support with [lunr-languages][22], both of which are integrated with this theme. Support
for other languages and even multilingual search can be activated by setting for other languages and even multilingual search can be activated by setting
the key `search.languages` to a comma-separated list of supported 2-letter the key `search.languages` to a comma-separated list of supported 2-letter
language codes, e.g.: language codes, e.g.:
@ -430,16 +425,14 @@ Norwegian `no`, Swedish `sv` and Turkish `tr`.
JavaScript payload by around 20kb (without gzip) and by another 15-30kb per JavaScript payload by around 20kb (without gzip) and by another 15-30kb per
language. language.
[18]: customization.md#overriding-partials [21]: https://lunrjs.com
[19]: customization.md#extending-the-theme [22]: https://github.com/MihaiValentin/lunr-languages
[20]: https://lunrjs.com
[21]: https://github.com/MihaiValentin/lunr-languages
### Tabs ### Tabs
From version 1.1.0 on, Material supports another layer on top of the main From version 1.1.0 on, Material supports another layer on top of the main
navigation for larger screens in the form of tabs. This is especially useful navigation for larger screens in the form of tabs. This is especially useful
for larger documentation projects with a few top-level sections. Tabs can be for larger documentation projects with only few top-level sections. Tabs can be
enabled by setting the respective feature flag to true: enabled by setting the respective feature flag to true:
``` yaml ``` yaml
@ -451,13 +444,13 @@ extra:
### More advanced customization ### More advanced customization
If you want to change the general appearance of the Material theme, see If you want to change the general appearance of the Material theme, see
[this article][22] for more information on advanced customization. [this article][23] for more information on advanced customization.
[22]: customization.md [23]: customization.md
## Extensions ## Extensions
MkDocs supports several [Markdown extensions][23]. The following extensions MkDocs supports several [Markdown extensions][24]. The following extensions
are not enabled by default (see the link for which are enabled by default) 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: but highly recommended, so they should be switched on at all times:
@ -471,20 +464,20 @@ markdown_extensions:
For more information, see the following list of extensions supported by the For more information, see the following list of extensions supported by the
Material theme including more information regarding installation and usage: Material theme including more information regarding installation and usage:
* [Admonition][24] * [Admonition][25]
* [Codehilite][25] * [Codehilite][26]
* [Footnotes][26] * [Footnotes][27]
* [Metadata][27] * [Metadata][28]
* [Permalinks][28] * [Permalinks][29]
* [PyMdown Extensions][28] * [PyMdown Extensions][30]
[23]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions [24]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
[24]: extensions/admonition.md [25]: extensions/admonition.md
[25]: extensions/codehilite.md [26]: extensions/codehilite.md
[26]: extensions/footnotes.md [27]: extensions/footnotes.md
[27]: extensions/metadata.md [28]: extensions/metadata.md
[28]: extensions/permalinks.md [29]: extensions/permalinks.md
[29]: extensions/pymdown.md [30]: extensions/pymdown.md
## Full example ## Full example
@ -495,11 +488,11 @@ Below is a full example configuration for a `mkdocs.yml`:
site_name: 'My Project' site_name: 'My Project'
site_description: 'A short description of my project' site_description: 'A short description of my project'
site_author: 'John Doe' site_author: 'John Doe'
site_url: 'https://my-github-handle.github.io/my-project' site_url: 'https://john-doe.github.io/my-project'
# Repository # Repository
repo_name: 'my-github-handle/my-project' repo_name: 'my-github-handle/my-project'
repo_url: 'https://github.com/my-github-handle/my-project' repo_url: 'https://github.com/john-doe/my-project'
# Copyright # Copyright
copyright: 'Copyright © 2016 - 2017 John Doe' copyright: 'Copyright © 2016 - 2017 John Doe'
@ -520,7 +513,7 @@ extra:
- type: 'github' - type: 'github'
link: 'https://github.com/john-doe' link: 'https://github.com/john-doe'
- type: 'twitter' - type: 'twitter'
link: 'https://twitter.com/jonh-doe' link: 'https://twitter.com/john-doe'
- type: 'linkedin' - type: 'linkedin'
link: 'https://de.linkedin.com/in/john-doe' link: 'https://de.linkedin.com/in/john-doe'