Commit df441033 authored by Alexander Martinez's avatar Alexander Martinez
Browse files

template

parent 24f647d5
Pipeline #1182 failed with stages
in 1 minute and 45 seconds
This diff is collapsed.
---
template: overrides/main.html
---
# Creating your site
After you've [installed][1] Material for MkDocs, you can bootstrap your project
documentation using the `mkdocs` executable. Go to the directory where you want
your project to be located and enter:
```
mkdocs new .
```
Alternatively, if you're running Material for MkDocs from within Docker, use:
=== "Unix, Powershell"
```
docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .
```
=== "Windows"
```
docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new .
```
This will create the following structure:
```
.
├─ docs/
│ └─ index.md
└─ mkdocs.yml
```
[1]: getting-started.md
## Configuration
### Minimal configuration
Simply add the following lines to `mkdocs.yml` to enable the theme. Note that
since there are several [installation methods][2], configuration might be
slightly different:
=== "pip, docker"
``` yaml
theme:
name: material
```
=== "git"
``` yaml
theme:
name: null
custom_dir: mkdocs-material/material
# 404 page
static_templates:
- 404.html
# Necessary for search to work properly
include_search_page: false
search_index_only: true
# Default values, taken from mkdocs_theme.yml
language: en
font:
text: Roboto
code: Roboto Mono
favicon: assets/favicon.png
icon:
logo: logo
```
_If you cloned Material for MkDocs from GitHub, you must list all of the themes'
defaults, because_ [`mkdocs_theme.yml`][3] _is not loaded automatically as
[described in the official documentation][4]._
[2]: getting-started.md#installation
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/mkdocs_theme.yml
[4]: https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme
### Advanced configuration
Material for MkDocs comes with many configuration options. The _setup_ section
explains in great detail how to configure and customize colors, fonts, icons
and much more:
<div class="mdx-columns" markdown="1">
- [Changing the colors][5]
- [Changing the fonts][6]
- [Changing the language][7]
- [Changing the logo and icons][8]
- [Setting up navigation][9]
- [Setting up site search][10]
- [Setting up site analytics][11]
- [Setting up versioning][12]
- [Setting up the header][13]
- [Setting up the footer][14]
- [Adding a git repository][15]
- [Adding a comment system][16]
</div>
[5]: setup/changing-the-colors.md
[6]: setup/changing-the-fonts.md
[7]: setup/changing-the-language.md
[8]: setup/changing-the-logo-and-icons.md
[9]: setup/setting-up-navigation.md
[10]: setup/setting-up-site-search.md
[11]: setup/setting-up-site-analytics.md
[12]: setup/setting-up-versioning.md
[13]: setup/setting-up-the-header.md
[14]: setup/setting-up-the-footer.md
[15]: setup/adding-a-git-repository.md
[16]: setup/adding-a-comment-system.md
## Previewing as you write
MkDocs includes a live preview server, so you can preview your changes as you
write your documentation. The server will automatically rebuild the site upon
saving. Start it with:
```
mkdocs serve
```
If you're running Material for MkDocs from within Docker, use:
=== "Unix, Powershell"
```
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
```
Point your browser to [localhost:8000][17] and you should see:
[![Creating your site][18]][18]
[17]: http://localhost:8000
[18]: assets/screenshots/creating-your-site.png
## Building your site
When you're finished editing, you can build a static site from your Markdown
files with:
```
mkdocs build
```
The contents of this directory make up your project documentation. There's no
need for operating a database or server, as it is completely self-contained.
The site can be hosted on [GitHub Pages][19], [GitLab Pages][20], a CDN of your
choice or your private web space.
[19]: publishing-your-site.md#github-pages
[20]: publishing-your-site.md#gitlab-pages
---
template: overrides/main.html
---
# Customization
Project documentation is as diverse as the projects themselves and Material for
MkDocs is a great starting point for making it look beautiful. However, as you
write your documentation, you may reach a point where small adjustments are
necessary to preserve your brand's style.
## Adding assets
[MkDocs][1] provides several ways to customize a theme. In order to make a few
tweaks to Material for MkDocs, you can just add your stylesheets and JavaScript
files to the `docs` directory.
[1]: https://www.mkdocs.org
### Additional CSS
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 the `docs` directory:
``` sh
.
├─ docs/
│ └─ stylesheets/
│ └─ extra.css
└─ mkdocs.yml
```
Then, add the following line to `mkdocs.yml`:
``` yaml
extra_css:
- stylesheets/extra.css
```
Spin up the [live preview server][2] and start typing your changes in your
additional stylesheet file – you should see them almost instantly after saving.
[2]: creating-your-site.md#previewing-as-you-write
### Additional JavaScript
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 the `docs` directory:
``` sh
.
├─ docs/
│ └─ javascripts/
│ └─ extra.js
└─ mkdocs.yml
```
Then, add the following line to `mkdocs.yml`:
``` yaml
extra_javascript:
- javascripts/extra.js
```
Further assistance can be found in the [MkDocs documentation][3].
[3]: https://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 parts), you can
extend the theme. MkDocs supports [theme extension][4], an easy way to override
parts of Material for MkDocs without forking from git. This ensures that you
can update to the latest version more easily.
[4]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
### Setup and theme structure
Enable Material for MkDocs as usual in `mkdocs.yml`, and create a new folder
for `overrides` which you then reference using the `custom_dir` key:
``` yaml
theme:
name: material
custom_dir: overrides
```
!!! warning "Theme extension prerequisites"
As the `custom_dir` variable is used for the theme extension process,
Material for MkDocs needs to be installed via `pip` and referenced with the
`name` parameter in `mkdocs.yml`. It will not work when cloning from `git`.
The structure in the `overrides` directory must mirror the directory structure
of the original theme, as any file in the `overrides` 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 `overrides` directory.
The directory layout of the theme is as follows:
``` sh
.
├─ .icons/ # Bundled icon sets
├─ assets/
│ ├─ images/ # Images and icons
│ ├─ javascripts/ # JavaScript
│ └─ stylesheets/ # Stylesheets
├─ partials/
│ ├─ integrations/ # Third-party integrations
│ │ ├─ analytics.html # - Google Analytics
│ │ └─ disqus.html # - Disqus
│ ├─ languages/ # Localized languages
│ ├─ footer.html # Footer bar
│ ├─ header.html # Header bar
│ ├─ language.html # Localized labels
│ ├─ logo.html # Logo in header and sidebar
│ ├─ nav.html # Main navigation
│ ├─ nav-item.html # Main navigation item
│ ├─ palette.html # Color palette
│ ├─ search.html # Search box
│ ├─ social.html # Social links
│ ├─ source.html # Repository information
│ ├─ source-date.html # Last updated date
│ ├─ source-link.html # Link to source file
│ ├─ tabs.html # Tabs navigation
│ ├─ tabs-item.html # Tabs navigation item
│ ├─ toc.html # Table of contents
│ └─ toc-item.html # Table of contents item
├─ 404.html # 404 error page
├─ base.html # Base template
└─ main.html # Default page
```
### Overriding partials
In order to override a partial, we can replace it with a file of the same name
and location in the `overrides` directory. For example, to replace the original
`footer.html`, create a `footer.html` file in the `overrides/partials`
directory:
``` sh
.
├─ overrides/
│ └─ partials/
│ └─ footer.html
└─ mkdocs.yml
```
MkDocs will now use the new partial when rendering the theme. This can be done
with any file.
### Overriding blocks
Besides overriding partials, it's also possible to override (and extend)
_template blocks_, which are defined inside the templates and wrap specific
features. To override a block, create a `main.html` file inside the `overrides`
directory:
``` sh
.
├─ overrides/
│ └─ main.html
└─ mkdocs.yml
```
Then, e.g. to override the site title, add the following line to `main.html`:
``` html
{% extends "base.html" %}
{% block htmltitle %}
<title>Lorem ipsum dolor sit amet</title>
{% endblock %}
```
Material for MkDocs provides the following template blocks:
| Block name | Purpose |
|:------------------|:------------------------------------------------|
| `analytics` | Wraps the Google Analytics integration |
| `announce` | Wraps the announcement bar |
| `config` | Wraps the JavaScript application config |
| `content` | Wraps the main content |
| `disqus` | Wraps the Disqus integration |
| `extrahead` | Empty block to add custom meta tags |
| `fonts` | Wraps the font definitions |
| `footer` | Wraps the footer with navigation and copyright |
| `header` | Wraps the fixed header bar |
| `hero` | Wraps the hero teaser (if available) |
| `htmltitle` | Wraps the `<title>` tag |
| `libs` | Wraps the JavaScript libraries (header) |
| `outdated` | Wraps the version warning |
| `scripts` | Wraps the JavaScript application (footer) |
| `source` | Wraps the linked source files |
| `site_meta` | Wraps the meta tags in the document head |
| `site_nav` | Wraps the site navigation and table of contents |
| `styles` | Wraps the stylesheets (also extra sources) |
| `tabs` | Wraps the tabs navigation (if available) |
For more on this topic refer to the [MkDocs documentation][5].
[5]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
#### Additional variables
Besides template blocks, Material for MkDocs provides extra variables for parts
that cannot be overridden with template blocks (due to technical limitations of
the template engine). If you want to add further information after the _Made
with Material for MkDocs_ hint in the footer, add the following line to
`main.html`:
``` html
{% extends "base.html" %}
{% set extracopyright %}
<!-- Add your additional information here -->
{% endset %}
```
Material for MkDocs provides the following additional variables:
| Block name | Purpose |
|:------------------|:------------------------------------------------|
| `extracopyright` | Adds custom copyright information |
## Theme development
Material for MkDocs is built on top of [TypeScript][6], [RxJS][7] and [SASS][8],
and uses a lean, custom build process to put everything together.[^1] If you
want to make more fundamental changes, it may be necessary to make the
adjustments directly in the source of the theme and recompile it.
[^1]:
Prior to version 7.0, the build was based on Webpack. This led to broken
builds due to frequent incompatibilities with loaders and plugins, so we
decided to swap Webpack for a leaner custom solution which is now based on
[RxJS][7] as the application itself. This enabled us to remove more than
500 dependencies (~30% less).
[6]: https://www.typescriptlang.org/
[7]: https://github.com/ReactiveX/rxjs
[8]: https://sass-lang.com
### Environment setup
In order to start development on Material for MkDocs, a [Node.js][9] version of
at least 14 is required. First, clone the repository:
```
git clone https://github.com/squidfunk/mkdocs-material
```
Next, all dependencies need to be installed, which is done with:
```
cd mkdocs-material
pip install -r requirements.txt
pip install mkdocs-minify-plugin
pip install mkdocs-redirects
npm install
```
[9]: https://nodejs.org
### Development mode
Start the watcher with:
```
npm start
```
Then, in a second session, start the MkDocs server with:
```
mkdocs serve
```
Point your browser to [localhost:8000][10] and you should see this documentation
in front of you.
!!! warning "Automatically generated files"
Never make any changes in the `material` directory, as the contents of this
directory are automatically generated from the `src` directory and will be
overridden when the theme is built.
[10]: http://localhost:8000
### Building the theme
When you're finished making your changes, you can build the theme by invoking:
```
npm run build
```
This triggers the production-level compilation and minification of all
stylesheets and JavaScript sources. When the command exits, the final files are
located in the `material` directory. Add the `theme_dir` variable pointing to
the aforementioned directory in the original `mkdocs.yml`.
Now you can run `mkdocs build` and you should see your documentation with your
changes to the original theme.
---
template: overrides/main.html
---
# Data privacy
In itself, Material for MkDocs does not perform any tracking and should adhere
to the [General Data Protection Regulation][1] (GDPR), but it integrates with
some third-party services that may not.
[1]: https://en.wikipedia.org/wiki/General_Data_Protection_Regulation
## Third-party services
### Google Fonts
Material for MkDocs makes fonts [configurable][2] by relying on Google Fonts
CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily
disabled][3] via `mkdocs.yml`.
[2]: setup/changing-the-fonts.md
[3]: setup/changing-the-fonts.md#disabling-font-loading
### Google Analytics and Disqus
Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5]
integrations, both of which must be enabled explicitly, so there's no immediate
action if you don't use those.
[4]: setup/setting-up-site-analytics.md#google-analytics
[5]: setup/adding-a-comment-system.md#disqus
---
template: overrides/main.html
---
# Deprecations
This page includes a list of deprecations, indicating which features of Material
for MkDocs were replaced with newer, more flexible alternatives, and thus should
not be used anymore.
## Front matter
### Redirect
:octicons-archive-24: Deprecated: 5.5 ·
:octicons-trash-24: Removed: 6.0
The `redirect` key, which could be added via [Metadata][1], allowed to
specify a redirect from within a document to a new address, which is a good
idea when moving content around:
``` markdown
---
redirect: /path/to/new/file
---
```
The [redirects][2] plugin provides the ability to define redirect mappings via
`mkdocs.yml`, which is considered to be a much better solution to achieve the
same result. It can be installed with `pip`:
```
pip install mkdocs-redirects
```
Redirect mappings can then be added to `mkdocs.yml`:
``` yaml
plugins:
- redirects:
redirect_maps:
path/to/old/file.md: path/to/new/file.md
```
[1]: reference/meta-tags.md#metadata
[2]: https://github.com/datarobot/mkdocs-redirects
### Source link
:octicons-archive-24: Deprecated: 5.5 ·
:octicons-trash-24: Removed: 6.0
The `source` and `path` keys, which could be added via [Metadata][1], showed
a source icon at the top right corner of a document, linking a document to a
single source file:
``` markdown
---
path: tree/master/docs
source: deprecations.md
---
```
Only a single source file could be linked, which is useless if a document refers
to multiple files (or multiple sections within a single file). A more flexible
approach is to use the new [icon integration][3]:
``` markdown
[:octicons-file-code-24: Source](https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md)
```
This will render as [:octicons-file-code-24: Source][4], which can be included
at arbitrary positions in any document.
[3]: setup/changing-the-logo-and-icons.md#icons
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md
### Hero
:octicons-archive-24: Deprecated: 5.5 ·
:octicons-trash-24: Removed: 6.0
The `hero` key, which could be added via [Metadata][1], allowed to render a
simple, text-only and page-local teaser text as part of a document. It could
be set from front matter with:
``` markdown
---