mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Updated documentation
This commit is contained in:
squidfunk
parent
6acd637cb8
commit
6af95f942d
@ -499,7 +499,7 @@ digit `\d`, which leaves version numbers discoverable. Searching for
|
||||
[:octicons-search-24: 7.2.6][28] brings up the [7.2.6][29] release notes.
|
||||
|
||||
[28]: ?q=7.2.6
|
||||
[29]: ../../changelog.md#726-_-september-1-2021
|
||||
[29]: ../../changelog/index.md#726-_-september-1-2021
|
||||
|
||||
#### HTML/XML tags
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@ template: overrides/main.html
|
||||
|
||||
# Creating your site
|
||||
|
||||
After you've [installed][1] Material for MkDocs, you can bootstrap your project
|
||||
After you've [installed] 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:
|
||||
|
||||
@ -35,14 +35,14 @@ This will create the following structure:
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
[1]: getting-started.md
|
||||
[installed]: 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
|
||||
since there are several [installation methods], minimal configuration might be
|
||||
slightly different:
|
||||
|
||||
=== "pip, docker"
|
||||
@ -77,53 +77,53 @@ slightly different:
|
||||
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]._
|
||||
When you clone from GitHub, you must list all of the themes' defaults
|
||||
explicitly, because [`mkdocs_theme.yml`][mkdocs_theme.yml] is not
|
||||
loaded automatically as described in the [custom theme guide].
|
||||
|
||||
[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
|
||||
[installation methods]: getting-started.md#installation
|
||||
[mkdocs_theme.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/src/mkdocs_theme.yml
|
||||
[custom theme guide]: 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
|
||||
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>
|
||||
|
||||
- [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 social cards][12]
|
||||
- [Setting up tags][13]
|
||||
- [Setting up versioning][14]
|
||||
- [Setting up the header][15]
|
||||
- [Setting up the footer][16]
|
||||
- [Adding a git repository][17]
|
||||
- [Adding a comment system][18]
|
||||
- [Changing the colors]
|
||||
- [Changing the fonts]
|
||||
- [Changing the language]
|
||||
- [Changing the logo and icons]
|
||||
- [Setting up navigation]
|
||||
- [Setting up site search]
|
||||
- [Setting up site analytics]
|
||||
- [Setting up social cards]
|
||||
- [Setting up tags]
|
||||
- [Setting up versioning]
|
||||
- [Setting up the header]
|
||||
- [Setting up the footer]
|
||||
- [Adding a git repository]
|
||||
- [Adding a comment system]
|
||||
|
||||
</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-social-cards.md
|
||||
[13]: setup/setting-up-tags.md
|
||||
[14]: setup/setting-up-versioning.md
|
||||
[15]: setup/setting-up-the-header.md
|
||||
[16]: setup/setting-up-the-footer.md
|
||||
[17]: setup/adding-a-git-repository.md
|
||||
[18]: setup/adding-a-comment-system.md
|
||||
[Changing the colors]: setup/changing-the-colors.md
|
||||
[Changing the fonts]: setup/changing-the-fonts.md
|
||||
[Changing the language]: setup/changing-the-language.md
|
||||
[Changing the logo and icons]: setup/changing-the-logo-and-icons.md
|
||||
[Setting up navigation]: setup/setting-up-navigation.md
|
||||
[Setting up site search]: setup/setting-up-site-search.md
|
||||
[Setting up site analytics]: setup/setting-up-site-analytics.md
|
||||
[Setting up social cards]: setup/setting-up-social-cards.md
|
||||
[Setting up tags]: setup/setting-up-tags.md
|
||||
[Setting up versioning]: setup/setting-up-versioning.md
|
||||
[Setting up the header]: setup/setting-up-the-header.md
|
||||
[Setting up the footer]: setup/setting-up-the-footer.md
|
||||
[Adding a git repository]: setup/adding-a-git-repository.md
|
||||
[Adding a comment system]: setup/adding-a-comment-system.md
|
||||
|
||||
## Previewing as you write
|
||||
|
||||
@ -149,12 +149,12 @@ If you're running Material for MkDocs from within Docker, use:
|
||||
docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material
|
||||
```
|
||||
|
||||
Point your browser to [localhost:8000][19] and you should see:
|
||||
Point your browser to [localhost:8000][live preview] and you should see:
|
||||
|
||||
[![Creating your site][20]][20]
|
||||
[![Creating your site]][Creating your site]
|
||||
|
||||
[19]: http://localhost:8000
|
||||
[20]: assets/screenshots/creating-your-site.png
|
||||
[live preview]: http://localhost:8000
|
||||
[Creating your site]: assets/screenshots/creating-your-site.png
|
||||
|
||||
## Building your site
|
||||
|
||||
@ -167,8 +167,8 @@ 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][21], [GitLab Pages][22], a CDN of your
|
||||
choice or your private web space.
|
||||
The site can be hosted on [GitHub Pages], [GitLab Pages], a CDN of your choice
|
||||
or your private web space.
|
||||
|
||||
[21]: publishing-your-site.md#github-pages
|
||||
[22]: publishing-your-site.md#gitlab-pages
|
||||
[GitHub Pages]: publishing-your-site.md#github-pages
|
||||
[GitLab pages]: publishing-your-site.md#gitlab-pages
|
||||
|
||||
@ -11,11 +11,11 @@ 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.
|
||||
[MkDocs] provides several ways to customize a theme. In order to make a few
|
||||
small tweaks to Material for MkDocs, you can just CSS and JavaScript files to
|
||||
the `docs` directory.
|
||||
|
||||
[1]: https://www.mkdocs.org
|
||||
[MkDocs]: https://www.mkdocs.org
|
||||
|
||||
### Additional CSS
|
||||
|
||||
@ -31,23 +31,17 @@ new stylesheet file in the `docs` directory:
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
Then, add the following line to `mkdocs.yml`:
|
||||
Then, add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
```
|
||||
|
||||
Spin up the [live preview server][2] and start typing your changes in your
|
||||
additional style sheet 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:
|
||||
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
|
||||
.
|
||||
@ -57,30 +51,27 @@ JavaScript file in the `docs` directory:
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
Then, add the following line to `mkdocs.yml`:
|
||||
Then, add the following lines 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
|
||||
extend the theme. MkDocs supports [theme extension], 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
|
||||
[theme extension]: 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:
|
||||
for `overrides` which you then reference using the [`custom_dir`][custom_dir]
|
||||
setting:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
@ -90,16 +81,15 @@ theme:
|
||||
|
||||
!!! 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`.
|
||||
As the [`custom_dir`][custom_dir] setting is used for the theme extension
|
||||
process, Material for MkDocs needs to be installed via `pip` and referenced
|
||||
with the [`name`][name] setting 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:
|
||||
assets may also be put in the `overrides` directory:
|
||||
|
||||
``` sh
|
||||
.
|
||||
@ -123,8 +113,7 @@ The directory layout of the theme is as follows:
|
||||
│ ├─ 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
|
||||
│ ├─ source-file.html # Source file information
|
||||
│ ├─ tabs.html # Tabs navigation
|
||||
│ ├─ tabs-item.html # Tabs navigation item
|
||||
│ ├─ toc.html # Table of contents
|
||||
@ -134,11 +123,14 @@ The directory layout of the theme is as follows:
|
||||
└─ main.html # Default page
|
||||
```
|
||||
|
||||
[custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
|
||||
[name]: https://www.mkdocs.org/user-guide/configuration/#name
|
||||
|
||||
### 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`
|
||||
`footer.html` partial, create a new `footer.html` partial in the `overrides`
|
||||
directory:
|
||||
|
||||
``` sh
|
||||
@ -155,9 +147,9 @@ with any file.
|
||||
### Overriding blocks <small>recommended</small> { #overriding-blocks data-toc-label="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:
|
||||
template blocks, which are defined inside the templates and wrap specific
|
||||
features. In order to set up block overrides, create a `main.html` file inside
|
||||
the `overrides` directory:
|
||||
|
||||
``` sh
|
||||
.
|
||||
@ -166,7 +158,7 @@ directory:
|
||||
└─ mkdocs.yml
|
||||
```
|
||||
|
||||
Then, e.g. to override the site title, add the following line to `main.html`:
|
||||
Then, e.g. to override the site title, add the following lines to `main.html`:
|
||||
|
||||
``` html
|
||||
{% extends "base.html" %}
|
||||
@ -176,7 +168,7 @@ Then, e.g. to override the site title, add the following line to `main.html`:
|
||||
{% endblock %}
|
||||
```
|
||||
|
||||
Material for MkDocs provides the following template blocks:
|
||||
The following template blocks are provided by the theme:
|
||||
|
||||
| Block name | Purpose |
|
||||
|:------------------|:------------------------------------------------|
|
||||
@ -194,16 +186,11 @@ Material for MkDocs provides the following template blocks:
|
||||
| `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 style sheets (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
|
||||
@ -220,7 +207,7 @@ with Material for MkDocs_ hint in the footer, add the following line to
|
||||
{% endset %}
|
||||
```
|
||||
|
||||
Material for MkDocs provides the following additional variables:
|
||||
The following template variables are provided by the theme:
|
||||
|
||||
| Block name | Purpose |
|
||||
|:------------------|:------------------------------------------------|
|
||||
@ -228,25 +215,25 @@ Material for MkDocs provides the following additional variables:
|
||||
|
||||
## 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.
|
||||
Material for MkDocs is built on top of [TypeScript], [RxJS] and [SASS], 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).
|
||||
Prior to :octicons-tag-24: 7.0.0 the build was based on Webpack, resulting
|
||||
in occasional broken builds due to incompatibilities with loaders and
|
||||
plugins. Therefore, we decided to swap Webpack for a leaner solution which
|
||||
is now based on [RxJS] as the application itself. This allowed for the
|
||||
pruning of more than 500 dependencies (~30% less).
|
||||
|
||||
[6]: https://www.typescriptlang.org/
|
||||
[7]: https://github.com/ReactiveX/rxjs
|
||||
[8]: https://sass-lang.com
|
||||
[TypeScript]: https://www.typescriptlang.org/
|
||||
[RxJS]: https://github.com/ReactiveX/rxjs
|
||||
[SASS]: https://sass-lang.com
|
||||
|
||||
### Environment setup
|
||||
|
||||
In order to start development on Material for MkDocs, a [Node.js][9] version of
|
||||
In order to start development on Material for MkDocs, a [Node.js] version of
|
||||
at least 14 is required. First, clone the repository:
|
||||
|
||||
```
|
||||
@ -263,7 +250,7 @@ pip install mkdocs-redirects
|
||||
npm install
|
||||
```
|
||||
|
||||
[9]: https://nodejs.org
|
||||
[Node.js]: https://nodejs.org
|
||||
|
||||
### Development mode
|
||||
|
||||
@ -273,14 +260,14 @@ Start the watcher with:
|
||||
npm start
|
||||
```
|
||||
|
||||
Then, in a second session, start the MkDocs live preview server with:
|
||||
Then, in a second terminal window, start the MkDocs live preview server with:
|
||||
|
||||
```
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
Point your browser to [localhost:8000][10] and you should see this documentation
|
||||
in front of you.
|
||||
Point your browser to [localhost:8000][live preview] and you should see this
|
||||
very documentation in front of you.
|
||||
|
||||
!!! warning "Automatically generated files"
|
||||
|
||||
@ -288,7 +275,7 @@ in front of you.
|
||||
directory are automatically generated from the `src` directory and will be
|
||||
overwritten when the theme is built.
|
||||
|
||||
[10]: http://localhost:8000
|
||||
[live preview]: http://localhost:8000
|
||||
|
||||
### Building the theme
|
||||
|
||||
@ -298,10 +285,7 @@ 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.
|
||||
This triggers the production-level compilation and minification of all style
|
||||
sheets and JavaScript files. After the command exits, the compiled files are
|
||||
located in the `material` directory. When running `mkdocs build`, you should
|
||||
now see your changes to the original theme.
|
||||
|
||||
@ -1,31 +0,0 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Data privacy
|
||||
|
||||
In itself, Material for MkDocs does not perform any tracking and adheres 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#autoloading
|
||||
|
||||
### 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
|
||||
@ -5,17 +5,14 @@ title: Getting started
|
||||
|
||||
# Getting started
|
||||
|
||||
Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
|
||||
Material for MkDocs is a theme for [MkDocs], a static site generator geared
|
||||
towards (technical) project documentation. If you're familiar with Python, you
|
||||
can install Material for MkDocs with [`pip`][2], the Python package manager.
|
||||
If not, we recommended using [`docker`][3].
|
||||
can install Material for MkDocs with [`pip`][pip], the Python package manager.
|
||||
If not, we recommended using [`docker`][docker].
|
||||
|
||||
In case you're running into problems, consult the [troubleshooting][4] section.
|
||||
|
||||
[1]: https://www.mkdocs.org
|
||||
[2]: #with-pip-recommended
|
||||
[3]: #with-docker
|
||||
[4]: troubleshooting.md
|
||||
[MkDocs]: https://www.mkdocs.org
|
||||
[pip]: #with-pip
|
||||
[docker]: #with-docker
|
||||
|
||||
## Installation
|
||||
|
||||
@ -28,17 +25,17 @@ pip install mkdocs-material
|
||||
```
|
||||
|
||||
This will automatically install compatible versions of all dependencies:
|
||||
[MkDocs][1], [Markdown][5], [Pygments][6] and [Python Markdown Extensions][7].
|
||||
Material for MkDocs always strives to support the latest versions, so there's
|
||||
no need to install those packages separately.
|
||||
[MkDocs], [Markdown], [Pygments] and [Python Markdown Extensions]. Material for
|
||||
MkDocs always strives to support the latest versions, so there's no need to
|
||||
install those packages separately.
|
||||
|
||||
[5]: https://python-markdown.github.io/
|
||||
[6]: https://pygments.org/
|
||||
[7]: https://facelessuser.github.io/pymdown-extensions/
|
||||
[Markdown]: https://python-markdown.github.io/
|
||||
[Pygments]: https://pygments.org/
|
||||
[Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
|
||||
|
||||
### with docker
|
||||
|
||||
The official [Docker image][8] is a great way to get up and running in a few
|
||||
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:
|
||||
|
||||
@ -52,12 +49,12 @@ covered in the following sections.
|
||||
|
||||
The following plugins are bundled with the Docker image:
|
||||
|
||||
- [mkdocs-minify-plugin][9]
|
||||
- [mkdocs-redirects][10]
|
||||
- [mkdocs-minify-plugin]
|
||||
- [mkdocs-redirects]
|
||||
|
||||
[8]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
||||
[9]: https://github.com/byrnereese/mkdocs-minify-plugin
|
||||
[10]: https://github.com/datarobot/mkdocs-redirects
|
||||
[Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
||||
[mkdocs-minify-plugin]: https://github.com/byrnereese/mkdocs-minify-plugin
|
||||
[mkdocs-redirects]: https://github.com/datarobot/mkdocs-redirects
|
||||
|
||||
??? question "How to add plugins to the Docker image?"
|
||||
|
||||
@ -82,19 +79,19 @@ The following plugins are bundled with the Docker image:
|
||||
!!! info ":material-apple: Apple Silicon (M1) and :fontawesome-brands-raspberry-pi: Raspberry Pi"
|
||||
|
||||
The official Docker image is only available for `linux/amd64`. We recommend
|
||||
the [third-party image][11] by @afritzler if you want to run Material for
|
||||
MkDocs via Docker on `arm64` or `armv7`, as it is automatically built on
|
||||
every release:
|
||||
the [third-party image] by @afritzler if you want to run Material for MkDocs
|
||||
via Docker on `arm64` or `armv7`, as it is automatically built on every
|
||||
release:
|
||||
|
||||
```
|
||||
docker pull ghcr.io/afritzler/mkdocs-material
|
||||
```
|
||||
|
||||
[11]: https://github.com/afritzler/mkdocs-material
|
||||
[third-party image]: https://github.com/afritzler/mkdocs-material
|
||||
|
||||
### with git
|
||||
|
||||
Material for MkDocs can be directly used from [GitHub][12] by cloning the
|
||||
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:
|
||||
|
||||
@ -106,7 +103,7 @@ The theme will reside in the folder `mkdocs-material/material`. When cloning
|
||||
from `git`, you must install all required dependencies yourself:
|
||||
|
||||
```
|
||||
pip install -r mkdocs-material/requirements.txt
|
||||
pip install -e mkdocs-material
|
||||
```
|
||||
|
||||
[12]: https://github.com/squidfunk/mkdocs-material
|
||||
[GitHub]: https://github.com/squidfunk/mkdocs-material
|
||||
|
||||
@ -7,13 +7,13 @@ title: Switching to Insiders
|
||||
|
||||
Material for MkDocs Insiders is a fully compatible drop-in replacement for
|
||||
Material for MkDocs, and can be installed similar to the public version using
|
||||
[`pip`][1], [`docker`][2] or [`git`][3]. When you sponsor @squidfunk, your
|
||||
account is added to the list of collaborators of the private Insiders
|
||||
[`pip`][pip], [`docker`][docker] or [`git`][git]. When you sponsor @squidfunk,
|
||||
your account is added to the list of collaborators of the private Insiders
|
||||
repository.
|
||||
|
||||
[1]: #with-pip-recommended
|
||||
[2]: #with-docker
|
||||
[3]: #with-git
|
||||
[pip]: #with-pip
|
||||
[docker]: #with-docker
|
||||
[git]: #with-git
|
||||
|
||||
## Requirements
|
||||
|
||||
|
||||
@ -10,15 +10,15 @@ makes this ridiculously simple.
|
||||
|
||||
## GitHub Pages
|
||||
|
||||
If you're already hosting your code on GitHub, [GitHub Pages][1] is certainly
|
||||
If you're already hosting your code on GitHub, [GitHub Pages] is certainly
|
||||
the most convenient way to publish your project documentation. It's free of
|
||||
charge and pretty easy to set up.
|
||||
|
||||
[1]: https://pages.github.com/
|
||||
[GitHub Pages]: https://pages.github.com/
|
||||
|
||||
### with GitHub Actions
|
||||
|
||||
Using [GitHub Actions][2] you can automate the deployment of your project
|
||||
Using [GitHub Actions] you can automate the deployment of your project
|
||||
documentation. At the root of your repository, create a new GitHub Actions
|
||||
workflow, e.g. `.github/workflows/ci.yml`, and copy and paste the following
|
||||
contents:
|
||||
@ -49,7 +49,7 @@ contents:
|
||||
2. At some point, GitHub renamed `master` to `main`. If your default branch
|
||||
is named `master`, you can safely remove `main`, vice versa.
|
||||
|
||||
3. This is the place to install further [MkDocs plugins][3] or Markdown
|
||||
3. This is the place to install further [MkDocs plugins] or Markdown
|
||||
extensions with `pip` to be used during the build:
|
||||
|
||||
``` sh
|
||||
@ -80,24 +80,24 @@ contents:
|
||||
- run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
|
||||
- run: mkdocs gh-deploy --force
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GH_TOKEN }}
|
||||
GH_TOKEN: ${{ secrets.GH_TOKEN }} # (1)
|
||||
```
|
||||
|
||||
1. Remember to set the `GH_TOKEN` environment variable to the value of your
|
||||
[personal access token] when deploying [Insiders], which can be done
|
||||
using [GitHub secrets].
|
||||
|
||||
Now, when a new commit is pushed to either the `master` or `main` branches,
|
||||
the static site is automatically built and deployed. Push your changes to see
|
||||
the workflow in action.
|
||||
|
||||
Your documentation should shortly appear at `<username>.github.io/<repository>`.
|
||||
|
||||
_Remember to set the_ `GH_TOKEN` _environment variable to the value of your
|
||||
[personal access token][4] when deploying [Insiders][5], which can be done
|
||||
using [secrets][6]._
|
||||
|
||||
[2]: https://github.com/features/actions
|
||||
[3]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
|
||||
[4]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
|
||||
[5]: insiders/index.md
|
||||
[6]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
|
||||
[GitHub Actions]: https://github.com/features/actions
|
||||
[MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
|
||||
[personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
|
||||
[Insiders]: insiders/index.md
|
||||
[GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
|
||||
|
||||
### with MkDocs
|
||||
|
||||
@ -110,10 +110,10 @@ mkdocs gh-deploy --force
|
||||
|
||||
## GitLab Pages
|
||||
|
||||
If you're hosting your code on GitLab, deploying to [GitLab Pages][7] can be
|
||||
done by using the [GitLab CI][8] task runner. At the root of your repository,
|
||||
create a task definition named `.gitlab-ci.yml` and copy and paste the
|
||||
following contents:
|
||||
If you're hosting your code on GitLab, deploying to [GitLab Pages] can be done
|
||||
by using the [GitLab CI] task runner. At the root of your repository, create a
|
||||
task definition named `.gitlab-ci.yml` and copy and paste the following
|
||||
contents:
|
||||
|
||||
=== "Material for MkDocs"
|
||||
|
||||
@ -139,7 +139,7 @@ following contents:
|
||||
stage: deploy
|
||||
only:
|
||||
- master
|
||||
script:
|
||||
script: # (1)
|
||||
- pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
|
||||
- mkdocs build --site-dir public
|
||||
artifacts:
|
||||
@ -147,16 +147,16 @@ following contents:
|
||||
- public
|
||||
```
|
||||
|
||||
1. Remember to set the `GH_TOKEN` environment variable to the value of your
|
||||
[personal access token] when deploying [Insiders], which can be done
|
||||
using [masked custom variables].
|
||||
|
||||
Now, when a new commit is pushed to `master`, the static site is automatically
|
||||
built and deployed. Commit and push the file to your repository to see the
|
||||
workflow in action.
|
||||
|
||||
Your documentation should shortly appear at `<username>.gitlab.io/<repository>`.
|
||||
|
||||
_Remember to set the_ `GH_TOKEN` _environment variable to the value of your
|
||||
[personal access token][4] when deploying [Insiders][5], which can be done
|
||||
using [masked custom variables][9]._
|
||||
|
||||
[7]: https://gitlab.com/pages
|
||||
[8]: https://docs.gitlab.com/ee/ci/
|
||||
[9]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
|
||||
[GitLab Pages]: https://gitlab.com/pages
|
||||
[GitLab CI]: https://docs.gitlab.com/ee/ci/
|
||||
[masked custom variables]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui
|
||||
|
||||
@ -11,9 +11,14 @@ documents can be linked to specific source files.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Repository
|
||||
|
||||
[:octicons-tag-24: 0.1.0][repo_url support] ·
|
||||
:octicons-milestone-24: Default: _none_
|
||||
|
||||
In order to display a link to the repository of your project as part of your
|
||||
documentation, set [`repo_url`][1] in `mkdocs.yml` to the public URL of your
|
||||
repository, e.g.:
|
||||
documentation, set [`repo_url`][repo_url] in `mkdocs.yml` to the public URL of
|
||||
your repository, e.g.:
|
||||
|
||||
``` yaml
|
||||
repo_url: https://github.com/squidfunk/mkdocs-material
|
||||
@ -21,35 +26,38 @@ repo_url: https://github.com/squidfunk/mkdocs-material
|
||||
|
||||
The link to 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
|
||||
automatically requested and rendered for _public repositories_.
|
||||
Additionally, for public repositories hosted on [GitHub] or [GitLab], the
|
||||
number of stars and forks is automatically requested and rendered.
|
||||
|
||||
[1]: https://www.mkdocs.org/user-guide/configuration/#repo_url
|
||||
[repo_url support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url
|
||||
|
||||
### Repository name
|
||||
|
||||
[:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default:
|
||||
_automatically set to_ `GitHub`, `GitLab` _or_ `Bitbucket`
|
||||
[:octicons-tag-24: 0.1.0][repo_name support] ·
|
||||
:octicons-milestone-24: Default: _automatically set to_ `GitHub`, `GitLab` _or_
|
||||
`Bitbucket`
|
||||
|
||||
MkDocs will infer the source provider by examining the URL and try to set the
|
||||
_repository name_ automatically. If you wish to customize the name, set
|
||||
[`repo_name`][3] in `mkdocs.yml`:
|
||||
[`repo_name`][repo_name] in `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
repo_name: squidfunk/mkdocs-material
|
||||
```
|
||||
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source.html
|
||||
[3]: https://www.mkdocs.org/user-guide/configuration/#repo_name
|
||||
[repo_name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[repo_name]: https://www.mkdocs.org/user-guide/configuration/#repo_name
|
||||
|
||||
### Repository icon
|
||||
|
||||
[:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default:
|
||||
`fontawesome/brands/git-alt`
|
||||
[:octicons-tag-24: 5.0.0][icon.repo support] ·
|
||||
:octicons-milestone-24: Default:
|
||||
[`fontawesome/brands/git-alt`][icon.repo default]
|
||||
|
||||
While the default _repository icon_ is a generic git icon, it can be set to
|
||||
[any icon bundled with the theme][4] by referencing a valid icon path in
|
||||
`mkdocs.yml`:
|
||||
While the default repository icon is a generic git icon, it can be set to
|
||||
[any icon bundled with the theme][custom icons] by referencing a valid icon
|
||||
path in `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
@ -70,16 +78,18 @@ Some popular choices:
|
||||
- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
|
||||
- :fontawesome-solid-trash: – `fontawesome/solid/trash`
|
||||
|
||||
[4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||||
[icon.repo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
|
||||
[icon.repo default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg
|
||||
[custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
|
||||
|
||||
### Edit button
|
||||
|
||||
[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default:
|
||||
_automatically set_
|
||||
[:octicons-tag-24: 0.1.0][edit_uri support] ·
|
||||
:octicons-milestone-24: Default: _automatically set_
|
||||
|
||||
If the repository URL points to a [GitHub][6], [GitLab][7] or [Bitbucket][8]
|
||||
repository, an _edit button_ is displayed at the top of each document. This
|
||||
behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`:
|
||||
If the repository URL points to a [GitHub], [GitLab] or [Bitbucket] repository,
|
||||
an edit button is displayed at the top of each document. This behavior can be
|
||||
changed by setting [`edit_uri`][edit_uri] in `mkdocs.yml`:
|
||||
|
||||
=== "Customize edit path"
|
||||
|
||||
@ -93,39 +103,39 @@ behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`:
|
||||
edit_uri: ""
|
||||
```
|
||||
|
||||
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
|
||||
[6]: https://github.com/
|
||||
[7]: https://about.gitlab.com/
|
||||
[8]: https://bitbucket.org/
|
||||
[9]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
|
||||
[edit_uri support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[edit_uri]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
|
||||
[GitHub]: https://github.com/
|
||||
[GitLab]: https://about.gitlab.com/
|
||||
[Bitbucket]: https://bitbucket.org/
|
||||
|
||||
### Revision date
|
||||
|
||||
[:octicons-file-code-24: Source][10] ·
|
||||
[:octicons-cpu-24: Plugin][11]
|
||||
[:octicons-tag-24: 4.6.0][git-revision-date support] ·
|
||||
[:octicons-cpu-24: Plugin][git-revision-date]
|
||||
|
||||
The [git-revision-date][10] plugin adds support for displaying the date a
|
||||
document was _last updated_ at the bottom of each page. It can be installed
|
||||
The [git-revision-date] plugin adds support for displaying the date a
|
||||
document was last updated at the bottom of each page. It can be installed
|
||||
with `pip`:
|
||||
|
||||
```
|
||||
pip install mkdocs-git-revision-date-plugin
|
||||
```
|
||||
|
||||
Then, add the following to `mkdocs.yml`:
|
||||
Then, add the following lines to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
- git-revision-date
|
||||
```
|
||||
|
||||
The following options are supported:
|
||||
The following configuration options are supported:
|
||||
|
||||
`enabled_if_env`{ #enabled-if-env }
|
||||
|
||||
: :octicons-milestone-24: Default: _none_ – When specified the data will only be extracted from git
|
||||
if the environment variable exists. This makes it possible to disable
|
||||
extraction for cases when the repository is not available:
|
||||
: :octicons-milestone-24: Default: _none_ – When specified, the plugin will
|
||||
only be invoked if the environment variable exists. This makes it easy to
|
||||
disable extraction for cases when the repository is not available:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
@ -133,21 +143,21 @@ The following options are supported:
|
||||
enabled_if_env: CI
|
||||
```
|
||||
|
||||
_Material for MkDocs doesn't provide official support for the other options of
|
||||
this plugin, so they may be supported but might yield unexpected results.
|
||||
Use them at your own risk._
|
||||
The other configuration options of this extension are not officially supported
|
||||
by Material for MkDocs, which is why they may yield unexpected results. Use
|
||||
them at your own risk.
|
||||
|
||||
[10]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/source-date.html
|
||||
[11]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin
|
||||
[git-revision-date support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
|
||||
[git-revision-date]: https://github.com/zhaoterryy/mkdocs-git-revision-date-plugin
|
||||
|
||||
### Revision date, localized
|
||||
|
||||
[:octicons-file-code-24: Source][10] ·
|
||||
[:octicons-cpu-24: Plugin][12]
|
||||
[:octicons-tag-24: 4.6.0][git-revision-date-localized support] ·
|
||||
[:octicons-cpu-24: Plugin][git-revision-date-localized]
|
||||
|
||||
Similarly, the [git-revision-date-localized][12] plugin adds support for adding
|
||||
a localized _updated at_ and _created at_ date at the bottom of each page. It
|
||||
can be installed with `pip`:
|
||||
Similarly, the [git-revision-date-localized] plugin adds support for adding
|
||||
a localized update and creation date at the bottom of each page. It can be
|
||||
installed with `pip`:
|
||||
|
||||
```
|
||||
pip install mkdocs-git-revision-date-localized-plugin
|
||||
@ -160,7 +170,7 @@ plugins:
|
||||
- git-revision-date-localized
|
||||
```
|
||||
|
||||
The following options are supported:
|
||||
The following configuration options are supported:
|
||||
|
||||
`type`{ #type }
|
||||
|
||||
@ -178,7 +188,7 @@ The following options are supported:
|
||||
|
||||
: :octicons-milestone-24: Default: `false` – Enables falling back to
|
||||
the time when `mkdocs build` was executed. Can be used as a fallback when
|
||||
the build is performed outside of the git repository:
|
||||
the build is performed outside of a git repository:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
@ -189,8 +199,8 @@ The following options are supported:
|
||||
`enable_creation_date`{ #enable-creation-date }
|
||||
|
||||
: :octicons-milestone-24: Default: `false` – Enables the display of the
|
||||
_created at_ date of the file associated with the page next to the
|
||||
_updated at_ date at the bottom of the page:
|
||||
creation date of the file associated with the page next to the last updated
|
||||
date at the bottom of the page:
|
||||
|
||||
``` yaml
|
||||
plugins:
|
||||
@ -199,8 +209,9 @@ The following options are supported:
|
||||
```
|
||||
|
||||
|
||||
_Material for MkDocs doesn't provide official support for the other options of
|
||||
this plugin, so they may be supported but might yield unexpected results.
|
||||
Use them at your own risk._
|
||||
The other configuration options of this extension are not officially supported
|
||||
by Material for MkDocs, which is why they may yield unexpected results. Use
|
||||
them at your own risk.
|
||||
|
||||
[12]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
|
||||
[git-revision-date-localized support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
|
||||
[git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
|
||||
|
||||
@ -66,7 +66,7 @@ theme:
|
||||
font: false
|
||||
```
|
||||
|
||||
[data privacy]: ../data-privacy.md
|
||||
[data privacy]: https://developers.google.com/fonts/faq#what_does_using_the_google_fonts_api_mean_for_the_privacy_of_my_users
|
||||
[font=false support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
|
||||
|
||||
## Customization
|
||||
|
||||
@ -97,7 +97,7 @@ The following configuration options are available:
|
||||
|
||||
#### Caching <small>recommended</small> { #caching data-toc-label="Caching" }
|
||||
|
||||
The [built-in social cards plugin] automatically fetches the fonts you define
|
||||
The [built-in social cards] plugin automatically fetches the fonts you define
|
||||
in `mkdocs.yml` from Google Fonts, and uses them to render the text that is
|
||||
displayed on the social card. The font files and generated cards are both
|
||||
written to the `.cache` directory, which is used in subsequent builds to detect
|
||||
@ -131,12 +131,12 @@ whether the social cards need to be regenerated. You might want to:
|
||||
- run: mkdocs gh-deploy --force
|
||||
```
|
||||
|
||||
[built-in social cards plugin]: #built-in-social-cards
|
||||
[built-in social cards]: #built-in-social-cards
|
||||
[publishing guide]: ../publishing-your-site.md#with-github-actions
|
||||
|
||||
#### Meta tags
|
||||
|
||||
The [built-in social cards plugin] automatically sets all necessary `meta` tags,
|
||||
The [built-in social cards] plugin automatically sets all necessary `meta` tags,
|
||||
equivalent to the following two customizations, which you can set manually when
|
||||
you don't want to use it:
|
||||
|
||||
@ -179,8 +179,6 @@ you don't want to use it:
|
||||
```
|
||||
|
||||
[Twitter Cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
|
||||
[built-in social cards plugin]: ../setup/setting-up-social-cards.md#built-in-social-cards
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -54,7 +54,7 @@ The following configuration options are available:
|
||||
|
||||
### Adding tags
|
||||
|
||||
When both, the [built-in tags plugin] and [Metadata] extension are enabled,
|
||||
When both, the [built-in tags] plugin and [Metadata] extension are enabled,
|
||||
tags can be added for a document with custom front matter. Add the following
|
||||
lines at the top of a Markdown file:
|
||||
|
||||
@ -80,14 +80,14 @@ following screenshots:
|
||||
|
||||
[![Tag search preview]][Tag search preview]
|
||||
|
||||
[built-in tags plugin]: #built-in-tags
|
||||
[built-in tags]: #built-in-tags
|
||||
[Metadata]: extensions/python-markdown.md#metadata
|
||||
[Tags preview]: ../assets/screenshots/tags.png
|
||||
[Tag search preview]: ../assets/screenshots/tags-search.png
|
||||
|
||||
### Adding a tags index
|
||||
|
||||
The [built-in tags plugin] allows to define a file to render a [tags index]
|
||||
The [built-in tags] plugin allows to define a file to render a [tags index]
|
||||
[tags.tags_file], which can be any page that is part of the `nav` section. To
|
||||
add a tags index, create a page, e.g. `tags.md`:
|
||||
|
||||
|
||||
@ -1,117 +0,0 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
## Theme not recognized
|
||||
|
||||
Operating systems:
|
||||
:fontawesome-brands-apple:
|
||||
:fontawesome-brands-windows:
|
||||
:fontawesome-brands-linux:
|
||||
|
||||
!!! error "Error: Unrecognized theme"
|
||||
|
||||
``` sh
|
||||
mkdocs serve
|
||||
# => INFO - Building documentation...
|
||||
# => ERROR - Config value: 'theme'. Error: Unrecognised theme 'material'.
|
||||
# => ...
|
||||
# => ConfigurationError: Aborted with 1 Configuration Errors!
|
||||
```
|
||||
|
||||
If you run into this error, the most common reason is that you installed MkDocs
|
||||
through some package manager (e.g. `brew` 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.
|
||||
|
||||
## Inadequate permissions
|
||||
|
||||
Operating systems: :fontawesome-brands-apple:
|
||||
|
||||
!!! error "Error: Permission denied"
|
||||
|
||||
``` sh
|
||||
pip install mkdocs-material
|
||||
# => Could not install packages due to an EnvironmentError: [Errno 13] Permission denied: '...'
|
||||
# => Consider using the --user option or check the permissions.
|
||||
```
|
||||
|
||||
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 three possible solutions for this, the recommended one
|
||||
of which is to use virtual environments:
|
||||
|
||||
=== "Virtual environments"
|
||||
|
||||
If you're installing Material for MkDocs with `pip`, the easiest 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][1]. First, ensure that you have a Python version of 3 or
|
||||
higher installed:
|
||||
|
||||
```
|
||||
python --version
|
||||
```
|
||||
|
||||
If you're good to go, create and activate a virtual environment with:
|
||||
|
||||
```
|
||||
python -m venv venv
|
||||
source ./venv/bin/activate
|
||||
```
|
||||
|
||||
Note that the second `venv` is the name of the folder where to create the
|
||||
virtual environment – you may choose it as you like. Your terminal should
|
||||
now print `(venv)` before the prompt and the `python` executable should be
|
||||
located inside the folder you just created.
|
||||
|
||||
Next, [install Material for MkDocs][2] with `pip`, which will download and
|
||||
install all packages in the `venv` folder you just created, including MkDocs
|
||||
and its dependencies:
|
||||
|
||||
```
|
||||
pip install mkdocs-material
|
||||
```
|
||||
|
||||
Verify that MkDocs and Material for MkDocs were both installed correctly:
|
||||
|
||||
```
|
||||
mkdocs --version
|
||||
mkdocs serve --help
|
||||
```
|
||||
|
||||
MkDocs should list `material` as an option under the `--theme` flag. When
|
||||
you're finished working with MkDocs, you can exit the virtual environment
|
||||
with:
|
||||
|
||||
```
|
||||
deactivate
|
||||
```
|
||||
|
||||
=== "User space"
|
||||
|
||||
Provide the `--user` flag to the install command and `pip` will install the
|
||||
package in a user-site location. While this is not a global installation,
|
||||
it's still not isolated and may lead to problems when you use different
|
||||
versions of Material for MkDocs in other projects:
|
||||
|
||||
```
|
||||
pip install --user mkdocs-material
|
||||
```
|
||||
|
||||
=== "Upgrade Python"
|
||||
|
||||
Upgrade your Python installation by installing Python with [Homebrew][3].
|
||||
This should eliminate a lot of problems you will run into with `pip`. Yet,
|
||||
it's still not an isolated installation which may also lead to the same
|
||||
problems as installing in user space:
|
||||
|
||||
```
|
||||
brew upgrade python
|
||||
```
|
||||
|
||||
[1]: https://docs.python.org/3/tutorial/venv.html
|
||||
[2]: getting-started.md#with-pip-recommended
|
||||
[3]: https://brew.sh/
|
||||
@ -2,7 +2,7 @@
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Upgrading
|
||||
# How to upgrade
|
||||
|
||||
Upgrade to the latest version with:
|
||||
|
||||
@ -10,7 +10,7 @@ Upgrade to the latest version with:
|
||||
pip install --upgrade mkdocs-material
|
||||
```
|
||||
|
||||
Inspect the currently installed version with:
|
||||
Show the currently installed version with:
|
||||
|
||||
```
|
||||
pip show mkdocs-material
|
||||
File diff suppressed because one or more lines are too long
22
mkdocs.yml
22
mkdocs.yml
@ -91,18 +91,7 @@ plugins:
|
||||
- redirects:
|
||||
redirect_maps:
|
||||
changelog/insiders.md: insiders/changelog.md
|
||||
extensions/admonition.md: reference/admonitions.md
|
||||
extensions/codehilite.md: reference/code-blocks.md
|
||||
extensions/footnotes.md: reference/footnotes.md
|
||||
extensions/metadata.md: reference/meta-tags.md
|
||||
extensions/permalinks.md: setup/setting-up-navigation.md #permalink
|
||||
extensions/pymdown.md: reference/admonitions.md
|
||||
plugins/revision-date.md: setup/adding-a-git-repository.md #revision-date
|
||||
plugins/search.md: setup/setting-up-site-search.md
|
||||
releases/4.md: upgrading.md #upgrading-from-4x-to-5x
|
||||
releases/5.md: upgrading.md #upgrading-from-3x-to-4x
|
||||
releases/changelog.md: changelog.md
|
||||
setup/adding-social-links.md: setup/setting-up-the-footer.md
|
||||
upgrading.md: upgrade.md
|
||||
sponsorship.md: insiders/index.md
|
||||
- minify:
|
||||
minify_html: true
|
||||
@ -174,13 +163,10 @@ nav:
|
||||
- Creating your site: creating-your-site.md
|
||||
- Publishing your site: publishing-your-site.md
|
||||
- Customization: customization.md
|
||||
- Troubleshooting: troubleshooting.md
|
||||
- Data privacy: data-privacy.md
|
||||
- License: license.md
|
||||
- Releases:
|
||||
- Changelog: changelog.md
|
||||
- Upgrade guide: upgrading.md
|
||||
- Deprecations: deprecations.md
|
||||
- Changelog:
|
||||
- changelog/index.md
|
||||
- How to upgrade: upgrade.md
|
||||
- Setup:
|
||||
- Changing the colors: setup/changing-the-colors.md
|
||||
- Changing the fonts: setup/changing-the-fonts.md
|
||||
|
||||
Loading…
Reference in New Issue
Block a user