mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00

squidfunk 12d1ad61c4 Reworked customization documentation

2020-03-10 14:07:03 +01:00

22 KiB

Raw Blame History

Getting started

Installation

While there are several ways of installing Material for MkDocs, the recommended methods are either by using pip – the Python package manager – or by pulling the official Docker image.

with pip recommended

All operating systems

Material for MkDocs can be installed with pip:

pip install mkdocs-material

Note that this will automatically install compatible versions of MkDocs, Markdown, Pygments and PyMdown Extensions. Material for MkDocs always strives to support the latest versions, so there's no need to install those packages separately.

!!! tip "Installation in a virtual environment"

The best way to make sure that you end up with the correct versions and
without any incompatibility problems between packages it to use a __virtual
environment__. Don't know what this is or how to set it up? We recommend
to start by reading a [tutorial on virtual environments][6] for Python.

!!! warning "Installation on macOS"

When you're running the pre-installed version of Python on macOS, `pip`
tries to install packages in a folder for which your user might not have
the adequate permissions. There are two possible solutions for 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
  should eliminate a lot of problems you could be having with `pip`.

!!! failure "Error: unrecognized theme 'material'"

If you run into this error, the most common reason is that you installed
MkDocs through some package manager (e.g. Homebrew or `apt-get`) and
Material for MkDocs through `pip`, so both packages end up in different
locations. MkDocs only checks its install location for themes.

with docker recommended

All operating systems

The official Docker image is a great way to get up and running in a few minutes, as it comes with all dependencies pre-installed. Pull the image for the latest version with:

docker pull squidfunk/mkdocs-material

The mkdocs executable is provided as an entrypoint and serve is the default command. Start the development server in your project root – the folder where mkdocs.yml resides — with:

=== "Unix"

```
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
```

=== "Windows"

```
docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
```

with git

All operating systems

Material for MkDocs can be directly used from GitHub by cloning the repository into a subfolder of your project root which might be useful if you want to use the very latest version:

git clone https://github.com/squidfunk/mkdocs-material.git

The theme will reside in the folder mkdocs-material/material.

with choco

Windows only

Material for MkDocs can be installed with Chocolatey:

choco install mkdocs-material

Note that this is an unofficial package of Material for MkDocs, so please understand that the maintainers cannot provide any support for when using this method.

Configuration

Depending on your installation method, you can now add the following lines to mkdocs.yml in your project root. If you installed Material for MkDocs using a package manager add:

theme:
  name: material

If you cloned Material for MkDocs from GitHub add:

theme:
  name: null
  custom_dir: mkdocs-material/material

MkDocs includes a development server, so you can preview your changes as you write your documentation. The development server can be started with the following command:

mkdocs serve

Point your browser to http://localhost:8000 and your documentation should great you in a new look. If you're starting from scratch, the following configuration can be used as a starting point:

??? summary "Example configuration"

``` yaml
# Project information
site_name: Material for MkDocs
site_description: A Material Design theme for MkDocs
site_author: Martin Donath
site_url: https://squidfunk.github.io/mkdocs-material/

# Repository
repo_name: squidfunk/mkdocs-material
repo_url: https://github.com/squidfunk/mkdocs-material

# Copyright
copyright: Copyright &copy; 2016 - 2020 Martin Donath

# Configuration
theme:
  name: material
  language: en
  palette:
    primary: indigo
    accent: indigo
  font:
    text: Roboto
    code: Roboto Mono

# Extras
extra:
  social:
    - icon: fontawesome/brands/github-alt
      link: https://github.com/squidfunk
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/squidfunk
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/squidfunk

# Google Analytics
google_analytics:
  - UA-XXXXXXXX-X
  - auto

# Extensions
markdown_extensions:
  - admonition
  - codehilite:
      guess_lang: false
  - toc:
      permalink: true
```

Feature flags

These optional features are hidden behind flags and can be explicitly enabled in mkdocs.yml.

Instant loading 🐣

The (still experimental) instant loading feature will intercept clicks on all internal links and dispatch them directly via XHR without a full page reload. It can be enabled from mkdocs.yml with:

theme:
  features:
    - instant

The resulting page is parsed and injected and all event handlers and components are automatically rebound. This means that Material for MkDocs behaves like a Single Page Application, which is especially useful for large documentation sites that come with a huge search index, as the search index will now remain intact in-between document switches.

Tabs

The tabs feature will render top-level subsections in another navigational layer below the header on big screens (but leave them untouched on mobile). It can be enabled from mkdocs.yml with:

theme:
  features:
    - tabs

Note that all top-level pages (i.e. all top-level entries that directly refer to an *.md file) defined inside the nav entry of mkdocs.yml will be grouped under the first tab which will receive the title of the first page.

Language

Default: en

Material for MkDocs supports internationalization (i18n) and provides translations for all template variables and labels. You can set the language from mkdocs.yml with:

theme:
  language: en

The following language codes are supported:

af / Afrikaans
ar / Arabic
ca / Catalan
zh / Chinese (Simplified)
zh-Hant / Chinese (Traditional)
zh-TW / Chinese (Taiwanese)
hr / Croatian
cs / Czech
da / Danish
nl / Dutch
en / English
et / Estonian
fi / Finnish
fr / French
gl / Galician
de / German
gr / Greek
he / Hebrew
hi / Hindi
hu / Hungarian
id / Indonesian
it / Italian
ja / Japanese
kr / Korean
no / Norwegian
nn / Norwegian (Nynorsk)
fa / Persian
pl / Polish
pt / Portugese
ro / Romanian
ru / Russian
sr / Serbian
sh / Serbo-Croatian
sk / Slovak
si / Slovenian
es / Spanish
sv / Swedish
th / Thai
tr / Turkish
uk / Ukrainian
vi / Vietnamese
Add language

While many languages are read ltr (left-to-right), Material for MkDocs also supports rtl (right-to-left) directionality which is deduced from the selected language, but can also be set with:

theme:
  direction: rtl

Color palette

The Material Design color palette comes with 20 hues, all of which are included with Material for MkDocs. Primary and accent colors can be set from the project root's mkdocs.yml:

theme:
  palette:
    primary: indigo
    accent: indigo

If the colors are set with these configuration options, an additional CSS file that includes the hues of the color palette is automatically included and linked from the template.

??? tip "Custom colors with CSS variables"

Material for MkDocs defines all colors as CSS variables. If you want to
customize the colors beyond the palette (e.g. to use your brand's colors),
you can add an [additional stylesheet][13] and override the defaults:

``` css
:root {

  /* Default color shades */
  --md-default-fg-color:               ...;
  --md-default-fg-color--light:        ...;
  --md-default-fg-color--lighter:      ...;
  --md-default-fg-color--lightest:     ...;
  --md-default-bg-color:               ...;
  --md-default-bg-color--light:        ...;
  --md-default-bg-color--lighter:      ...;
  --md-default-bg-color--lightest:     ...;

  /* Primary color shades */
  --md-primary-fg-color:               ...;
  --md-primary-fg-color--light:        ...;
  --md-primary-fg-color--dark:         ...;
  --md-primary-bg-color:               ...;
  --md-primary-bg-color--light:        ...;

  /* Accent color shades */
  --md-accent-fg-color:                ...;
  --md-accent-fg-color--transparent:   ...;
  --md-accent-bg-color:                ...;
  --md-accent-bg-color--light:         ...;

  /* Code block color shades */
  --md-code-bg-color:                  ...;
  --md-code-fg-color:                  ...;
}
```

Primary color

Default: indigo

Click on a color name to change the primary color of the theme:

red pink purple deep purple indigo blue light blue cyan teal green light green lime yellow amber orange deep orange brown grey blue grey black white

Accent color

Default: indigo

Click on a color name to change the accent color of the theme:

red pink purple deep purple indigo blue light blue cyan teal green light green lime yellow amber orange deep orange

Fonts

Default: Roboto and Roboto Mono

The Roboto font family is the default font included with the theme, specifically the regular sans-serif type for text and the monospaced type for code. Both fonts are loaded from Google Fonts and can be changed to any valid webfont, like for example the Ubuntu font family:

theme:
  font:
    text: Ubuntu
    code: Ubuntu Mono

The text font will be loaded in weights 400 and 700, the monospaced font in regular weight. If you want to load fonts from other destinations or don't want to use Google Fonts for data privacy reasons, just set font to false:

theme:
  font: false

Icons

Default: material/library and fontawesome/brands/git-alt

Material for MkDocs uses icons in several places. Currently, the following icons can be changed from mkdocs.yml: the logo icon, the repository icon and the social link icons. While the social link icons are tied to the respective entries, the other icons can be changed by referencing a valid path (without the trailing .svg) relative to the .icons folder which comes with the theme:

theme:
  icon:
    logo: material/library
    repo: fontawesome/brands/git-alt

All icons are directly inlined as *.svg files, so no further requests will be made. Icon sets which are bundled with Material for MkDocs:

Material Design icons: 3.8k icons
FontAwesome icons: 1.5k icons
GitHub octicons: 200 icons

Logo

Default: icon set through theme.icon.logo

If you want to replace the icon in the header (screen) and drawer (mobile) with your brand's logo, you can place an image file in your docs folder and use the following option in mkdocs.yml:

theme:
  logo: images/logo.svg

Ideally, the image should be a square with a minimum resolution of 96x96, 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 and drawer.

Favicon

Default: assets/images/favicon.png

The default favicon can be changed with:

theme:
  favicon: images/favicon.png

Extras

Adding a source repository

To include a link to the repository of your project within your documentation, set the following variables via your project's mkdocs.yml:

repo_name: squidfunk/mkdocs-material
repo_url: https://github.com/squidfunk/mkdocs-material

The name of the repository will be rendered next to the search bar on big screens and as part of the main navigation drawer on smaller screen sizes. Additionally, for GitHub and GitLab, the number of stars and forks is shown. Note that the repository icon can be explicitly set through theme.icon.repo.

!!! question "Why is there an edit button at the top of every article?"

If the `repo_url` is set to a GitHub or BitBucket repository, and the
`repo_name` is set to *GitHub* or *BitBucket* (implied by default), an
edit button will appear at the top of every article. This is the automatic
behavior that MkDocs implements. See the [MkDocs documentation][21] on more
guidance regarding the `edit_uri` attribute, which defines whether the edit
button is shown or not.

Social accounts can be linked in the footer of the documentation using the icons which are bundled with the theme. Note that each icon must point to a valid path (without the trailing .svg) relative to the .icons folder which comes with the theme:

extra:
  social:
    - icon: fontawesome/brands/github-alt
      link: https://github.com/squidfunk
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/squidfunk
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/squidfunk

Adding a Web App Manifest

A Web App Manifest is a simple JSON file that tells the browser about your web application and how it should behave when installed on the user's mobile device or desktop. You can specify such a manifest in mkdocs.yml:

extra:
  manifest: manifest.webmanifest

Integrations

Google Analytics

MkDocs makes it easy to integrate site tracking with Google Analytics. Besides basic page views, site search is tracked to better understand how people use your documentation. Google Analytics can be activated with:

google_analytics:
  - UA-XXXXXXXX-X
  - auto

Disqus

Material for MkDocs is integrated with Disqus, so if you want to add a comments section to your documentation set the shortname of your Disqus project in mkdocs.yml:

extra:
  disqus: your-shortname

The comments section is inserted on every page, except the index page. The necessary JavaScript is automatically included.

!!! warning "Requirements"

Note that `site_url` must be set in `mkdocs.yml` for the Disqus integration
to load properly.

Disqus can also be enabled or disabled for specific pages using Metadata.

Extensions

Markdown comes with several very useful extensions, the following of which are not enabled by default but highly recommended, so enabling them should definitely be a good idea:

markdown_extensions:
  - admonition
  - codehilite:
      guess_lang: false
  - toc:
      permalink: true

See the following list of extensions supported by Material for MkDocs including some more information on configuration and usage:

Plugins

MkDocs' plugin architecture makes it possible to add pre- or post-processing steps that sit between the theme and your documentation. For more information, see the following list of plugins tested and supported by Material for MkDocs including more information regarding installation and usage:

Search (enabled by default)
Minification
Revision date

For further reference, the MkDocs wiki contains a list of all available plugins.

22 KiB Raw Blame History Unescape Escape

Getting started

Installation

with pip recommended

with docker recommended

with git

with choco

Configuration

Feature flags

Instant loading 🐣

Tabs

Language

Color palette

Primary color

Accent color

Fonts

Icons

Logo

Favicon

Extras

Adding a source repository

Adding social links

Adding a Web App Manifest

Integrations

Google Analytics

Disqus

Extensions

Plugins

22 KiB

Raw Blame History