Cool_Tools/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-28 01:10:58 +01:00
Code Issues Releases Wiki Activity

Merge pull request #1735 from squidfunk/docs/restructure

Browse Source 
WIP – Restructure documentation
This commit is contained in:
Martin Donath 2020-07-22 19:15:23 +02:00 committed by GitHub
commit fb5cb9526f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
88 changed files with 3851 additions and 3352 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/ci.yml vendored
View File

@ -81,7 +81,9 @@ jobs:
- run: |
pip install -r requirements.txt
pip install .
pip install mkdocs-minify-plugin>=0.2
pip install \
mkdocs-minify-plugin>=0.3 \
mkdocs-redirects>=1.0
# Build documentation
- env:

2
CHANGELOG
View File

@ -10,7 +10,7 @@ mkdocs-material-5.3.3 (2020-06-24)
mkdocs-material-5.3.2 (2020-06-21)
* Improved search type-ahead experience with non-Latin characters
* Improved search typeahead experience with non-Latin characters
* Fixed #1753: Japanese search doesn't work anymore
mkdocs-material-5.3.1 (2020-06-20)

1
MANIFEST.in
View File

@ -1,5 +1,6 @@
recursive-include material *.js *.css *.map *.html *.svg *.png *.yml
recursive-include material *.ttf *.woff *.woff2 LICENSE*
recursive-exclude material/assets overrides*
recursive-exclude material/overrides *
recursive-exclude site *
recursive-exclude src *

BIN
docs/assets/creating-your-site.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 319 KiB

BIN
docs/assets/screenshots/creating-your-site.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 319 KiB

18
docs/releases/changelog.md → docs/changelog.md
View File

@ -2,21 +2,9 @@
template: overrides/main.html
---
# Upgrading
# Changelog
To upgrade to the latest version:
``` sh
pip install --upgrade mkdocs-material
```
To inspect the currently installed version:
``` sh
pip show mkdocs-material
```
## Changelog
## Release notes
### 5.4.0 <small>_ June 29, 2020</small>
@ -30,7 +18,7 @@ pip show mkdocs-material
### 5.3.2 <small>_ June 21, 2020</small>
* Improved search type-ahead experience with non-Latin characters
* Improved search typeahead experience with non-Latin characters
* Fixed #1753: Japanese search doesn't work anymore
### 5.3.1 <small>_ June 20, 2020</small>

5
docs/contributing.md
View File

@ -1,5 +0,0 @@
---
template: overrides/main.html
---
--8<-- "CONTRIBUTING.md"

140
docs/creating-your-site.md Normal file
View File

@ -0,0 +1,140 @@
---
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:
``` sh
mkdocs new .
```
Alternatively, if you're running Material for MkDocs from within Docker, use:
=== "Unix"
```
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
Depending on your [installation method][2], you can now add the following lines
to `mkdocs.yml` in your project root. If you installed Material for MkDocs using
`pip` or `docker`, add:
``` yaml
theme:
name: material
```
If you cloned Material for MkDocs from GitHub, add:
``` yaml
theme:
name: null
custom_dir: mkdocs-material/material
```
### Advanced configuration
Material for MkDocs comes with a lot of configuration options. The _guides_
section explains in great detail how to configure and customize colors, fonts,
icons and much more:
* [Changing the colors][3]
* [Changing the fonts][4]
* [Changing the language][5]
* [Changing the logo and icons][6]
* [Setting up navigation][7]
* [Setting up site search][8]
* [Setting up site analytics][9]
* [Adding social links][10]
* [Adding a git repository][11]
* [Adding a comment system][12]
<!-- * [Adding an announcement bar][13] -->
<!-- * [Adding a landing page][14] -->
[2]: getting-started.md#installation
[3]: setup/changing-the-colors.md
[4]: setup/changing-the-fonts.md
[5]: setup/changing-the-language.md
[6]: setup/changing-the-logo-and-icons.md
[7]: setup/setting-up-navigation.md
[8]: setup/setting-up-site-search.md
[9]: setup/setting-up-site-analytics.md
[10]: setup/adding-social-links.md
[11]: setup/adding-a-git-repository.md
[12]: setup/adding-a-comment-system.md
<!-- [13]: setup/adding-an-announcement-bar.md -->
<!--[14]: setup/adding-a-landing-page.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"
```
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][15] and you should see:
[![Creating your site][16]][15]
[15]: http://localhost:8000
[16]: assets/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][17], [GitLab Pages][18], a CDN of your
choice or your private web space.
[17]: publishing-your-site.md#github-pages
[18]: publishing-your-site.md#gitlab-pages

106
docs/customization.md
View File

@ -4,8 +4,6 @@ template: overrides/main.html
# Customization
## A great starting point
Project documentation is as diverse as the projects themselves and Material for
MkDocs is a good starting point for making it look great. However, as you write
your documentation, you may reach a point where some small adjustments are
@ -13,9 +11,9 @@ necessary to preserve your brand's style.
## Adding assets
[MkDocs][1] provides several ways to interfere with themes. In order to make a
few tweaks to an existing theme, you can just add your stylesheets and
JavaScript files to the `docs` directory.
[MkDocs][1] provides several ways to customize a theme. In order to make a few
tweaks to an existing theme, you can just add your stylesheets and JavaScript
files to the `docs` directory.
[1]: https://www.mkdocs.org
@ -23,58 +21,59 @@ JavaScript files to the `docs` directory.
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 your `docs` directory:
new stylesheet file in the `docs` directory:
``` sh
mkdir docs/stylesheets
touch docs/stylesheets/extra.css
```
Then, add the following line to your `mkdocs.yml`:
Then, add the following line to `mkdocs.yml`:
``` yaml
extra_css:
- stylesheets/extra.css
```
Spin up the development server with `mkdocs serve` and start typing your
changes in your additional stylesheet file – you can see them instantly after
saving, as the MkDocs development server supports live reloading.
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 your `docs` directory:
JavaScript file in the `docs` directory:
``` sh
mkdir docs/javascripts
touch docs/javascripts/extra.js
```
Then, add the following line to your `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][2].
Further assistance can be found in the [MkDocs documentation][3].
[2]: https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme
[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 part), you can
extend the theme. MkDocs supports [theme extension][3], an easy way to override
extend the theme. MkDocs supports [theme extension][4], an easy way to override
parts of a theme without forking and changing the main theme.
[3]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
[4]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
### Setup and theme structure
Reference the Material theme as usual in your `mkdocs.yml`, and create a
new folder for `overrides` which you reference using `custom_dir`:
Reference the original theme as usual in `mkdocs.yml`, and create a new folder
for `overrides` which you reference using `custom_dir`:
``` yaml
theme:
@ -84,9 +83,9 @@ theme:
!!! warning "Theme extension prerequisites"
As the `custom_dir` variable is used for the theme extension process, the
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 your `mkdocs.yml`.
`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
@ -97,28 +96,33 @@ 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/ # 3rd-party integrations
│ ├─ integrations/ # Third-party integrations
│ │ ├─ analytics.html # - Google Analytics
│ │ └─ disqus.html # - Disqus
│ ├─ language/ # Localized languages
│ ├─ footer.html # Footer bar
│ ├─ header.html # Header bar
│ ├─ hero.html # Hero teaser
│ ├─ language.html # Localized labels
│ ├─ nav-item.html # Main navigation item
│ ├─ 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
│ ├─ source.html # Repository information
│ ├─ tabs-item.html # Tabs navigation item
│ ├─ tabs.html # Tabs navigation
│ ├─ toc-item.html # Table of contents item
│ └─ toc.html # Table of contents
│ ├─ 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
@ -131,12 +135,12 @@ our own partial. To do this, create the file `partials/footer.html` in the
`overrides` directory. MkDocs will now use the new partial when rendering the
theme. This can be done with any file.
### Overriding template blocks
### Overriding blocks
Besides overriding partials, one can also override so called *template blocks*,
which are defined inside the templates and wrap specific features. To override a
template block, create a `main.html` inside the `overrides` directory and define
the block, e.g.:
Besides overriding partials, it's also possible to override (and extend) so
called _blocks_, which are defined inside the templates and wrap specific
features. To override a block, create a `main.html` inside the `overrides`
directory and define the block, e.g.:
``` jinja
{% extends "base.html" %}
@ -151,12 +155,12 @@ Material for MkDocs provides the following template blocks:
| Block name | Wrapped contents |
| ------------ | ----------------------------------------------- |
| `analytics` | Wraps the Google Analytics integration |
| `announce` | Wraps the Announcement bar |
| `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 define additional meta tags |
| `fonts` | Wraps the webfont definitions |
| `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) |
@ -169,24 +173,24 @@ Material for MkDocs provides the following template blocks:
| `styles` | Wraps the stylesheets (also extra sources) |
| `tabs` | Wraps the tabs navigation (if available) |
For more on this topic refer to the [MkDocs documentation][4]
For more on this topic refer to the [MkDocs documentation][5].
[4]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
[5]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
## Theme development
Material for MkDocs uses [Webpack][5] as a build tool to leverage modern web
technologies like [TypeScript][6] and [SASS][7]. If you want to make more
Material for MkDocs uses [Webpack][6] as a build tool to leverage modern web
technologies like [TypeScript][7] and [SASS][8]. 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. This is fairly easy.
the source of the theme and recompile it.
[5]: https://webpack.js.org/
[6]: https://www.typescriptlang.org/
[7]: https://sass-lang.com
[6]: https://webpack.js.org/
[7]: https://www.typescriptlang.org/
[8]: https://sass-lang.com
### Environment setup
In order to start development on Material for MkDocs, a [Node.js][8] version of
In order to start development on Material for MkDocs, a [Node.js][9] version of
at least 12 is required. First, clone the repository:
``` sh
@ -198,10 +202,11 @@ Next, all dependencies need to be installed, which is done with:
``` sh
cd mkdocs-material
pip install -r requirements.txt
pip install mkdocs-minify-plugin
npm install
```
[8]: https://nodejs.org
[9]: https://nodejs.org
### Development mode
@ -217,7 +222,8 @@ Then, in a second session, start the MkDocs server with:
mkdocs serve
```
Point your browser to [localhost:8000][9] and you should see this documentation in front of you.
Point your browser to [localhost:8000][10] and you should see this documentation
in front of you.
!!! warning "Automatically generated files"
@ -225,11 +231,11 @@ Point your browser to [localhost:8000][9] and you should see this documentation
directory are automatically generated from the `src` directory and will be
overridden when the theme is built.
[9]: http://localhost:8000
[10]: http://localhost:8000
### Build process
### Building the theme
When you've finished making your changes, you can build the theme by invoking:
When you're finished making your changes, you can build the theme by invoking:
``` sh
npm run build
@ -238,7 +244,7 @@ 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 your original `mkdocs.yml`.
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.

8
docs/data-privacy.md
View File

@ -25,14 +25,14 @@ theme:
font: false
```
When Google Fonts are disabled, Material for MkDocs will default to **Helvetica
Neue** and **Monaco** with their corresponding fall backs, relying on system
When Google Fonts are disabled, Material for MkDocs will default to __Helvetica
Neue__ and __Monaco__ with their corresponding fall backs, relying on system
fonts. You can easily include your own, self-hosted webfont by [overriding][4]
the `fonts` block.
[2]: getting-started.md#fonts
[2]: setup/changing-the-fonts.md
[3]: https://github.com/google/fonts/issues/1495
[4]: customization.md#overriding-template-blocks
[4]: customization.md#overriding-blocks
### Google Analytics and Disqus

459
docs/extensions/admonition.md
View File

@ -1,459 +0,0 @@
---
template: overrides/main.html
---
# Admonition
[Admonition][1] is an extension included in the standard Markdown library that
makes it possible to add block-styled side content to your documentation, e.g.
summaries, notes, hints or warnings.
[1]: https://python-markdown.github.io/extensions/admonition/
## Configuration
Add the following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- admonition
```
## Usage
Admonitions follow a simple syntax: every block is started with `!!!`, followed
by a single keyword which is used as the [type qualifier][2] of the block. The
content of the block then follows on the next line, indented by four spaces.
Example:
``` markdown
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[2]: #types
### Changing the title
By default, the Admonition title will equal the type qualifier in titlecase.
However, it can be changed by adding a quoted string after the type qualifier.
Example:
``` markdown
!!! note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
### Removing the title
Similar to [changing the title][3], the icon and title can be omitted by
providing an empty string after the type qualifier:
Example:
``` markdown
!!! note ""
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! note ""
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[3]: #changing-the-title
### Embedded content
Admonitions can contain all kinds of text content, including headlines, lists,
paragraphs and other blocks – except code blocks, because the parser from the
standard Markdown library does not account for those.
The [PyMdown Extensions][4] package adds an extension called [SuperFences][5],
which makes it possible to nest code blocks within other blocks, respectively
Admonition blocks.
[4]: https://facelessuser.github.io/pymdown-extensions
[5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
Example:
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
``` mysql
SELECT
Employees.EmployeeID,
Employees.Name,
Employees.Salary,
Manager.Name AS Manager
FROM
Employees
LEFT JOIN
Employees AS Manager
ON
Employees.ManagerID = Manager.EmployeeID
WHERE
Employees.EmployeeID = '087652';
```
Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
### Collapsible blocks
The [Details][6] extension which is also part of the [PyMdown Extensions][4]
package adds support for rendering collapsible Admonition blocks. This is
useful for FAQs or content that is of secondary nature.
Example:
``` markdown
??? note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
??? note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
By adding a `+` sign directly after the start marker, blocks can be rendered
open by default.
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
## Types
Admonition supports user-defined type qualifiers which may influence the style
of the inserted block. Following is a list of type qualifiers provided by
Material for MkDocs, whereas the default type, and thus fallback for unknown
type qualifiers, is `note`.
### Note
Example:
``` markdown
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `note`
* `seealso`
### Abstract
Example:
``` markdown
!!! abstract
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! abstract
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `abstract`
* `summary`
* `tldr`
### Info
Example:
``` markdown
!!! info
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! info
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `info`
* `todo`
### Tip
Example:
``` markdown
!!! tip
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! tip
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `tip`
* `hint`
* `important`
### Success
Example:
``` markdown
!!! success
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! success
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `success`
* `check`
* `done`
### Question
Example:
``` markdown
!!! question
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! question
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `question`
* `help`
* `faq`
### Warning
Example:
``` markdown
!!! warning
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! warning
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `warning`
* `caution`
* `attention`
### Failure
Example:
``` markdown
!!! failure
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! failure
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `failure`
* `fail`
* `missing`
### Danger
Example:
``` markdown
!!! danger
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! danger
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `danger`
* `error`
### Bug
Example:
``` markdown
!!! bug
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! bug
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `bug`
### Example
Example:
``` markdown
!!! example
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! example
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `example`
### Quote
Example:
``` markdown
!!! quote
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
!!! quote
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Qualifiers:
* `quote`
* `cite`

966
docs/extensions/codehilite.md
View File

@ -1,966 +0,0 @@
---
template: overrides/main.html
---
# CodeHilite
[CodeHilite][1] is an extension that adds syntax highlighting to code blocks
and is included in the standard Markdown library. It uses [Pygments][2] during
the compilation of the Markdown file to provide syntax highlighting for over
[300 languages][3] and has no JavaScript runtime dependency.
[1]: https://python-markdown.github.io/extensions/code_hilite/
[2]: https://pygments.org
[3]: http://pygments.org/languages
## Configuration
Add the following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- codehilite
```
## Usage
### Specifying the language
The CodeHilite extension uses the same syntax as regular Markdown code blocks,
but needs to know the language of the code block. This can be done in three
different ways.
#### via Markdown syntax <small>recommended</small>
In Markdown, code blocks can be opened and closed by writing three backticks on
separate lines. To add code highlighting to those blocks, the easiest way is
to specify the language identifier directly after the opening block.
Example:
```` markdown
``` python
import tensorflow as tf
```
````
Result:
``` python
import tensorflow as tf
```
#### via Shebang
Alternatively, if the first line of a code block contains a shebang, the
language is derived from the path referenced in the shebang. This will only
work for code blocks that are indented using four spaces, not for those
encapsulated in three backticks.
Example:
```` markdown
#!/usr/bin/python
import tensorflow as tf
````
Result:
``` python
#!/usr/bin/python
import tensorflow as tf
```
#### via three colons
If the first line starts with three colons followed by a language identifier,
the first line is stripped. This will only work for code blocks that are
indented using four spaces, not for those encapsulated in three backticks.
Example:
``` markdown
:::python
import tensorflow as tf
```
Result:
:::python
import tensorflow as tf
### Adding line numbers
Line numbers can be added to a code block by enabling the `linenums` flag in
`mkdocs.yml` or adding `linenums=1` right after the language identifier:
``` yaml
markdown_extensions:
- codehilite:
linenums: true
```
Example:
```` markdown
``` python linenums="1"
""" Bubble sort """
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
````
Result:
``` python linenums="1"
""" Bubble sort """
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
### Grouping code blocks
The [Tabbed][4] extension which is part of the [PyMdown Extensions][5]
package adds support for grouping Markdown blocks with tabs. This is especially
useful for documenting projects with multiple language bindings.
Add the Tabbed and SuperFences extensions to `mkdocs.yml`:
``` yaml
markdown_extensions:
- codehilite
- pymdownx.tabbed
- pymdownx.superfences
```
Add your tabbed code to your markdown file. Example:
````
=== "Bash"
``` bash
#!/bin/bash
echo "Hello world!"
```
=== "C"
``` c
#include <stdio.h>
int main(void) {
printf("Hello world!\n");
return 0;
}
```
=== "C++"
``` c++
#include <iostream>
int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}
```
=== "C#"
``` c#
using System;
class Program {
static void Main(string[] args) {
Console.WriteLine("Hello world!");
}
}
```
````
Result:
=== "Bash"
``` bash
#!/bin/bash
echo "Hello world!"
```
=== "C"
``` c
#include <stdio.h>
int main(void) {
printf("Hello world!\n");
return 0;
}
```
=== "C++"
``` c++
#include <iostream>
int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}
```
=== "C#"
``` c#
using System;
class Program {
static void Main(string[] args) {
Console.WriteLine("Hello world!");
}
}
```
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
[5]: https://facelessuser.github.io/pymdown-extensions
### Highlighting specific lines
Specific lines can be highlighted by passing the line numbers to the `hl_lines`
argument placed right after the language identifier. Line counts start at 1.
Example:
```` markdown
``` python hl_lines="3 4"
""" Bubble sort """
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
````
Result:
``` python linenums="1" hl_lines="3 4"
""" Bubble sort """
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
## Supported languages <small>excerpt</small>
CodeHilite uses [Pygments][2], a generic syntax highlighter with support for
over [300 languages][3], so the following list of examples is just an excerpt.
### Bash
``` bash
#!/bin/bash
for OPT in "$@"
do
case "$OPT" in
'-f' ) canonicalize=1 ;;
'-n' ) switchlf="-n" ;;
esac
done
# readlink -f
function __readlink_f {
target="$1"
while test -n "$target"; do
filepath="$target"
cd `dirname "$filepath"`
target=`readlink "$filepath"`
done
/bin/echo $switchlf `pwd -P`/`basename "$filepath"`
}
if [ ! "$canonicalize" ]; then
readlink $switchlf "$@"
else
for file in "$@"
do
case "$file" in
-* ) ;;
* ) __readlink_f "$file" ;;
esac
done
fi
exit $?
```
### C
``` c
extern size_t
pb_varint_scan(const uint8_t data[], size_t left) {
assert(data && left);
left = left > 10 ? 10 : left;
#ifdef __SSE2__
/* Mapping: remaining bytes ==> bitmask */
static const int mask_map[] = {
0x0000, 0x0001, 0x0003, 0x0007,
0x000F, 0x001F, 0x003F, 0x007F,
0x00FF, 0x01FF, 0x03FF
};
/* Load buffer into 128-bit integer and create high-bit mask */
__m128i temp = _mm_loadu_si128((const __m128i *)data);
__m128i high = _mm_set1_epi8(0x80);
/* Intersect and extract mask with high-bits set */
int mask = _mm_movemask_epi8(_mm_and_si128(temp, high));
mask = (mask & mask_map[left]) ^ mask_map[left];
/* Count trailing zeroes */
return mask ? __builtin_ctz(mask) + 1 : 0;
#else
/* Linear scan */
size_t size = 0;
while (data[size++] & 0x80)
if (!--left)
return 0;
return size;
#endif /* __SSE2__ */
}
```
### C++
``` cpp
Extension::
Extension(const Descriptor *descriptor, const Descriptor *scope) :
descriptor_(descriptor),
scope_(scope) {
/* Extract full name for signature */
variables_["signature"] = descriptor_->full_name();
/* Prepare message symbol */
variables_["message"] = StringReplace(
variables_["signature"], ".", "_", true);
LowerString(&(variables_["message"]));
/* Suffix scope to identifiers, if given */
string suffix ("");
if (scope_) {
suffix = scope_->full_name();
/* Check if the base and extension types are in the same package */
if (!scope_->file()->package().compare(descriptor_->file()->package()))
suffix = StripPrefixString(suffix,
scope_->file()->package() + ".");
/* Append to signature */
variables_["signature"] += ".[" + suffix +"]";
suffix = "_" + suffix;
}
/* Prepare extension symbol */
variables_["extension"] = StringReplace(
suffix, ".", "_", true);
LowerString(&(variables_["extension"]));
}
```
### C&#35;
``` csharp
public static void Send(
Socket socket, byte[] buffer, int offset, int size, int timeout) {
int startTickCount = Environment.TickCount;
int sent = 0;
do {
if (Environment.TickCount > startTickCount + timeout)
throw new Exception("Timeout.");
try {
sent += socket.Send(buffer, offset + sent,
size - sent, SocketFlags.None);
} catch (SocketException ex) {
if (ex.SocketErrorCode == SocketError.WouldBlock ||
ex.SocketErrorCode == SocketError.IOPending ||
ex.SocketErrorCode == SocketError.NoBufferSpaceAvailable) {
/* Socket buffer is probably full, wait and try again */
Thread.Sleep(30);
} else {
throw ex;
}
}
} while (sent < size);
}
```
### Clojure
``` clojure
(clojure-version)
(defn partition-when
[f]
(fn [rf]
(let [a (java.util.ArrayList.)
fval (volatile! false)]
(fn
([] (rf))
([result]
(let [result (if (.isEmpty a)
result
(let [v (vec (.toArray a))]
;; Clear first
(.clear a)
(unreduced (rf result v))))]
(rf result)))
([result input]
(if-not (and (f input) @fval)
(do
(vreset! fval true)
(.add a input)
result)
(let [v (vec (.toArray a))]
(.clear a)
(let [ret (rf result v)]
(when-not (reduced? ret)
(.add a input))
ret))))))))
(into [] (partition-when
#(.startsWith % ">>"))
["1d" "33" ">> 1" ">> 2" "22" ">> 3"])
```
### Diff
``` diff
Index: grunt.js
===================================================================
--- grunt.js (revision 31200)
+++ grunt.js (working copy)
@@ -12,6 +12,7 @@
module.exports = function (grunt) {
+ console.log('hello world');
// Project configuration.
grunt.initConfig({
lint: {
@@ -19,10 +20,6 @@
'packages/services.web/{!(test)/**/,}*.js',
'packages/error/**/*.js'
],
- scripts: [
- 'grunt.js',
- 'db/**/*.js'
- ],
browser: [
'packages/web/server.js',
'packages/web/server/**/*.js',
```
### Docker
``` docker
FROM ubuntu
# Install vnc, xvfb in order to create a 'fake' display and firefox
RUN apt-get update && apt-get install -y x11vnc xvfb firefox
RUN mkdir ~/.vnc
# Setup a password
RUN x11vnc -storepasswd 1234 ~/.vnc/passwd
# Autostart firefox (might not be the best way, but it does the trick)
RUN bash -c 'echo "firefox" >> /.bashrc'
EXPOSE 5900
CMD ["x11vnc", "-forever", "-usepw", "-create"]
```
### Elixir
``` elixir
require Logger
def accept(port) do
{:ok, socket} = :gen_tcp.listen(port,
[:binary, packet: :line, active: false, reuseaddr: true])
Logger.info "Accepting connections on port #{port}"
loop_acceptor(socket)
end
defp loop_acceptor(socket) do
{:ok, client} = :gen_tcp.accept(socket)
serve(client)
loop_acceptor(socket)
end
defp serve(socket) do
socket
|> read_line()
|> write_line(socket)
serve(socket)
end
defp read_line(socket) do
{:ok, data} = :gen_tcp.recv(socket, 0)
data
end
defp write_line(line, socket) do
:gen_tcp.send(socket, line)
end
```
### Erlang
``` erlang
circular(Defs) ->
[ { { Type, Base }, Fields } ||
{ { Type, Base }, Fields } <- Defs, Type == msg, circular(Base, Defs) ].
circular(Base, Defs) ->
Fields = proplists:get_value({ msg, Base }, Defs),
circular(Defs, Fields, [Base]).
circular(_Defs, [], _Path) ->
false;
circular(Defs, [Field | Fields], Path) ->
case Field#field.type of
{ msg, Type } ->
case lists:member(Type, Path) of
false ->
Children = proplists:get_value({ msg, Type }, Defs),
case circular(Defs, Children, [Type | Path]) of
false -> circular(Defs, Fields, Path);
true -> true
end;
true ->
Type == lists:last(Path) andalso
(length(Path) == 1 orelse not is_tree(Path))
end;
_ ->
circular(Defs, Fields, Path)
end.
```
### F&#35;
``` fsharp
/// Asynchronously download retangles from the server
/// and decode the JSON format to F# Rectangle record
let [<Js>] getRectangles () : Async<Rectangle[]> = async {
let req = XMLHttpRequest()
req.Open("POST", "/get", true)
let! resp = req.AsyncSend()
return JSON.parse(resp) }
/// Repeatedly update rectangles after 0.5 sec
let [<Js>] updateLoop () = async {
while true do
do! Async.Sleep(500)
let! rects = getRectangles()
cleanRectangles()
rects |> Array.iter createRectangle }
```
### Go
``` go
package main
import "fmt"
func counter(id int, channel chan int, closer bool) {
for i := 0; i < 10000000; i++ {
fmt.Println("process", id," send", i)
channel <- 1
}
if closer { close(channel ) }
}
func main() {
channel := make(chan int)
go counter(1, channel, false)
go counter(2, channel, true)
x := 0
// receiving data from channel
for i := range channel {
fmt.Println("receiving")
x += i
}
fmt.Println(x)
}
```
### HTML
``` html
<!doctype html>
<html class="no-js" lang="">
<head>
<meta charset="utf-8">
<meta http-equiv="x-ua-compatible" content="ie=edge">
<title>HTML5 Boilerplate</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="apple-touch-icon" href="apple-touch-icon.png">
<link rel="stylesheet" href="css/normalize.css">
<link rel="stylesheet" href="css/main.css">
<script src="js/vendor/modernizr-2.8.3.min.js"></script>
</head>
<body>
<p>Hello world! This is HTML5 Boilerplate.</p>
</body>
</html>
```
### Java
``` java
import java.util.LinkedList;
import java.lang.reflect.Array;
public class UnsortedHashSet<E> {
private static final double LOAD_FACTOR_LIMIT = 0.7;
private int size;
private LinkedList<E>[] con;
public UnsortedHashSet() {
con = (LinkedList<E>[])(new LinkedList[10]);
}
public boolean add(E obj) {
int oldSize = size;
int index = Math.abs(obj.hashCode()) % con.length;
if (con[index] == null)
con[index] = new LinkedList<E>();
if (!con[index].contains(obj)) {
con[index].add(obj);
size++;
}
if (1.0 * size / con.length > LOAD_FACTOR_LIMIT)
resize();
return oldSize != size;
}
private void resize() {
UnsortedHashSet<E> temp = new UnsortedHashSet<E>();
temp.con = (LinkedList<E>[])(new LinkedList[con.length * 2 + 1]);
for (int i = 0; i < con.length; i++) {
if (con[i] != null)
for (E e : con[i])
temp.add(e);
}
con = temp.con;
}
public int size() {
return size;
}
}
```
### JavaScript
``` javascript
var Math = require('lib/math');
var _extends = function (target) {
for (var i = 1; i < arguments.length; i++) {
var source = arguments[i];
for (var key in source) {
target[key] = source[key];
}
}
return target;
};
var e = exports.e = 2.71828182846;
exports['default'] = function (x) {
return Math.exp(x);
};
module.exports = _extends(exports['default'], exports);
```
### JSON
``` json
{
"name": "mkdocs-material",
"version": "0.2.4",
"description": "A Material Design theme for MkDocs",
"homepage": "http://squidfunk.github.io/mkdocs-material/",
"authors": [
"squidfunk <martin.donath@squidfunk.com>"
],
"license": "MIT",
"main": "Gulpfile.js",
"scripts": {
"start": "./node_modules/.bin/gulp watch --mkdocs",
"build": "./node_modules/.bin/gulp build --production"
}
...
}
```
### Julia
``` julia
using MXNet
mlp = @mx.chain mx.Variable(:data) =>
mx.FullyConnected(name=:fc1, num_hidden=128) =>
mx.Activation(name=:relu1, act_type=:relu) =>
mx.FullyConnected(name=:fc2, num_hidden=64) =>
mx.Activation(name=:relu2, act_type=:relu) =>
mx.FullyConnected(name=:fc3, num_hidden=10) =>
mx.SoftmaxOutput(name=:softmax)
# data provider
batch_size = 100
include(Pkg.dir("MXNet", "examples", "mnist", "mnist-data.jl"))
train_provider, eval_provider = get_mnist_providers(batch_size)
# setup model
model = mx.FeedForward(mlp, context=mx.cpu())
# optimization algorithm
optimizer = mx.SGD(lr=0.1, momentum=0.9)
# fit parameters
mx.fit(model, optimizer, train_provider, n_epoch=20, eval_data=eval_provider)
```
### Lua
``` lua
local ffi = require("ffi")
ffi.cdef[[
void Sleep(int ms);
int poll(struct pollfd *fds, unsigned long nfds, int timeout);
]]
local sleep
if ffi.os == "Windows" then
function sleep(s)
ffi.C.Sleep(s*1000)
end
else
function sleep(s)
ffi.C.poll(nil, 0, s * 1000)
end
end
for i = 1,160 do
io.write("."); io.flush()
sleep(0.01)
end
io.write("\n")
```
### MySQL
``` mysql
SELECT
Employees.EmployeeID,
Employees.Name,
Employees.Salary,
Manager.Name AS Manager
FROM
Employees
LEFT JOIN
Employees AS Manager
ON
Employees.ManagerID = Manager.EmployeeID
WHERE
Employees.EmployeeID = '087652';
```
### PHP
``` php
<?php
// src/AppBundle/Controller/LuckyController.php
namespace AppBundle\Controller;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Symfony\Component\HttpFoundation\Response;
class LuckyController {
/**
* @Route("/lucky/number")
*/
public function numberAction() {
$number = mt_rand(0, 100);
return new Response(
'<html><body>Lucky number: '.$number.'</body></html>'
);
}
}
```
### Protocol Buffers
``` proto
syntax = "proto2";
package caffe;
// Specifies the shape (dimensions) of a Blob.
message BlobShape {
repeated int64 dim = 1 [packed = true];
}
message BlobProto {
optional BlobShape shape = 7;
repeated float data = 5 [packed = true];
repeated float diff = 6 [packed = true];
// 4D dimensions -- deprecated. Use "shape" instead.
optional int32 num = 1 [default = 0];
optional int32 channels = 2 [default = 0];
optional int32 height = 3 [default = 0];
optional int32 width = 4 [default = 0];
}
```
### Python
``` python
"""
A very simple MNIST classifier.
See extensive documentation at
http://tensorflow.org/tutorials/mnist/beginners/index.md
"""
from __future__ import absolute_import
from __future__ import division
from __future__ import print_function
# Import data
from tensorflow.examples.tutorials.mnist import input_data
import tensorflow as tf
flags = tf.app.flags
FLAGS = flags.FLAGS
flags.DEFINE_string('data_dir', '/tmp/data/', 'Directory for storing data')
mnist = input_data.read_data_sets(FLAGS.data_dir, one_hot=True)
sess = tf.InteractiveSession()
# Create the model
x = tf.placeholder(tf.float32, [None, 784])
W = tf.Variable(tf.zeros([784, 10]))
b = tf.Variable(tf.zeros([10]))
y = tf.nn.softmax(tf.matmul(x, W) + b)
```
### Ruby
``` ruby
require 'finity/event'
require 'finity/machine'
require 'finity/state'
require 'finity/transition'
require 'finity/version'
module Finity
class InvalidCallback < StandardError; end
class MissingCallback < StandardError; end
class InvalidState < StandardError; end
# Class methods to be injected into the including class upon inclusion.
module ClassMethods
# Instantiate a new state machine for the including class by accepting a
# block with state and event (and subsequent transition) definitions.
def finity options = {}, &block
@finity ||= Machine.new self, options, &block
end
# Return the names of all registered states.
def states
@finity.states.map { |name, _| name }
end
# Return the names of all registered events.
def events
@finity.events.map { |name, _| name }
end
end
# Inject methods into the including class upon inclusion.
def self.included base
base.extend ClassMethods
end
end
```
### Scala
```scala
// Every record of this DataFrame contains the label and
// features represented by a vector.
val df = sqlContext.createDataFrame(data).toDF("label", "features")
// Set parameters for the algorithm.
// Here, we limit the number of iterations to 10.
val lr = new LogisticRegression().setMaxIter(10)
// Fit the model to the data.
val model = lr.fit(df)
// Inspect the model: get the feature weights.
val weights = model.weights
// Given a dataset, predict each point's label, and show the results.
model.transform(df).show()g
```
### XML
``` xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mainTag SYSTEM "some.dtd" [ENTITY % entity]>
<?oxygen RNGSchema="some.rng" type="xml"?>
<xs:main-Tag xmlns:xs="http://www.w3.org/2001/XMLSchema">
<!-- This is a sample comment -->
<childTag attribute="Quoted Value" another-attribute='Single quoted value'
a-third-attribute='123'>
<withTextContent>Some text content</withTextContent>
<withEntityContent>Some text content with &lt;entities&gt; and
mentioning uint8_t and int32_t</withEntityContent>
<otherTag attribute='Single quoted Value'/>
</childTag>
<![CDATA[ some CData ]]>
</main-Tag>
```

89
docs/extensions/footnotes.md
View File

@ -1,89 +0,0 @@
---
template: overrides/main.html
---
# Footnotes
[Footnotes][1] is another extension included in the standard Markdown library.
As the name says, it adds the ability to add inline footnotes to your
documentation.
[1]: https://python-markdown.github.io/extensions/footnotes/
## Configuration
Add the following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- footnotes
```
## Usage
The markup for footnotes is similar to the standard Markdown markup for links.
A reference is inserted in the text, which can then be defined at any point in
the document.
### Inserting the reference
The footnote reference is enclosed in square brackets and starts with a caret,
followed by an arbitrary label which may contain numeric identifiers [1, 2, 3,
...] or names [Granovetter et al. 1998]. The rendered references are always
consecutive superscripted numbers.
Example:
``` markdown
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
```
Result:
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
### Inserting the content
The footnote content is also declared with a label, which must match the label
used for the footnote reference. It can be inserted at an arbitrary position in
the document and is always rendered at the bottom of the page. Furthermore, a
backlink is automatically added to the footnote reference.
#### on a single line
Short statements can be written on the same line.
Example:
``` markdown
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```
Result:
<a href="#fn:1">Jump to footnote at the bottom of the page</a>
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
#### on multiple lines
Paragraphs should be written on the next line. As with all Markdown blocks, the
content must be indented by four spaces.
Example:
``` markdown
[^2]:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
Result:
[^2]:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
auctor massa, nec semper lorem quam in massa.
<a href="#fn:2">Jump to footnote at the bottom of the page</a>

37
docs/extensions/permalinks.md
View File

@ -1,37 +0,0 @@
---
template: overrides/main.html
---
# Permalinks
Permalinks are a feature of the [Table of Contents][1] extension, which is part
of the standard Markdown library. The extension inserts an anchor at the end of
each headline, which makes it possible to directly link to a specific section
of the document.
[1]: https://python-markdown.github.io/extensions/toc/
## Configuration
Add the following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- toc:
permalink: true
```
This will add a link containing the paragraph symbol `¶` at the end of each
headline (exactly like on the page you're currently viewing), which Material
for MkDocs will make appear on hover. In order to change the text of the
permalink, a string can be passed, e.g.:
``` yaml
markdown_extensions:
- toc:
permalink: Link
```
## Usage
When enabled, permalinks are inserted automatically.

375
docs/extensions/pymdown.md
View File

@ -1,375 +0,0 @@
---
template: overrides/main.html
---
# PyMdown Extensions
[PyMdown Extensions][1] is a collection of Markdown extensions that add some
great missing features to the standard Markdown library. A compatible version
is always included with the theme.
[1]: https://facelessuser.github.io/pymdown-extensions/
## Configuration
The following list of extensions that are part of the PyMdown Extensions
package are recommended to be used together with Material for MkDocs:
``` yaml
markdown_extensions:
- pymdownx.arithmatex
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- pymdownx.critic
- pymdownx.details
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
- pymdownx.inlinehilite
- pymdownx.magiclink
- pymdownx.mark
- pymdownx.smartsymbols
- pymdownx.superfences
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tabbed
- pymdownx.tilde
```
## Usage
### Arithmatex <small>MathJax</small>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML"></script>
[Arithmatex][2] integrates Material for MkDocs with [MathJax][3] which parses
block-style and inline equations written in TeX markup and outputs them in
mathematical notation. See [this thread][4] for a short introduction and quick
reference on how to write equations in TeX syntax.
Besides activating the extension in the `mkdocs.yml`, the MathJax JavaScript
runtime needs to be included. This can be done with [additional JavaScript][5]:
``` yaml
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML
```
If you want to override the default MathJax configuration, you can do this by
adding another JavaScript file **before** the MathJax runtime which contains
the MathJax configuration, e.g.:
``` js
window.MathJax = {
tex2jax: {
inlineMath: [ ["\\(","\\)"] ],
displayMath: [ ["\\[","\\]"] ]
},
TeX: {
TagSide: "right",
TagIndent: ".8em",
MultLineWidth: "85%",
equationNumbers: {
autoNumber: "AMS",
},
unicode: {
fonts: "STIXGeneral,'Arial Unicode MS'"
}
},
displayAlign: "left",
showProcessingMessages: false,
messageStyle: "none"
};
```
Then, add the following lines to `mkdocs.yml`:
``` yaml
extra_javascript:
- javascripts/extra.js
- https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML
```
[2]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
[3]: https://www.mathjax.org/
[4]: https://math.meta.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference
[5]: ../customization.md#additional-javascript
#### Blocks
Blocks are enclosed in `:::tex $$...$$` which are placed on separate lines.
Example:
``` tex
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$
```
Result:
$$
\frac{n!}{k!(n-k)!} = \binom{n}{k}
$$
#### Inline
Inline equations must be enclosed in `:::tex $...$`:
Example:
``` tex
Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
```
Result:
Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
### BetterEm
[BetterEm][6] improves the handling of emphasis markup (**bold** and *italic*)
within Markdown by providing a more sophisticated parser for better detecting
start and end tokens. Read the documentation for [usage notes][7].
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
[7]: https://facelessuser.github.io/pymdown-extensions/usage_notes/
### Caret
[Caret][8] makes it possible to highlight ^^inserted text^^. The portion of
text that should be marked as added must be enclosed in two carets `^^...^^`.
[8]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
### Critic
[Critic][9] implements [Critic Markup][10], a Markdown extension that enables
the tracking of changes (additions, deletions and comments) on documents.
During compilation of the Markdown document, changes can be rendered (default),
accepted or rejected.
Text can be {--deleted--} and replacement text {++added++}. This can also be
combined into {~~one~>a single~~} operation. {==Highlighting==} is also
possible {>>and comments can be added inline<<}.
{==
Formatting can also be applied to blocks, by putting the opening and closing
tags on separate lines and adding new lines between the tags and the content.
==}
[9]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
[10]: http://criticmarkup.com/
### Details
[Details][11] adds [collapsible Admonition blocks][12] which can contain
arbitrary content using the HTML5 `details` and `summary` tags. Additionally,
all Admonition qualifiers can be used, e.g. `note`, `question`, `warning` etc.:
??? question "How many Prolog programmers does it take to change a lightbulb?"
Yes.
[11]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
[12]: ../admonition/#collapsible-blocks
### Emoji :tada:
[Emoji][13] adds the ability to insert, well, emojis! :smile:
By default, [Emoji][13] uses JoyPixles' emoji under the former name EmojiOne.
Recent versions of the extension lock support to an older version (2.2.7) due
to JoyPixels' newer, less permissible licenses included in later releases. This
restricts support to Unicode 9. To get the latest support for the current
Unicode version, you can use Twemoji instead which has a much more permissible
license. Simply override the default emoji index being used:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:pymdownx.emoji.twemoji
emoji_generator: !!python/name:pymdownx.emoji.to_svg
```
To view all the available short names and emoji available, see
[Emoji's documentation][18] on your chosen index which includes links to the
files containing the short names and emoji associated with each supported
index.
!!! warning "Legal disclaimer"
Material has no affiliation with [JoyPixles][15] or [Twemoji][14], both
of which are licensed under [CC BY 4.0][16]. When including images or CSS
from either provider, please read their licenses to ensure proper
attribution: [EmojiOne][17] or [Twemoji][14].
### Icons :hatching_chick:
In addition, you can embed the Material Design icons, Fontawesome icons and
GitHub's Octicons directly from Markdown by using [Material for MkDocs's custom
emoji index][19]. It extends the Twemoji index with new short names that access
any of the included icons. To use the custom index, you need to use
`materialx.emoji` instead of `pymdownx.emoji`:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
```
Example:
``` markdown
* :material-account-circle: – we can use Material Design icons
* :fontawesome-regular-laugh-wink: – we can also use FontAwesome icons
* :octicons-octoface-16: – that's not all, we can also use GitHub's Octicons
```
Result:
* :material-account-circle: – we can use [Material Design icons][20]
* :fontawesome-regular-laugh-wink: – we can also use [FontAwesome icons][21]
* :octicons-octoface-16: – that's not all, we can also use [GitHub's Octicons][22]
[13]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[14]: https://twemoji.twitter.com/
[15]: https://www.joypixels.com/
[16]: https://creativecommons.org/licenses/by/4.0/legalcode
[17]: https://github.com/joypixels/emojione#emojione-version-2
[18]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
[19]: https://github.com/facelessuser/mkdocs-material-extensions
[20]: https://material.io/resources/icons/
[21]: https://fontawesome.com/icons?d=gallery&m=free
[22]: https://octicons.github.com/
### InlineHilite
[InlineHilite][23] adds support for inline code highlighting. It's useful for
short snippets included within body copy, e.g. `#!js var test = 0;` and can be
activated by prefixing inline code with a shebang and language identifier,
e.g. `#!js`.
[23]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
### MagicLink
[MagicLink][24] detects links in Markdown and auto-generates the necessary
markup, so no special syntax is required. It auto-links `http[s]://` and
`ftp://` links, as well as references to email addresses.
[24]: https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/
### Mark
[Mark][25] adds the ability to ==highlight text== like it was marked with a
==text marker==. The portion of text that should be highlighted must be
enclosed in two equal signs `==...==`.
[25]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
### SmartSymbols
[SmartSymbols][26] converts markup for special characters into their
corresponding symbols, e.g. arrows (<--, -->, <-->), trademark and copyright
symbols ((c), (tm), (r)) and fractions (1/2, 1/4, ...).
[26]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
### SuperFences
[SuperFences][27] provides the ability to nest code blocks under blockquotes,
lists and other block elements, which the [Fenced Code Blocks][28] extension
from the standard Markdown library doesn't parse correctly.
SuperFences does also allow [grouping code blocks with tabs][29].
[27]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
[28]: https://python-markdown.github.io/extensions/fenced_code_blocks/
[29]: codehilite.md#grouping-code-blocks
### Tabbed
[Tabbed][30] adds support for creating tabbed groups of Markdown content.
Example:
``` markdown
=== "Fruit List"
- :apple: Apple
- :banana: Banana
- :kiwi: Kiwi
=== "Fruit Table"
Fruit | Color
--------------- | -----
:apple: Apple | Red
:banana: Banana | Yellow
:kiwi: Kiwi | Green
```
Result:
=== "Fruit List"
- :apple: Apple
- :banana: Banana
- :kiwi: Kiwi
=== "Fruit Table"
Fruit | Color
--------------- | -----
:apple: Apple | Red
:banana: Banana | Yellow
:kiwi: Kiwi | Green
[30]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
### Tasklist
[Tasklist][31] adds support for styled checkbox lists. This is useful for
keeping track of tasks and showing what has been done and has yet to be done.
Checkbox lists are like regular lists, but prefixed with `[ ]` for empty or
`[x]` for filled checkboxes.
Example:
``` markdown
* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
* [x] Nulla lobortis egestas semper
* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
* [ ] Vestibulum convallis sit amet nisi a tincidunt
* [x] In hac habitasse platea dictumst
* [x] In scelerisque nibh non dolor mollis congue sed et metus
* [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
* [ ] Praesent sed risus massa
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi
```
Result:
* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
* [x] Nulla lobortis egestas semper
* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est
* [ ] Vestibulum convallis sit amet nisi a tincidunt
* [x] In hac habitasse platea dictumst
* [x] In scelerisque nibh non dolor mollis congue sed et metus
* [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis
* [ ] Praesent sed risus massa
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi
[31]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
### Tilde
[Tilde][32] provides an easy way to ~~strike through~~ cross out text.
The portion of text that should be erased must be enclosed in two tildes
`~~...~~` and the extension will take care of the rest.
[32]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/

796
docs/getting-started.md
View File

@ -4,64 +4,55 @@ template: overrides/main.html
# Getting started
Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
towards (technical) project documentation. If you're familar with Python, you
can install Material for MkDocs with [`pip`][2], the Python package manager.
If not, we recommended using [`docker`][3].
In case you're running into problems, consult the [troubleshooting][4] section.
[1]: https://www.mkdocs.org
[2]: #with-pip
[3]: #with-docker
[4]: troubleshooting.md
## 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][1].
[1]: https://hub.docker.com/r/squidfunk/mkdocs-material/
### with pip <small>recommended</small>
### with pip
Material for MkDocs can be installed with `pip`:
=== "Community edition"
``` sh
pip install mkdocs-material
```
Note that this will automatically install compatible versions of [MkDocs][2],
[Markdown][3], [Pygments][4] and [PyMdown Extensions][5]. Material for MkDocs
always strives to support the latest versions, so there's no need to install
those packages separately.
=== "Sponsor edition"
!!! tip "Installation in a virtual environment"
``` sh
pip install git+https://$GH_TOKEN@github.com/squidfunk/mkdocs-material-next.git
```
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.
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.
!!! warning "Installation on macOS"
Note that in order to install the [sponsor edition][8], you'll need to [become
a sponsor][9], create a [personal access token][10], and set the `GH_TOKEN`
environment variable to the token's value.
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:
[5]: https://python-markdown.github.io/
[6]: https://pygments.org/
[7]: https://facelessuser.github.io/pymdown-extensions/
[8]: sponsorship.md
[9]: sponsorship.md#how-to-become-a-sponsor
[10]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
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.
### with docker
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.
[2]: https://www.mkdocs.org
[3]: https://python-markdown.github.io/
[4]: https://pygments.org/
[5]: https://facelessuser.github.io/pymdown-extensions/
[6]: https://docs.python-guide.org/dev/virtualenvs/
### with docker <small>recommended</small>
The official [Docker image][7] is a great way to get up and running in a few
The official [Docker image][11] 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:
@ -69,726 +60,35 @@ minutes, as it comes with all dependencies pre-installed. Pull the image for the
docker pull squidfunk/mkdocs-material
```
The `mkdocs` executable is provided as an entry point and `serve` is the default
command. Start the development server in your project root – the folder where
`mkdocs.yml` resides — with:
The `mkdocs` executable is provided as an entry point and `serve` is the
default command. If you're not familar with Docker don't worry, we have you
covered in the following sections.
=== "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
```
[7]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[11]: https://hub.docker.com/r/squidfunk/mkdocs-material/
### with git
Material for MkDocs can be directly used from [GitHub][8] by cloning the
Material for MkDocs can be directly used from [GitHub][12] by cloning the
repository into a subfolder of your project root which might be useful if you
want to use the very latest version:
=== "Community edition"
``` sh
git clone https://github.com/squidfunk/mkdocs-material.git
```
The theme will reside in the folder `mkdocs-material/material`.
[8]: https://github.com/squidfunk/mkdocs-material
## 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:
``` yaml
theme:
name: material
```
If you cloned Material for MkDocs from GitHub add:
``` yaml
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:
=== "Sponsor edition"
``` sh
mkdocs serve
git clone git@github.com:squidfunk/mkdocs-material-next.git mkdocs-material
```
Point your browser to http://localhost:8000 and your documentation should greet
you in a new look. If you're starting from scratch, the following configuration
can be used as a starting point:
The theme will reside in the folder `mkdocs-material/material`. Note that when
cloning from `git`, you must install all required dependencies yourself:
??? summary "Example configuration"
This is an excerpt from the [`mkdocs.yml`][9] used to render these pages:
``` 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
``` sh
pip install -r mkdocs-material/requirements.txt
```
[9]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
### Feature flags
These optional features are hidden behind flags and can be explicitly enabled
in `mkdocs.yml`.
#### Instant loading :hatching_chick:
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:
``` yaml
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:
``` yaml
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.
This means that there will effectively be no collapsible subsections for the
first tab, as each subsection is rendered as another tab. If you want more
fine-grained control, i.e., collapsible subsections for the first tab, you can
move all *top-level pages into a subsection*, so that the top-level is entirely
made up of subsections. Note that tabs are only shown for larger screens, so
make sure that navigation is plausible on mobile devices.
As an example, see the [`mkdocs.yml`][9] used to render these pages.
### 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:
``` yaml
theme:
language: en
```
The following language codes are supported:
<style>
.md-language-list {
-webkit-columns: 2;
-moz-columns: 2;
columns: 2;
}
.md-language-list li {
-webkit-column-break-inside: avoid;
page-break-inside: avoid;
break-inside: avoid;
}
</style>
<ul class="md-language-list">
<li><code>af</code> / Afrikaans</li>
<li><code>ar</code> / Arabic</li>
<li><code>bn</code> / Bengali (Bangla)</li>
<li><code>ca</code> / Catalan</li>
<li><code>cs</code> / Czech</li>
<li><code>da</code> / Danish</li>
<li><code>de</code> / German</li>
<li><code>en</code> / English</li>
<li><code>es</code> / Spanish</li>
<li><code>et</code> / Estonian</li>
<li><code>fa</code> / Persian (Farsi)</li>
<li><code>fi</code> / Finnish</li>
<li><code>fr</code> / French</li>
<li><code>gl</code> / Galician</li>
<li><code>gr</code> / Greek</li>
<li><code>he</code> / Hebrew</li>
<li><code>hi</code> / Hindi</li>
<li><code>hr</code> / Croatian</li>
<li><code>hu</code> / Hungarian</li>
<li><code>id</code> / Indonesian</li>
<li><code>it</code> / Italian</li>
<li><code>ja</code> / Japanese</li>
<li><code>kr</code> / Korean</li>
<li><code>my</code> / Burmese</li>
<li><code>nl</code> / Dutch</li>
<li><code>nn</code> / Norwegian (Nynorsk)</li>
<li><code>no</code> / Norwegian</li>
<li><code>pl</code> / Polish</li>
<li><code>pt</code> / Portuguese</li>
<li><code>ro</code> / Romanian</li>
<li><code>ru</code> / Russian</li>
<li><code>sh</code> / Serbo-Croatian</li>
<li><code>si</code> / Slovenian</li>
<li><code>sk</code> / Slovak</li>
<li><code>sr</code> / Serbian</li>
<li><code>sv</code> / Swedish</li>
<li><code>th</code> / Thai</li>
<li><code>tr</code> / Turkish</li>
<li><code>uk</code> / Ukrainian</li>
<li><code>vi</code> / Vietnamese</li>
<li><code>zh</code> / Chinese (Simplified)</li>
<li><code>zh-Hant</code> / Chinese (Traditional)</li>
<li><code>zh-TW</code> / Chinese (Taiwanese)</li>
<li>
<a href="https://bit.ly/38F5RCa">
Add language
</a>
</li>
</ul>
While many languages are read `ltr` (left-to-right), Material for MkDocs also
supports `rtl` (right-to-left) directionality which is inferred from the
selected language, but can also be set with:
``` yaml
theme:
direction: rtl
```
### Color scheme
> Default: `default`
Material for MkDocs supports two color schemes: a light mode, which is just
called `default`, and a dark mode, which is called `slate`. The color scheme
can be set from `mkdocs.yml`:
``` yaml
theme:
palette:
scheme: slate
```
Click on a color name to change the color scheme of the theme:
<style>
.md-typeset button[data-md-color-scheme] {
cursor: pointer;
transition: opacity 250ms;
}
.md-typeset button[data-md-color-scheme]:hover {
opacity: 0.75;
}
.md-typeset button[data-md-color-scheme] > code {
display: block;
color: var(--md-primary-bg-color);
background-color: var(--md-primary-fg-color);
}
</style>
<button data-md-color-scheme="default"><code>default</code></button>
<button data-md-color-scheme="slate"><code>slate</code></button>
<script>
var buttons = document.querySelectorAll("button[data-md-color-scheme]")
buttons.forEach(function(button) {
var attr = "data-md-color-scheme"
button.addEventListener("click", function() {
document.body.setAttribute(attr, this.getAttribute(attr))
})
})
</script>
The color scheme can also be set based on _user preference_, which makes use of
the `prefers-color-scheme` media query. This can be done by adding the following
to `mkdocs.yml`:
``` yaml
theme:
palette:
scheme: preference
```
### Color palette
The Material Design [color palette][10] 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`:
``` yaml
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][11] 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: ...;
}
:root > * {
/* Code block color shades */
--md-code-bg-color: ...;
--md-code-fg-color: ...;
}
```
[10]: http://www.materialui.co/colors
[11]: customization.md#additional-stylesheets
#### Primary color
> Default: `indigo`
Click on a color name to change the primary color of the theme:
<style>
.md-typeset button[data-md-color-primary] {
cursor: pointer;
transition: opacity 250ms;
}
.md-typeset button[data-md-color-primary]:hover {
opacity: 0.75;
}
.md-typeset button[data-md-color-primary] > code {
display: block;
color: var(--md-primary-bg-color);
background-color: var(--md-primary-fg-color);
}
</style>
<button data-md-color-primary="red"><code>red</code></button>
<button data-md-color-primary="pink"><code>pink</code></button>
<button data-md-color-primary="purple"><code>purple</code></button>
<button data-md-color-primary="deep-purple"><code>deep purple</code></button>
<button data-md-color-primary="indigo"><code>indigo</code></button>
<button data-md-color-primary="blue"><code>blue</code></button>
<button data-md-color-primary="light-blue"><code>light blue</code></button>
<button data-md-color-primary="cyan"><code>cyan</code></button>
<button data-md-color-primary="teal"><code>teal</code></button>
<button data-md-color-primary="green"><code>green</code></button>
<button data-md-color-primary="light-green"><code>light green</code></button>
<button data-md-color-primary="lime"><code>lime</code></button>
<button data-md-color-primary="yellow"><code>yellow</code></button>
<button data-md-color-primary="amber"><code>amber</code></button>
<button data-md-color-primary="orange"><code>orange</code></button>
<button data-md-color-primary="deep-orange"><code>deep orange</code></button>
<button data-md-color-primary="brown"><code>brown</code></button>
<button data-md-color-primary="grey"><code>grey</code></button>
<button data-md-color-primary="blue-grey"><code>blue grey</code></button>
<button data-md-color-primary="black"><code>black</code></button>
<button data-md-color-primary="white"><code>white</code></button>
<script>
var buttons = document.querySelectorAll("button[data-md-color-primary]")
buttons.forEach(function(button) {
var attr = "data-md-color-primary"
button.addEventListener("click", function() {
document.body.setAttribute(attr, this.getAttribute(attr))
})
})
</script>
#### Accent color
> Default: `indigo`
Click on a color name to change the accent color of the theme:
<style>
.md-typeset button[data-md-color-accent] {
cursor: pointer;
transition: opacity 250ms;
}
.md-typeset button[data-md-color-accent]:hover {
opacity: 0.75;
}
.md-typeset button[data-md-color-accent] > code {
display: block;
color: var(--md-accent-fg-color);
}
</style>
<button data-md-color-accent="red"><code>red</code></button>
<button data-md-color-accent="pink"><code>pink</code></button>
<button data-md-color-accent="purple"><code>purple</code></button>
<button data-md-color-accent="deep-purple"><code>deep purple</code></button>
<button data-md-color-accent="indigo"><code>indigo</code></button>
<button data-md-color-accent="blue"><code>blue</code></button>
<button data-md-color-accent="light-blue"><code>light blue</code></button>
<button data-md-color-accent="cyan"><code>cyan</code></button>
<button data-md-color-accent="teal"><code>teal</code></button>
<button data-md-color-accent="green"><code>green</code></button>
<button data-md-color-accent="light-green"><code>light green</code></button>
<button data-md-color-accent="lime"><code>lime</code></button>
<button data-md-color-accent="yellow"><code>yellow</code></button>
<button data-md-color-accent="amber"><code>amber</code></button>
<button data-md-color-accent="orange"><code>orange</code></button>
<button data-md-color-accent="deep-orange"><code>deep orange</code></button>
<script>
var buttons = document.querySelectorAll("button[data-md-color-accent]")
buttons.forEach(function(button) {
var attr = "data-md-color-accent"
button.addEventListener("click", function() {
document.body.setAttribute(attr, this.getAttribute(attr))
})
})
</script>
### Fonts
> Default: `Roboto` and `Roboto Mono`
The [Roboto font family][12] 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][13] and can be changed to any
valid webfont, like for example the [Ubuntu font family][14]:
``` yaml
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`:
``` yaml
theme:
font: false
```
[12]: https://fonts.google.com/specimen/Roboto
[13]: https://fonts.google.com
[14]: https://fonts.google.com/specimen/Ubuntu
### 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][15]. 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:
``` yaml
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][16] (`material`): 5.1k icons
* [FontAwesome icons][17] (`fontawesome`): 1.6k icons
* [GitHub's Octicons][18] (`octicons`): 200 icons
__You can use all those icons [directly from :fontawesome-brands-markdown:
Markdown][19]!__
[15]: #adding-social-links
[16]: https://materialdesignicons.com/
[17]: https://fontawesome.com/icons?d=gallery&m=free
[18]: https://octicons.github.com/
[19]: extensions/pymdown.md#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`:
``` yaml
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:
``` yaml
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`:
``` yaml
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][20] on more
guidance regarding the `edit_uri` attribute, which defines whether the edit
button is shown or not.
[20]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
### Adding social links
Social accounts can be linked in the footer of the documentation using the
[icons][21] 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:
``` yaml
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
```
By default, the link `title` will be set to the domain name, e.g. _github.com_.
If you want to set a discernable name, e.g., to improve your Lighthouse score,
you can set the `name` attribute on each social link.
[21]: #icons
### Adding a Web App Manifest
A [Web App Manifest][22] 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`:
``` yaml
extra:
manifest: manifest.webmanifest
```
[22]: https://developers.google.com/web/fundamentals/web-app-manifest/
## Integrations
### Google Analytics
MkDocs makes it easy to integrate site tracking with Google Analytics. To enable
tracking, which is disabled by default, you must add your tracking identifier
to `mkdocs.yml`:
``` yaml
google_analytics:
- UA-XXXXXXXX-X
- auto
```
Besides basic page views, *site search* can also be tracked to better understand
how people use your documentation and what they expect to find. To enable
search tracking:
1. Go to your Google Analytics **admin settings**
2. Select the property for the respective tracking code
3. Go to the **view settings** tab.
4. Scroll down and enable **site search settings**
5. Set the **query parameter** to `q`.
### Disqus
Material for MkDocs is integrated with [Disqus][23], so if you want to add a
comments section to your documentation set the *shortname* of your Disqus
project in `mkdocs.yml`:
``` yaml
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][24].
[23]: https://disqus.com
[24]: extensions/metadata.md#disqus
## Extensions
[Markdown][3] 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:
``` yaml
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:
* [Admonition][25]
* [Codehilite][26]
* [Footnotes][27]
* [Metadata][28]
* [Permalinks][29]
* [PyMdown Extensions][30]
[25]: extensions/admonition.md
[26]: extensions/codehilite.md
[27]: extensions/footnotes.md
[28]: extensions/metadata.md
[29]: extensions/permalinks.md
[30]: extensions/pymdown.md
## 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][31] (enabled by default)
* [Minification][32]
* [Revision date][33]
* [Awesome pages][34]
For further reference, the MkDocs wiki contains a list of all
[available plugins][35].
[31]: plugins/search.md
[32]: plugins/minification.md
[33]: plugins/revision-date.md
[34]: plugins/awesome-pages.md
[35]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
[12]: https://github.com/squidfunk/mkdocs-material

20
docs/license.md
View File

@ -6,22 +6,4 @@ template: overrides/main.html
**MIT License**
Copyright &copy; 2016 - 2020 Martin Donath
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
--8<-- "LICENSE"

80
docs/plugins/awesome-pages.md
View File

@ -1,80 +0,0 @@
---
template: overrides/main.html
---
# Awesome pages
The [mkdocs-awesome-pages-plugin][1] omits the need to specify all pages in the
`nav` entry of `mkdocs.yml` and gives you control over page visibility, titles
and order on a directory level.
!!! success "Bundled with the official Docker image"
This plugin is already installed for your convenience when you use the
official [Docker image][2], so the installation step can be skipped. Read
the [getting started guide][3] to get up and running with Docker.
[1]: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
[2]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[3]: ../getting-started.md#with-docker-recommended
## Installation
Install the plugin using `pip`:
``` sh
pip install mkdocs-awesome-pages-plugin
```
## Configuration
Add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- search # necessary for search to work
- awesome-pages
```
## Usage
If the `nav` entry in `mkdocs.yml` is omitted, MkDocs will automatically include
all pages in a specific order. This plugin allows for more fine-grained control
on a per-directory basis. In order to configure behavior for a specific
directory, create a YAML file named `.pages` in it and set one of the following
options.
### Setting a directory title
The directory title, which is shown as part of the navigation, can be set with:
``` yaml
title: Lorem ipsum dolor sit amet
```
### Changing the order of pages
The order of pages and subsections can be configured with:
``` yaml
arrange:
- page-1.md
- page-2.md
- subdirectory
```
### Excluding a directory
A directory can be hidden (i.e. excluded) with:
``` yaml
hide: true
```
### Collapsing single-page directories
Directories which contain a single page can be collapsed with:
``` yaml
collapse: true
```

42
docs/plugins/minification.md
View File

@ -1,42 +0,0 @@
---
template: overrides/main.html
---
# Minification
The [mkdocs-minify-plugin][1] will minify all `*.html` files generated by
`mkdocs build` in a post-processing step, stripping all unnecessary characters
to reduce the payload served to the client.
!!! success "Bundled with the official Docker image"
This plugin is already installed for your convenience when you use the
official [Docker image][2], so the installation step can be skipped. Read
the [getting started guide][3] to get up and running with Docker.
[1]: https://github.com/byrnereese/mkdocs-minify-plugin
[2]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[3]: ../getting-started.md#with-docker-recommended
## Installation
Install the plugin using `pip`:
``` sh
pip install mkdocs-minify-plugin
```
## Configuration
Add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- search # necessary for search to work
- minify:
minify_html: true
```
## Usage
When enabled, all `*.html` will be minified automatically.

85
docs/plugins/revision-date.md
View File

@ -1,85 +0,0 @@
---
template: overrides/main.html
---
# Revision date
The [mkdocs-git-revision-date-localized-plugin][1] will add the date on which a
Markdown file was last updated at the bottom of each page.
!!! success "Bundled with the official Docker image"
This plugin is already installed for your convenience when you use the
official [Docker image][2], so the installation step can be skipped. Read
the [getting started guide][3] to get up and running with Docker.
[1]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
[2]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[3]: ../getting-started.md#with-docker-recommended
!!! warning "Requirements"
The date is extracted at the time of the build, so `mkdocs build` must be
triggered from within a git repository.
## Installation
Install the plugin using `pip`:
``` sh
pip install mkdocs-git-revision-date-localized-plugin
```
## Configuration
Add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- search # necessary for search to work
- git-revision-date-localized
```
Note that the date is printed according to the locale which is determined
through the [theme language][2] that was set in `mkdocs.yml`.
[2]: ../getting-started.md/#language
### Language
The language (i.e. locale) is deduced from the `theme.language` option.
### Format
> Default: `date`
To change the date format, set the `type` parameter to one of `date`,
`datetime`, `iso_date`, `iso_datetime` or `timeago`, e.g.:
``` yaml
plugins:
- search # necessary for search to work
- git-revision-date-localized:
type: date
```
The following formats are supported:
``` gnuplot
28 November, 2019 # type: date
28 November, 2019 13:57:28 # type: datetime
2019-11-28 # type: iso_date
2019-11-28 13:57:26 # type: iso_datetime
20 hours ago # type: timeago
```
## Usage
When enabled, the respective date is automatically added at the bottom of each
page, e.g.:
---
<small>
Last updated: 28 November, 2019
</small>

133
docs/plugins/search.md
View File

@ -1,133 +0,0 @@
---
template: overrides/main.html
---
# Search
The [built-in search plugin][1] provides client-side search inside the browser
and is implemented using [lunr.js][2] which includes stemmers for the English
language by default, while stemmers for other languages are included with
[lunr-languages][3], both of which are integrated with this theme.
!!! tip "Make search work offline"
While search will not work for the `file://` protocol, as web workers and
the use of `XMLHTTPRequest` are both blocked by modern browsers for security
reasons, the [localsearch][4] plugin and @squidfunk's [iframe-worker][5]
polyfill add support for cases where this is a mandatory requirement, e.g.,
for offline use.
[1]: https://www.mkdocs.org/user-guide/configuration/#search
[2]: https://lunrjs.com
[3]: https://github.com/MihaiValentin/lunr-languages
[4]: https://github.com/wilhelmer/mkdocs-localsearch
[5]: https://github.com/squidfunk/iframe-worker
## Installation
The search plugin is a built-in plugin, and thus doesn't need to be installed.
## Configuration
Add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- search
```
### Language
> Default: best match for `theme.language`, automatically set
Material for MkDocs selects the (best-)matching stemmer for the given theme
language. Multilingual search can be enabled in `mkdocs.yml` by explicitly
defining the search language(s):
``` yaml
plugins:
- search:
lang:
- en
- de
- ru
```
The following language codes are supported:
<style>
.md-language-list {
-webkit-columns: 2;
-moz-columns: 2;
columns: 2;
}
.md-language-list li {
-webkit-column-break-inside: avoid;
page-break-inside: avoid;
break-inside: avoid;
}
</style>
<ul class="md-language-list">
<li><code>ar</code> / Arabic</li>
<li><code>da</code> / Danish</li>
<li><code>du</code> / Dutch</li>
<li><code>en</code> / English</li>
<li><code>fi</code> / Finnish</li>
<li><code>fr</code> / French</li>
<li><code>de</code> / German</li>
<li><code>hu</code> / Hungarian</li>
<li><code>it</code> / Italian</li>
<li><code>ja</code> / Japanese</li>
<li><code>no</code> / Norwegian</li>
<li><code>pt</code> / Portuguese</li>
<li><code>ro</code> / Romanian</li>
<li><code>ru</code> / Russian</li>
<li><code>es</code> / Spanish</li>
<li><code>sv</code> / Swedish</li>
<li><code>th</code> / Thai</li>
<li><code>tr</code> / Turkish</li>
<li><code>vi</code> / Vietnamese</li>
</ul>
!!! warning "Only specify the languages you really need"
Be aware that including support for other languages increases the general
JavaScript payload by around 20kb (before `gzip`) and by another 15-30kb
per language.
### Tokenization
> Default: `[\s\-]+`
The separator for tokenization can be customized which makes it possible to
index parts of words that are separated by `-` or `.`:
``` yaml
plugins:
- search:
separator: '[\s\-\.]+'
```
### Prebuilding :hatching_chick:
> Default: `false`
MkDocs can generate a [prebuilt index][6] of all pages during build time, which
provides performance improvements at the cost of more bandwidth. This may be
beneficial for large documentation projects that are served with appropriate
HTTP headers (e.g. `Content-Encoding: gzip`).
Material for MkDocs 5 finally brings experimental support for prebuilt indexes
which can be enabled by adding the following lines to `mkdocs.yml`:
``` yaml
plugins:
- search:
prebuild_index: true
```
[6]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
## Usage
When enabled, a search bar is shown in the header.

94
docs/publishing-your-site.md Normal file
View File

@ -0,0 +1,94 @@
---
template: overrides/main.html
---
# Publishing your site
The great thing about hosting project documentation in a `git` repository is
the ability to deploy it automatically when new changes are pushed. MkDocs
makes this ridiculously simple.
## GitHub Pages
If you're already hosting your code on GitHub, [GitHub Pages][1] 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/
### with GitHub Actions
Using [GitHub Actions][2] 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:
=== ".github/workflows/ci.yml"
``` yaml
name: ci
on:
push:
branches:
- master
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- uses: actions/setup-python@v2
with:
python-version: 3.x
- run: pip install mkdocs-material
- run: mkdocs gh-deploy --force
```
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>.github.io/<repository>`.
[2]: https://github.com/features/actions
### with MkDocs
If you prefer to deploy your project documentation manually, you can just invoke
the following command from the directory containing the `mkdocs.yml` file:
```
mkdocs gh-deploy --force
```
## GitLab Pages
If you're hosting your code on GitLab, deploying to [GitLab Pages][3] can be
done by using the [GitLab CI][4] task runner. At the root of your repository,
create a task definition named `.gitlab-ci.yml` and copy and paste the
following contents:
=== ".gitlab-ci.yml"
``` yaml
image: python:latest
deploy:
stage: deploy
only:
- master
script:
- pip install mkdocs-material
- mkdocs build --site-dir public
artifacts:
paths:
- public
```
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>`.
[3]: https://gitlab.com/pages
[4]: https://docs.gitlab.com/ee/ci/

331
docs/reference/admonitions.md Normal file
View File

@ -0,0 +1,331 @@
---
template: overrides/main.html
---
# Admonitions
Admonitions, also known as _call-outs_, are an excellent choice for including
side content without significantly interrupting the document flow. Material for
MkDocs provides several different types of admonitions and allows for the
inclusion and nesting of arbitrary content.
## Configuration
### Admonition
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Admonition][2] extension, which is part of the standard Markdown
library, is integrated with Material for MkDocs and can be enabled from
`mkdocs.yml`:
``` yaml
markdown_extensions:
- admonition
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/_admonition.scss
[2]: https://python-markdown.github.io/extensions/admonition/
### Details
[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
The [Details][4] extension, which is part of [Python Markdown Extensions][5],
adds the ability to __make admonitions collapsible__. It can be enabled from
`mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.details
```
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_details.scss
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
[5]: https://facelessuser.github.io/pymdown-extensions/
### SuperFences
[:octicons-file-code-24: Source][6] · [:octicons-workflow-24: Extension][7]
The [SuperFences][7] extension, which is also part of [Python Markdown
Extensions][5], allows for the __nesting of content blocks inside admonitions__,
and is therefore strongly recommended:
``` yaml
markdown_extensions:
- pymdownx.superfences
```
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
## Usage
Admonitions follow a simple syntax: a block must start with `!!!`, followed
by a single keyword which is used as the [type qualifier][8] of the block. The
content of the block then follows on the next line, indented by four spaces.
_Example_:
``` markdown
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[8]: #supported-types
### Changing the title
By default, the title will equal the type qualifier in titlecase. However, it
can be changed by adding a quoted string containing valid Markdown (including
links, formatting, ...) after the type qualifier.
_Example_:
``` markdown
!!! note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
!!! note "Phasellus posuere in sem ut cursus"
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
### Removing the title
Similar to [changing the title][9], the icon and title can be omitted entirely
by adding an empty string directly after the type qualifier. Note that this
will not work for [collapsible blocks][10].
_Example_:
``` markdown
!!! note ""
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
!!! note ""
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[9]: #changing-the-title
[10]: #collapsible-blocks
### Embedded content
Admonitions can contain all kinds of text content, including headlines, lists,
paragraphs and other blocks. While the parser from the standard Markdown library
doesn't account for nested blocks, the [SuperFences][11] extension adds the
ability to nest arbitrary content inside admonitions.
_Example_:
``` markdown
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
``` python
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
```
_Result_:
!!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
``` python
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in
sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis.
Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim.
[11]: #superfences
### Collapsible blocks
The [Details][12] extension adds support for rendering collapsible admonition
blocks. This is useful for FAQs or content that is of secondary nature. A
details block follows the syntax and semantics of admonition blocks, but must
start with `???`.
_Example_:
``` markdown
??? note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
??? note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
Adding a `+` after `???` will render the block as open on page load:
_Example_:
``` markdown
???+ note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
???+ note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
[12]: #details
### Supported types
Following is a list of type qualifiers provided by Material for MkDocs, whereas
the default type, and thus fallback for unknown type qualifiers, is `note`:
`note`, `seealso`
: !!! note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`abstract`, `summary`, `tldr`
: !!! abstract
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`info`, `todo`
: !!! info
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`tip`, `hint`, `important`
: !!! tip
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`success`, `check`, `done`
: !!! success
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`question`, `help`, `faq`
: !!! question
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`warning`, `caution`, `attention`
: !!! warning
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`failure`, `fail`, `missing`
: !!! failure
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`danger`, `error`
: !!! danger
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`bug`
: !!! bug
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`example`
: !!! example
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.
`quote`, `cite`
: !!! quote
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et
euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
purus auctor massa, nec semper lorem quam in massa.

290
docs/reference/code-blocks.md Normal file
View File

@ -0,0 +1,290 @@
---
template: overrides/main.html
---
# Code blocks
Code blocks and examples are an essential part of technical project
documentation. Material for MkDocs provides different ways to set up syntax
highlighting for code blocks, either during build time using [Pygments][1] or
during runtime using a JavaScript syntax highlighter.
[1]: https://pygments.org
## Configuration
### Highlight
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] ·
:octicons-zap-24: Supersedes: [CodeHilite][4]
The [Highlight][3] extension, which is part of [Python Markdown Extensions][5],
integrates with Material for MkDocs and provides several options for
configuring syntax highlighting of code blocks:
`use_pygments`{: #use_pygments }
: :octicons-milestone-24: Default: `true` – This option allows to control
whether highlighting should be carried out during build time by
[Pygments][1] or runtime with a JavaScript highlighter. Remember to add the
necessary [additional stylesheets][6] and [JavaScript][7] if you want to
use the latter:
=== "Pygments"
``` yaml
markdown_extensions:
- pymdownx.highlight:
use_pygments: true
```
=== "JavaScript"
``` yaml
markdown_extensions:
- pymdownx.highlight:
use_pygments: false
```
??? example "Syntax highlighting with Highlight.js"
[Highlight.js][8] can be integrated by creating an [additional
JavaScript][7] file initializing the highlighter and including the
respective stylesheet and JavaScript from a [CDN][9] serving
Highlight.js in `mkdocs.yml`:
=== "docs/javascripts/extra.js"
``` js
hljs.initHighlighting()
```
=== "mkdocs.yml"
``` yaml
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js
- javascripts/extra.js
extra_css:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/default.min.css
```
Note that Highlight.js has no affiliation with the Highlight extension.
`linenums`{: #linenums }
: :octicons-milestone-24: Default: `false` – This option will add line numbers
to _all_ code blocks. If you wish to add line numbers to _some_, but not all
code blocks, consult the section on [adding line numbers][10] later in this
document, which also contains some tips on working with line numbers:
``` yaml
markdown_extensions:
- pymdownx.highlight:
linenums: true
```
`linenums_style`{: #linenums_style }
: :octicons-milestone-24: Default: `table` – The Highlight extension provides
three ways to add line numbers, all of which are supported by Material for
MkDocs. While `table` wraps a code block in a table, `inline` and
`pymdownx.inline` render line numbers as part of the line itself:
``` yaml
markdown_extensions:
- pymdownx.highlight:
linenums_style: pymdownx.inline
```
Note that `inline` will put line numbers next to the actual code, which
means that they will be included when selecting text with the cursor or
copying a code block to the clipboard. Thus, the usage of `table` or
`pymdownx.inline` is recommended.
_Material for MkDocs doesn't provide official support for the other options of
this extension, so they may be supported but can also yield weird results. Use
them at your own risk._
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_highlight.scss
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
[4]: https://python-markdown.github.io/extensions/code_hilite/
[5]: https://facelessuser.github.io/pymdown-extensions/
[6]: ../customization.md#additional-stylesheets
[7]: ../customization.md#additional-javascript
[8]: https://highlightjs.org/
[9]: https://cdnjs.com/libraries/highlight.js/
[10]: #adding-line-numbers
### InlineHilite
[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][11]
The [InlineHilite][11] extension, which is part of [Python Markdown
Extensions][5] also integrates with Material for MkDocs and adds support for
__syntax highlighting of inline code blocks__. It's built on top of the
[Highlight][3] extension and can be enabled from `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.inlinehilite
```
See the section on [inline code blocks][12] for usage information.
[11]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
[12]: #highlighting-inline-code-blocks
### SuperFences
[:octicons-file-code-24: Source][13] · [:octicons-workflow-24: Extension][14]
The [SuperFences][14] extension, which is also part of [Python Markdown
Extensions][5], allows for the __nesting of code blocks inside other blocks__,
and is therefore strongly recommended:
``` yaml
markdown_extensions:
- pymdownx.superfences
```
[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
[14]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
### Keys
[:octicons-file-code-24: Source][15] · [:octicons-workflow-24: Extension][16]
The [Keys][16] extension, which is part of [Python Markdown Extensions][5],
allows for inserting __keyboard keys__, e.g. ++ctrl+alt+delete++ , and
can be enabled from `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.keys
```
[15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_keys.scss
[16]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
## Usage
This section discusses how to use different syntax highlighting features with
[Pygments][1] – the default highlighter – so they don't apply when using
a JavaScript syntax highlighter.
### Specifying the language
Code blocks must be enclosed with two separate lines containing three backticks.
To add code highlighting to those blocks, add the language short name directly
after the opening block. See the [list of available lexers][17] to find the
short name for a given language.
_Example_:
```` markdown
``` python
import tensorflow as tf
```
````
_Result_:
``` python
import tensorflow as tf
```
[17]: https://pygments.org/docs/lexers/
### Adding line numbers
Line numbers can be added to a code block by using the `linenums="<start>"`
option directly after the short name, whereas `<start>` represents the starting
line number. A code block can start from a line number other than `1`, which
allows splitting large code blocks for readability.
_Example_:
```` markdown
``` python linenums="1"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
````
_Result_:
``` python linenums="1"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
### Highlighting specific lines
Specific lines can be highlighted by passing the line numbers to the `hl_lines`
argument placed right after the language short name. Note that line counts start
at `1`, regardless of the starting line number specified as part of `linenums`.
_Example_:
```` markdown
``` python hl_lines="2 3"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
````
_Result_:
``` python hl_lines="2 3"
def bubble_sort(items):
for i in range(len(items)):
for j in range(len(items) - 1 - i):
if items[j] > items[j + 1]:
items[j], items[j + 1] = items[j + 1], items[j]
```
### Highlighting inline code blocks
When [InlineHilite][18] is enabled, inline code blocks can be highlighted by
prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by
the [language short name][17].
_Example_:
```
The `#!python range()` function is used to generate a sequence of numbers.
```
_Result_:
The `#!python range()` function is used to generate a sequence of numbers.
[18]: #inlinehilite
### Displaying keyboard keys
When [Keys][19] is enabled, keyboard keys can be inserted with a simple syntax.
See the [Python Markdown Extensions][16] documentation for a list of all
available keys.
_Example_:
```
++ctrl+alt+del++
```
_Result_:
++ctrl+alt+del++
[19]: #keys

220
docs/reference/content-tabs.md Normal file
View File

@ -0,0 +1,220 @@
---
template: overrides/main.html
---
# Content tabs
Sometimes, it's desirable to group alternative content under different tabs,
e.g. when describing how to access an API from different languages or
environments. Material for MkDocs allows for beautiful and functional tabs, grouping code blocks and other content.
## Configuration
### Tabbed
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Tabbed][2] extension, which is part of [Python Markdown Extensions][3],
integrates with Material for MkDocs and can be enabled from `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.tabbed
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_tabbed.scss
[2]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
[3]: https://facelessuser.github.io/pymdown-extensions/
### SuperFences
[:octicons-file-code-24: Source][4] · [:octicons-workflow-24: Extension][5]
The [SuperFences][5] extension, which is also part of [Python Markdown
Extensions][3], allows for the __nesting of code blocks inside tabs__, and is
therefore strongly recommended:
``` yaml
markdown_extensions:
- pymdownx.superfences
```
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
[5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
## Usage
### Grouping code blocks
Code blocks are one of the primary targets to be grouped, and can be considered
a special case of content tabs, as tabs with a single code block are always
rendered without horizontal spacing.
_Example_:
```
=== "C"
``` c
#include <stdio.h>
int main(void) {
printf("Hello world!\n");
return 0;
}
```
=== "C++"
``` c++
#include <iostream>
int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}
```
```
_Result_:
=== "C"
``` c
#include <stdio.h>
int main(void) {
printf("Hello world!\n");
return 0;
}
```
=== "C++"
``` c++
#include <iostream>
int main(void) {
std::cout << "Hello world!" << std::endl;
return 0;
}
```
### Grouping other content
When a content tab contains more than one code block, it is rendered with
horizontal spacing. Vertical spacing is never added, but can be achieved
by nesting tabs in other blocks.
_Example_:
```
=== "Unordered list"
- Sed sagittis eleifend rutrum
- Donec vitae suscipit est
- Nulla tempor lobortis orci
=== "Ordered list"
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```
_Result_:
=== "Unordered list"
- Sed sagittis eleifend rutrum
- Donec vitae suscipit est
- Nulla tempor lobortis orci
=== "Ordered list"
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
### Embedded content
Content tabs can contain arbitrary nested content, including further content
tabs, and can be nested in other blocks like [admonitions][6], [details][7] or
blockquotes:
_Example_:
``` markdown
!!! example
=== "Unordered List"
_Example_:
``` markdown
- Sed sagittis eleifend rutrum
- Donec vitae suscipit est
- Nulla tempor lobortis orci
```
_Result_:
- Sed sagittis eleifend rutrum
- Donec vitae suscipit est
- Nulla tempor lobortis orci
=== "Ordered List"
_Example_:
``` markdown
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```
_Result_:
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```
_Result_:
!!! example
=== "Unordered List"
_Example_:
``` markdown
- Sed sagittis eleifend rutrum
- Donec vitae suscipit est
- Nulla tempor lobortis orci
```
_Result_:
- Sed sagittis eleifend rutrum
- Donec vitae suscipit est
- Nulla tempor lobortis orci
=== "Ordered List"
_Example_:
``` markdown
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
```
_Result_:
1. Sed sagittis eleifend rutrum
2. Donec vitae suscipit est
3. Nulla tempor lobortis orci
[6]: admonitions.md
[7]: admonitions.md#details

91
docs/reference/footnotes.md Normal file
View File

@ -0,0 +1,91 @@
---
template: overrides/main.html
---
# Footnotes
Footnotes are a great way to add references to supplemental or additional
information for a specific section of a document without interrupting the
document flow. Material for MkDocs provides the ability to insert inline
footnotes and render them at the bottom of the page.
## Configuration
### Footnotes
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Footnotes][2] extension, which is part of the standard Markdown library,
adds the ability to add inline footnotes to a document and can be enabled from
`mkdocs.yml`:
``` yaml
markdown_extensions:
- footnotes
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/_footnotes.scss
[2]: https://python-markdown.github.io/extensions/footnotes/
## Usage
### Adding footnote references
A footnote reference must be enclosed in square brackets and must start with a
caret `^`, directly followed by an arbitrary identifier, which is similar to
the standard Markdown link syntax.
_Example_:
``` markdown
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
```
_Result_:
Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2]
### Adding footnote content
The footnote content must be declared with the same identifier as the reference.
It can be inserted at an arbitrary position in the document and is always
rendered at the bottom of the page. Furthermore, a backlink to the footnote
reference is automatically added.
#### on a single line
Short statements can be written on the same line.
_Example_:
``` markdown
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
```
_Result_:
[Jump to footnote at the bottom of the page](#fn:1)
[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
#### on multiple lines
Paragraphs can be written on the next line and must be indented by four spaces.
_Example_:
``` markdown
[^2]:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
```
_Result_:
[^2]:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus
auctor massa, nec semper lorem quam in massa.
[Jump to footnote at the bottom of the page](#fn:2)

202
docs/reference/lists.md Normal file
View File

@ -0,0 +1,202 @@
---
template: overrides/main.html
---
# Lists
Material for MkDocs supports several flavors of lists that cater to different
use cases, including _unordered lists_ and _ordered lists_, which are supported
through standard Markdown, as well as _definition lists_ and _task lists_, which
are supported through extensions.
## Configuration
### Definition Lists
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Definition List][1] extension, which is part of the standard Markdown
library, adds the ability to add definitions lists to a document and can be
enabled from `mkdocs.yml`:
``` yaml
markdown_extensions:
- def_list
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_typeset.scss
[2]: https://python-markdown.github.io/extensions/definition_lists/
### Tasklist
[:octicons-file-code-24: Source][3] · [:octicons-workflow-24: Extension][4]
The [Tasklist][4] extension, which is part of [Python Markdown Extensions][5],
adds support for lists with styled checkboxes, and provides several options for
configuring the style:
`custom_checkbox`{: #custom_checkbox }
: :octicons-milestone-24: Default: `false` · This option toggles the rendering
style of checkboxes, replacing native checkbox styles with beautiful icons,
and is therefore _strongly recommended_:
``` yaml
markdown_extensions:
- pymdownx.tasklist:
custom_checkbox: true
```
`clickable_checkbox`{: #clickable_checkbox }
: :octicons-milestone-24: Default: `false` · This option toggles whether
checkboxes are clickable. As the state is not persisted, the use of this
option is _rather discouraged_ from a user experience perspective:
``` yaml
markdown_extensions:
- pymdownx.tasklist:
clickable_checkbox: true
```
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_tasklist.scss
[4]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
[5]: https://facelessuser.github.io/pymdown-extensions/
## Usage
### Using unordered lists
An unordered list can be written by prefixing a line with a `-`, `*` or `+`
list marker, all of which can be used interchangeably. Furthermore, all flavors
of lists can be nested inside each other.
_Example_:
``` markdown
* Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
lacinia sed. Aenean in finibus diam.
* Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
* Nam vulputate tincidunt fringilla.
* Nullam dignissim ultrices urna non auctor.
```
_Result_:
* Nulla et rhoncus turpis. Mauris ultricies elementum leo. Duis efficitur
accumsan nibh eu mattis. Vivamus tempus velit eros, porttitor placerat nibh
lacinia sed. Aenean in finibus diam.
* Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
* Nam vulputate tincidunt fringilla.
* Nullam dignissim ultrices urna non auctor.
### Using ordered lists
An ordered list must start with a number immediately followed by a dot. The
numbers do not need to be consecutive and can be all set to `1.`, as they will
be re-numbered when renderer.
_Example_:
``` markdown
1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
nulla. Vivamus a pharetra leo.
1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
ultricies libero efficitur sed.
2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
1. Mauris dictum mi lacus
2. Ut sit amet placerat ante
3. Suspendisse ac eros arcu
```
_Result_:
1. Vivamus id mi enim. Integer id turpis sapien. Ut condimentum lobortis
sagittis. Aliquam purus tellus, faucibus eget urna at, iaculis venenatis
nulla. Vivamus a pharetra leo.
1. Vivamus venenatis porttitor tortor sit amet rutrum. Pellentesque aliquet
quam enim, eu volutpat urna rutrum a. Nam vehicula nunc mauris, a
ultricies libero efficitur sed.
2. Morbi eget dapibus felis. Vivamus venenatis porttitor tortor sit amet
rutrum. Pellentesque aliquet quam enim, eu volutpat urna rutrum a.
1. Mauris dictum mi lacus
2. Ut sit amet placerat ante
3. Suspendisse ac eros arcu
### Using definition lists
[Definition lists][6] are a ideal for describing arbitrary key-value pairs, e.g.
the parameters of functions or modules, as used within this documentation to
describe extension or plugin parameters.
_Example_:
``` markdown
`Lorem ipsum dolor sit amet`
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
tellus non sem sollicitudin, quis rutrum leo facilisis.
`Cras arcu libero`
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
Nam vulputate tincidunt fringilla.
Nullam dignissim ultrices urna non auctor.
```
_Result_:
`Lorem ipsum dolor sit amet`
: Sed sagittis eleifend rutrum. Donec vitae suscipit est. Nullam tempus
tellus non sem sollicitudin, quis rutrum leo facilisis.
`Cras arcu libero`
: Aliquam metus eros, pretium sed nulla venenatis, faucibus auctor ex. Proin
ut eros sed sapien ullamcorper consequat. Nunc ligula ante.
Duis mollis est eget nibh volutpat, fermentum aliquet dui mollis.
Nam vulputate tincidunt fringilla.
Nullam dignissim ultrices urna non auctor.
[6]: #definition-lists
### Using tasklists
When the [Tasklist][7] extension is enabled, unordered list items can be
prefixed with `[ ]` to render an unchecked or `[x]` to render a checked
checkbox.
_Example_:
``` markdown
* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
* [ ] Vestibulum convallis sit amet nisi a tincidunt
* [x] In hac habitasse platea dictumst
* [x] In scelerisque nibh non dolor mollis congue sed et metus
* [ ] Praesent sed risus massa
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
```
_Result_:
* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
* [ ] Vestibulum convallis sit amet nisi a tincidunt
* [x] In hac habitasse platea dictumst
* [x] In scelerisque nibh non dolor mollis congue sed et metus
* [ ] Praesent sed risus massa
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
[7]: #tasklist

39
docs/extensions/metadata.md → docs/reference/meta-tags.md
View File

@ -1,27 +1,29 @@
---
template: overrides/main.html
hero: Set heroes with metadata
path: tree/master/docs/extensions
source: metadata.md
---
# Metadata
# Meta tags
[Metadata][1] is an extension included in the standard Markdown library that
makes it possible to control certain properties in a page-specific context,
e.g. the page title or description.
[1]: https://python-markdown.github.io/extensions/meta_data/
<!-- TBD -->
## Configuration
Add the following lines to `mkdocs.yml`:
### Metadata
[:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Metadata][1] extension, which is part of the standard Markdown
library, adds the ability to add custom metadata to a document and can be
enabled from `mkdocs.yml`:
``` yaml
markdown_extensions:
- meta
```
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[2]: https://python-markdown.github.io/extensions/meta_data/
## Usage
Metadata is written as a series of key-value pairs at the beginning of the
@ -116,20 +118,3 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
This will set the `meta` tag containing the site description inside the
document `head` for the current page to the provided value.
#### Disqus
As described in the [getting started guide][3], Disqus can be enabled on a
per-document basis:
``` markdown
disqus: your-shortname
```
Disqus can also be disabled for a specific page by setting it to an empty value:
``` markdown
disqus: ''
```
[3]: ../getting-started.md#disqus

30
docs/releases/4.md
View File

@ -1,30 +0,0 @@
---
template: overrides/main.html
---
# Upgrading to 4.x
## Highlights
Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix
includes a mandatory change of the base font-size from `10px` to `20px` which
means all `rem` values needed to be updated. Within the theme, `px` to `rem`
calculation is now encapsulated in a new function called `px2rem` which is part
of the SASS code base.
If you use Material for MkDocs with custom CSS that is based on `rem` values,
note that those values must now be divided by 2. Now, `1.0rem` doesn't map to
`10px`, but `20px`. To learn more about the problem and implications, please
refer to [the issue][1] in which the problem was discovered and fixed.
[1]: https://github.com/squidfunk/mkdocs-material/issues/911
## How to upgrade
### Changes to `mkdocs.yml`
None.
### Changes to `*.html` files
None.

55
docs/setup/adding-a-comment-system.md Normal file
View File

@ -0,0 +1,55 @@
---
template: overrides/main.html
---
# Adding a comment system
Material for MkDocs is natively integrated with [Disqus][1], a comment system
that provides a wide range of features like social integrations, user profiles,
as well as spam and moderation tools. Of course, other comment systems can be
integrated, too.
[1]: https://disqus.com/
## Configuration
### Disqus
First, ensure you've set [`site_url`][2] in `mkdocs.yml`. Then, to integrate
Material for MkDocs with [Disqus][1], create an account and a site giving you a
[shortname][3], and add it to `mkdocs.yml`:
``` yaml
extra:
disqus: <shortname>
```
This will insert a comment system on _every page, except the index page_.
[2]: https://www.mkdocs.org/user-guide/configuration/#site_url
[3]: https://help.disqus.com/en/articles/1717111-what-s-a-shortname
## Customization
### Selective integration
If the [Metadata][4] extension is enabled, you can disable or enable Disqus for
specific pages by adding the following to the front matter of a page:
=== "Enable Disqus"
``` markdown
---
disqus: <shortname>
---
```
=== "Disable Disqus"
``` markdown
---
disqus: ""
---
```
[4]: ../reference/meta-tags.md#metadata

100
docs/setup/adding-a-git-repository.md Normal file
View File

@ -0,0 +1,100 @@
---
template: overrides/main.html
---
# Adding a git repository
If your documentation is related to source code, Material for MkDocs provides
the ability to display information to the project's repository as part of the
static site, including statistics like stars and forks. Furthermore, certain
documents can be linked to specific source files.
## Configuration
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.:
``` yaml
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_.
[1]: 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`
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`:
``` 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_url
### Repository icon
[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default:
`fontawesome/brands/git-alt`
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`:
``` yaml
theme:
icon:
repo: fontawesome/brands/git-alt
```
Some popular choices:
- :fontawesome-brands-git: – `fontawesome/brands/git`
- :fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
- :fontawesome-brands-git-square: – `fontawesome/brands/git-square`
- :fontawesome-brands-github: – `fontawesome/brands/github`
- :fontawesome-brands-github-alt: – `fontawesome/brands/github-alt`
- :fontawesome-brands-github-square: – `fontawesome/brands/github-square`
- :fontawesome-brands-gitlab: – `fontawesome/brands/gitlab`
- :fontawesome-brands-gitkraken: – `fontawesome/brands/gitkraken`
- :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
- :fontawesome-solid-trash: – `fontawesome/solid/trash`
[4]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
### Edit button
[:octicons-file-code-24: Source][5] · :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`:
=== "Customize edit path"
``` yaml
edit_uri: edit/master/docs/
```
=== "Hide edit button"
``` yaml
edit_uri: ""
```
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L299-L308
[6]: https://github.com/
[7]: https://about.gitlab.com/
[8]: https://bitbucket.org/
[9]: https://www.mkdocs.org/user-guide/configuration/#edit_uri

90
docs/setup/adding-social-links.md Normal file
View File

@ -0,0 +1,90 @@
---
template: overrides/main.html
---
# Adding social links
The footer of your project documentation is a good place to add links to
websites or platforms you or your company are using as additional marketing
channels, e.g. :fontawesome-brands-medium:{: style="color: #00AB6C" },
:fontawesome-brands-twitter:{: style="color: #1DA1F2" } or
:fontawesome-brands-facebook:{: style="color: #3B5998" }, which can be
configured through `mkdocs.yml`.
## Configuration
### Social links
[:octicons-file-code-24: Source][1] ·
:octicons-milestone-24: Default: _none_
All _social links_ are rendered next to the copyright information as part of the
footer of your project documentation. Add a list of social links in `mkdocs.yml`
with:
``` yaml
extra:
social:
- icon: fontawesome/brands/twitter
link: https://twitter.com/squidfunk
```
For each entry, the following fields are available:
`icon`{: #icon }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must point to a valid icon path referencing [any icon bundled
with the theme][2], or the build will not succeed. Some popular choices:
- :fontawesome-brands-behance: – `fontawesome/brands/behance`
- :fontawesome-brands-docker: – `fontawesome/brands/docker`
- :fontawesome-brands-github: – `fontawesome/brands/github`
- :fontawesome-brands-instagram: – `fontawesome/brands/instagram`
- :fontawesome-brands-linkedin: – `fontawesome/brands/linkedin`
- :fontawesome-brands-medium: – `fontawesome/brands/medium`
- :fontawesome-brands-pied-piper-alt: – `fontawesome/brands/pied-piper-alt`
- :fontawesome-brands-product-hunt: – `fontawesome/brands/product-hunt`
- :fontawesome-brands-slack: – `fontawesome/brands/slack`
- :fontawesome-brands-twitter: – `fontawesome/brands/twitter`
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/social.html
[2]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
`link`{: #link }
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must contain a valid relative or absolute URL including the URI
scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
=== "Twitter"
``` yaml
extra:
social:
- icon: fontawesome/brands/twitter
link: https://twitter.com/squidfunk
```
=== "Email address"
``` yaml
extra:
social:
- icon: fontawesome/solid/paper-plane
link: mailto:<email-address>
```
`name`{: #name }
: :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ –
This field is used as the link's `title` attribute and can be set to a
discernable name to improve accessibility:
``` yaml
extra:
social:
- icon: fontawesome/brands/twitter
link: https://twitter.com/squidfunk
name: squidfunk on Twitter
```

257
docs/setup/changing-the-colors.md Normal file
View File

@ -0,0 +1,257 @@
---
template: overrides/main.html
---
# Changing the colors
As any good Material Design implementation, Material for MkDocs supports
Google's original [color palette][1], which can be easily configured through
`mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
fit your brand's identity by using [CSS variables][2].
[1]: http://www.materialui.co/colors
[2]: #custom-colors
## Configuration
### Color scheme
[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: `default`
Material for MkDocs supports two _color schemes_: a light mode, which is just
called `default`, and a dark mode, which is called `slate`. The color scheme
can be set from `mkdocs.yml`:
``` yaml
theme:
palette:
scheme: default
```
:material-cursor-default-click-outline: click on a tile to change the color
scheme:
<div class="tx-switch">
<button data-md-color-scheme="default"><code>default</code></button>
<button data-md-color-scheme="slate"><code>slate</code></button>
</div>
<script>
var buttons = document.querySelectorAll("button[data-md-color-scheme]")
buttons.forEach(function(button) {
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-color-scheme")
document.body.setAttribute("data-md-color-scheme", attr)
var name = document.querySelector("#__code_0 code span:nth-child(7)")
name.textContent = attr
})
})
</script>
The _color scheme_ can also be set based on _user preference_, which makes use
of the `prefers-color-scheme` media query, by setting the value in `mkdocs.yml`
to `preference`:
``` yaml
theme:
palette:
scheme: preference
```
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_scheme.scss
### Primary color
[:octicons-file-code-24: Source][4] · :octicons-milestone-24: Default: `indigo`
The _primary color_ is used for the header, the sidebar, text links and several
other components. In order to change the primary color, set the following value
in `mkdocs.yml` to a valid color name:
``` yaml
theme:
palette:
primary: indigo
```
:material-cursor-default-click-outline: click on a tile to change the primary
color:
<div class="tx-switch">
<button data-md-color-primary="red"><code>red</code></button>
<button data-md-color-primary="pink"><code>pink</code></button>
<button data-md-color-primary="purple"><code>purple</code></button>
<button data-md-color-primary="deep-purple"><code>deep purple</code></button>
<button data-md-color-primary="indigo"><code>indigo</code></button>
<button data-md-color-primary="blue"><code>blue</code></button>
<button data-md-color-primary="light-blue"><code>light blue</code></button>
<button data-md-color-primary="cyan"><code>cyan</code></button>
<button data-md-color-primary="teal"><code>teal</code></button>
<button data-md-color-primary="green"><code>green</code></button>
<button data-md-color-primary="light-green"><code>light green</code></button>
<button data-md-color-primary="lime"><code>lime</code></button>
<button data-md-color-primary="yellow"><code>yellow</code></button>
<button data-md-color-primary="amber"><code>amber</code></button>
<button data-md-color-primary="orange"><code>orange</code></button>
<button data-md-color-primary="deep-orange"><code>deep orange</code></button>
<button data-md-color-primary="brown"><code>brown</code></button>
<button data-md-color-primary="grey"><code>grey</code></button>
<button data-md-color-primary="blue-grey"><code>blue grey</code></button>
<button data-md-color-primary="black"><code>black</code></button>
<button data-md-color-primary="white"><code>white</code></button>
</div>
<script>
var buttons = document.querySelectorAll("button[data-md-color-primary]")
buttons.forEach(function(button) {
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-color-primary")
document.body.setAttribute("data-md-color-primary", attr)
var name = document.querySelector("#__code_2 code span:nth-child(7)")
name.textContent = attr.replace("-", " ")
})
})
</script>
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_primary.scss
### Accent color
[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default: `indigo`
The _accent color_ is used to denote elements that can be interacted with, e.g.
hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
chosing a valid color name:
``` yaml
theme:
palette:
accent: indigo
```
:material-cursor-default-click-outline: click on a tile to change the accent
color:
<style>
.md-typeset button[data-md-color-accent] > code {
background-color: var(--md-code-bg-color);
color: var(--md-accent-fg-color);
}
</style>
<div class="tx-switch">
<button data-md-color-accent="red"><code>red</code></button>
<button data-md-color-accent="pink"><code>pink</code></button>
<button data-md-color-accent="purple"><code>purple</code></button>
<button data-md-color-accent="deep-purple"><code>deep purple</code></button>
<button data-md-color-accent="indigo"><code>indigo</code></button>
<button data-md-color-accent="blue"><code>blue</code></button>
<button data-md-color-accent="light-blue"><code>light blue</code></button>
<button data-md-color-accent="cyan"><code>cyan</code></button>
<button data-md-color-accent="teal"><code>teal</code></button>
<button data-md-color-accent="green"><code>green</code></button>
<button data-md-color-accent="light-green"><code>light green</code></button>
<button data-md-color-accent="lime"><code>lime</code></button>
<button data-md-color-accent="yellow"><code>yellow</code></button>
<button data-md-color-accent="amber"><code>amber</code></button>
<button data-md-color-accent="orange"><code>orange</code></button>
<button data-md-color-accent="deep-orange"><code>deep orange</code></button>
</div>
<script>
var buttons = document.querySelectorAll("button[data-md-color-accent]")
buttons.forEach(function(button) {
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-color-accent")
document.body.setAttribute("data-md-color-accent", attr)
var name = document.querySelector("#__code_3 code span:nth-child(7)")
name.textContent = attr.replace("-", " ")
})
})
</script>
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/palette/_accent.scss
---
!!! warning "Accessibility – not all color combinations work well"
With __2__ (color schemes) __x 21__ (primary colors) __x 17__ (accent color)
= __714__ combinations, it's impossible to ensure that all configurations
provide a good user experience (e.g. _yellow on light background_), so make
sure that the color combination of your choosing provides enough contrast
and tweak CSS variables where necessary.
## Customization
### Custom colors
[:octicons-file-code-24: Source][6] ·
:octicons-mortar-board-24: Difficulty: _easy_
Material for MkDocs implements colors using [CSS variables][7] (custom
properties). If you want to customize the colors beyond the palette (e.g. to
use your brand-specific colors), you can add an [additional stylesheet][8] and
tweak the following CSS variables:
``` css
:root {
/* Default color shades */
--md-default-fg-color: hsla(0, 0%, 0%, 0.87);
--md-default-fg-color--light: hsla(0, 0%, 0%, 0.54);
--md-default-fg-color--lighter: hsla(0, 0%, 0%, 0.32);
--md-default-fg-color--lightest: hsla(0, 0%, 0%, 0.07);
--md-default-bg-color: hsla(0, 0%, 100%, 1);
--md-default-bg-color--light: hsla(0, 0%, 100%, 0.7);
--md-default-bg-color--lighter: hsla(0, 0%, 100%, 0.3);
--md-default-bg-color--lightest: hsla(0, 0%, 100%, 0.12);
/* Primary color shades */
--md-primary-fg-color: hsla(231, 48%, 48%, 1);
--md-primary-fg-color--light: hsla(231, 44%, 56%, 1);
--md-primary-fg-color--dark: hsla(232, 54%, 41%, 1);
--md-primary-bg-color: hsla(0, 0%, 100%, 1);
--md-primary-bg-color--light: hsla(0, 0%, 100%, 0.7);
/* Accent color shades */
--md-accent-fg-color: hsla(231, 99%, 66%, 1);
--md-accent-fg-color--transparent: hsla(231, 99%, 66%, 0.1);
--md-accent-bg-color: hsla(0, 0%, 100%, 1);
--md-accent-bg-color--light: hsla(0, 0%, 100%, 0.7);
}
```
The colors of [code blocks][9], [admonitions][10], text links and the footer can
be adjusted through dedicated CSS variables, which partly default to the base
colors or neutral colors:
``` css
:root > * {
/* Code color shades */
--md-code-bg-color: hsla(0, 0%, 96%, 1);
--md-code-fg-color: hsla(200, 18%, 26%, 1);
/* Text color shades */
--md-text-color: var(--md-default-fg-color);
--md-text-link-color: var(--md-primary-fg-color);
/* Admonition color shades */
--md-admonition-bg-color: var(--md-default-bg-color);
--md-admonition-fg-color: var(--md-default-fg-color);
/* Footer color shades */
--md-footer-bg-color: hsla(0, 0%, 0%, 0.87);
--md-footer-bg-color--dark: hsla(0, 0%, 0%, 0.32);
--md-footer-fg-color: hsla(0, 0%, 100%, 1);
--md-footer-fg-color--light: hsla(0, 0%, 100%, 0.7);
--md-footer-fg-color--lighter: hsla(0, 0%, 100%, 0.3);
}
```
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_colors.scss
[7]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[8]: ../customization.md#additional-stylesheets
[9]: ../reference/code-blocks.md
[10]: ../reference/admonitions.md

112
docs/setup/changing-the-fonts.md Normal file
View File

@ -0,0 +1,112 @@
---
template: overrides/main.html
---
# Changing the fonts
Material for MkDocs makes it easy to change the typeface of your project
documentation, as it directly integrates with [Google Fonts][1]. Alternatively,
fonts can be custom-loaded if self-hosting is preferred for data privacy reasons
or another destination should be used.
[1]: https://fonts.google.com
## Configuration
### Regular font
[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: [`Roboto`][3]
The _regular font_ is used for all body copy, headlines, and essentially
everything that does not need to be proportionally spaced. It can be set to any
valid [Google Font][1] with:
``` yaml
theme:
font:
text: Roboto
```
The typeface will be loaded in 300, 400, _400i_ and __700__.
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L120-L139
[3]: https://fonts.google.com/specimen/Roboto
### Proportional font
[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: [`Roboto Mono`][4]
The _proportional font_ is used for code blocks and can be configured separately.
Just like the regular font, it can be set to any valid [Google Font][1] from
`mkdocs.yml` with:
``` yaml
theme:
font:
code: Roboto Mono
```
The typeface will be loaded in 400.
[4]: https://fonts.google.com/specimen/Roboto+Mono
## Customization
If you want to load fonts from other destinations or don't want to use Google
Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, you may customize
font loading as described below.
### Disabling font loading
[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you want to prevent typefaces from being loaded from Google Fonts and fall
back to system fonts, add the following lines to `mkdocs.yml`:
``` yaml
theme:
font: false
```
### Additional fonts
[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you want to load an (additional) font from another destination, or override
the fallback font, you can use an [additional stylesheet][8] to add the
corresponding `@font-face` definition:
``` css
@font-face {
font-family: "<font>";
src: "...";
}
```
The font can then be applied to specific elements, e.g. only headlines, or
globally to be used as the site-wide regular or proportional font:
=== "Regular font"
``` css
body, input {
font-family: "<font>", -apple-system, Helvetica, Arial, sans-serif;
}
```
=== "Proportional font"
``` css
pre, code, kbd {
font-family: "<font>", SFMono-Regular, Consolas, Menlo, monospace;
}
```
[5]: ../data-privacy.md
[6]: ../customization.md#extending-the-theme
[7]: ../customization.md#overriding-blocks
[8]: ../customization.md#additional-stylesheets

156
docs/setup/changing-the-language.md Normal file
View File

@ -0,0 +1,156 @@
---
template: overrides/main.html
---
# Changing the language
Material for MkDocs supports internationalization (i18n) and provides
translations for template variables and labels in 40+ languages. Additionally,
search can be configured to use a language-specific stemmer (if available).
## Configuration
### Site language
[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en`
You can set the _site language_ from `mkdocs.yml` with:
``` yaml
theme:
language: en
```
The following languages are supported:
<ul class="tx-columns">
<li><code>af</code> – Afrikaans</li>
<li><code>ar</code> – Arabic</li>
<li><code>bn</code> – Bengali (Bangla)</li>
<li><code>ca</code> – Catalan</li>
<li><code>cs</code> – Czech</li>
<li><code>da</code> – Danish</li>
<li><code>de</code> – German</li>
<li><code>en</code> – English</li>
<li><code>es</code> – Spanish</li>
<li><code>et</code> – Estonian</li>
<li><code>fa</code> – Persian (Farsi)</li>
<li><code>fi</code> – Finnish</li>
<li><code>fr</code> – French</li>
<li><code>gl</code> – Galician</li>
<li><code>gr</code> – Greek</li>
<li><code>he</code> – Hebrew</li>
<li><code>hi</code> – Hindi</li>
<li><code>hr</code> – Croatian</li>
<li><code>hu</code> – Hungarian</li>
<li><code>id</code> – Indonesian</li>
<li><code>it</code> – Italian</li>
<li><code>ja</code> – Japanese</li>
<li><code>kr</code> – Korean</li>
<li><code>my</code> – Burmese</li>
<li><code>nl</code> – Dutch</li>
<li><code>nn</code> – Norwegian (Nynorsk)</li>
<li><code>no</code> – Norwegian</li>
<li><code>pl</code> – Polish</li>
<li><code>pt</code> – Portuguese</li>
<li><code>ro</code> – Romanian</li>
<li><code>ru</code> – Russian</li>
<li><code>sh</code> – Serbo-Croatian</li>
<li><code>si</code> – Slovenian</li>
<li><code>sk</code> – Slovak</li>
<li><code>sr</code> – Serbian</li>
<li><code>sv</code> – Swedish</li>
<li><code>th</code> – Thai</li>
<li><code>tr</code> – Turkish</li>
<li><code>uk</code> – Ukrainian</li>
<li><code>vi</code> – Vietnamese</li>
<li><code>zh</code> – Chinese (Simplified)</li>
<li><code>zh-Hant</code> – Chinese (Traditional)</li>
<li><code>zh-TW</code> – Chinese (Taiwanese)</li>
<li>
<a href="https://bit.ly/38F5RCa">
Add language
</a>
</li>
</ul>
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/language/en.html
### Site search language
[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: _automatically set_
Some languages, like Arabic or Japanese, need dedicated stemmers for search to
work properly. Material for MkDocs relies on [lunr-languages][3] to provide this
functionality. See the guide detailing how to [set up site search][4] for
more information.
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L49-L69
[3]: https://github.com/MihaiValentin/lunr-languages
[4]: setting-up-site-search.md
### Directionality
[:octicons-file-code-24: Source][5] ·
:octicons-milestone-24: Default: _automatically set_
While many languages are read `ltr` (left-to-right), Material for MkDocs also
supports `rtl` (right-to-left) _directionality_ which is inferred from the
selected language, but can also be set with:
``` yaml
theme:
direction: ltr
```
:material-cursor-default-click-outline: click on a tile to change the
directionality:
<div class="tx-switch">
<button data-md-dir="ltr"><code>ltr</code></button>
<button data-md-dir="rtl"><code>rtl</code></button>
</div>
<script>
var buttons = document.querySelectorAll("button[data-md-dir]")
buttons.forEach(function(button) {
button.addEventListener("click", function() {
var attr = this.getAttribute("data-md-dir")
document.body.dir = attr
var name = document.querySelector("#__code_1 code span:nth-child(5)")
name.textContent = attr
})
})
</script>
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L168
## Customization
### Translations
[:octicons-file-code-24: Source][1] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you want to customize some (or all) of the translations for your language,
you may follow the guide on [theme extension][6] and create a new partial in
`partials/language`, e.g. `en-custom.html`. Next, look up the translation you
want to change in the [base translation][1] and add it to the partial you just
created. Say, you want to change "__Table of contents__" to "__On this page__":
``` jinja
{% macro t(key) %}{{ {
"toc.title": "On this page"
}[key] }}{% endmacro %}
```
Then, add the following lines to `mkdocs.yml`:
``` yaml
theme:
language: en-custom
```
[6]: ../customization.md#extending-the-theme

130
docs/setup/changing-the-logo-and-icons.md Normal file
View File

@ -0,0 +1,130 @@
---
template: overrides/main.html
---
# Changing the logo and icons
When installing Material for MkDocs, you immediately get access to _over 7.000
icons_ ready to be used for customization of specific parts of the theme and/or
when writing your documentation in Markdown. Not enough? You can also [add
additional icons][1] with very little effort.
[1]: #additional-icons
## Configuration
### Logo
[:octicons-file-code-24: Source][2] ·
:octicons-milestone-24: Default: `material/library`
There're two ways to specify a _logo_: it must be a valid path to [any icon
bundled with the theme][3], or to a user-provided image located in the `docs`
folder. Both can be set from `mkdocs.yml`:
=== "Icon"
``` yaml
theme:
icon:
logo: material/library
```
=== "Image"
``` yaml
theme:
logo: assets/logo.png
```
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/logo.html
[3]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
### Favicon
[:octicons-file-code-24: Source][4] ·
:octicons-milestone-24: Default: `assets/images/favicon.png`
The _favicon_ can be changed to a path pointing to a user-provided image, which
must be located in the `docs` folder. It can be set from `mkdocs.yml`:
``` yaml
theme:
favicon: images/favicon.png
```
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L71
### Icons
[:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6]
The [Emoji][6] extension, which is part of [Python Markdown Extensions][7],
adds the ability to __integrate custom icons__ in the `*.svg` file format,
which are inlined into the HTML when [building your site][8]:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
```
The following icon sets are bundled with Material for MkDocs:
* :material-material-design: – [Material Design][9]
* :fontawesome-brands-font-awesome-flag: – [FontAwesome][10]
* :fontawesome-brands-github: – [Octicons][11]
If you want to add [additional icons][1], read on.
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_emoji.scss
[6]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[7]: https://facelessuser.github.io/pymdown-extensions/
[8]: ../creating-your-site.md#building-your-site
[9]: https://materialdesignicons.com/
[10]: https://fontawesome.com/icons?d=gallery&m=free
[11]: https://octicons.github.com/
## Customization
### Additional icons
[:octicons-file-code-24: Source][3] ·
:octicons-mortar-board-24: Difficulty: _moderate_
In order to add additional icons, [extend the theme][13] and create a folder
named `.icons` in the [`custom_dir`][14] you want to use for overrides. Next,
add your `*.svg` icons into a subfolder of the `.icons` folder. Let's say you
downloaded and unpacked the [Bootstrap][15] icon set, and want to add it to
your project documentation. The structure of your project should look like this:
``` sh
.
├─ docs/
│ └─ index.md
├─ overrides/
│ └─ .icons/
│ └─ bootstrap/
│ └─ *.svg
└─ mkdocs.yml
```
Then, add the following lines to `mkdocs.yml`:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
options:
custom_icons:
- overrides/.icons
```
You should now be able to use the :fontawesome-brands-bootstrap: Bootstrap
icons.
[13]: ../customization.md#extending-the-theme
[14]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
[15]: https://icons.getbootstrap.com/

182
docs/setup/setting-up-navigation.md Normal file
View File

@ -0,0 +1,182 @@
---
template: overrides/main.html
---
# Setting up navigation
A clear and concise navigation structure is an important aspect of good project
documentation. Material for MkDocs provides several options to configure the
behavior of navigational elements, some of those through _feature flags_.
## Configuration
### Instant loading
[:octicons-file-code-24: Source][1] ·
:octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental
When _instant loading_ is activated, clicks on all internal links will be
intercepted and dispatched via [XHR][2] without fully reloading the page. It
can be enabled from `mkdocs.yml` with:
``` yaml
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.
[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/instant/index.ts
[2]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
### Navigation tabs
[:octicons-file-code-24: Source][3] · :octicons-unlock-24: Feature flag
When _tabs_ are activated, top-level sections are rendered in a menu layer
below the header on big screens (but not when the sidebar is hidden). It can be
enabled from `mkdocs.yml` with:
``` yaml
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`][4] entry of `mkdocs.yml`
will be grouped under the first tab which will receive the title of the first
page.
This means that there will effectively be no collapsible subsections for the
first tab, because each subsection is rendered as another tab. If you want more
fine-grained control, _i.e. collapsible subsections for the first tab_, you can
use __top-level sections__, so that the top-level is entirely made up of
sections. This is illustrated in the following example:
=== "Top-level pages"
``` yaml
nav:
- Tab 1 + Page 1.1
- Page 1.2
- Tab 2:
- Page 2.1
- Page 2.2
- Page 2.3
- Page 1.3
```
=== "Top-level sections"
``` yaml
nav:
- Tab 1:
- Page 1.1
- Page 1.2
- Page 1.3
- Tab 2:
- Page 2.1
- Page 2.2
- Page 2.3
```
Note that tabs are only shown for larger screens, so make sure that navigation
is plausible on mobile devices. As another example, see the [`mkdocs.yml`][5]
used to render these pages.
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
[4]: https://www.mkdocs.org/user-guide/configuration/#nav
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
### Table of contents
[:octicons-file-code-24: Source][6] · [:octicons-workflow-24: Extension][7]
The [Table of contents][8] extension, which is part of the standard Markdown
library, provides some options that are supported by Material for MkDocs to
customize its appearance:
`permalink`{: #permalink }
: :octicons-milestone-24: Default: `false` – This option adds an anchor link
containing the paragraph symbol `¶` or another custom symbol at the end of
each headline, exactly like on the page you're currently viewing, which
Material for MkDocs will make appear on hover:
=== "¶"
``` yaml
markdown_extensions:
- toc:
permalink: true
```
=== "⚓︎"
``` yaml
markdown_extensions:
- toc:
permalink: ⚓︎
```
`slugify`{: #slugify }
: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
customization of the slug function. For some languages, the default may not
produce good and readable identifiers. Consider using another slug function
like for example those from [Python Markdown Extensions][9]:
=== "Unicode"
``` yaml
markdown_extensions:
- toc:
slugify: pymdownx.slugs.uslugify
```
=== "Unicode, case-sensitive"
``` yaml
markdown_extensions:
- toc:
slugify: pymdownx.slugs.uslugify_cased
```
`toc_depth`{: #toc_depth }
: :octicons-milestone-24: Default: `6` – Define the range of levels to be
included in the table of contents. This may be useful for project
documentation with deeply structured headings to decrease the length of the
table of contents, or to remove the table of contents altogether:
=== "Hide levels 4-6"
``` yaml
markdown_extensions:
- toc:
toc_depth: 3
```
=== "Hide table of contents"
``` yaml
markdown_extensions:
- toc:
toc_depth: 0
```
_Material for MkDocs doesn't provide official support for the other options of
this extension, so they may be supported but can also yield weird results. Use
them at your own risk._
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
[7]: https://python-markdown.github.io/extensions/toc/
[8]: https://python-markdown.github.io/extensions/toc/#usage
[9]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/

86
docs/setup/setting-up-site-analytics.md Normal file
View File

@ -0,0 +1,86 @@
---
template: overrides/main.html
---
# Setting up site analytics
As with any other service that is offered on the web, understanding how your
documentation is actually used can be an essential success factor. While
Material for MkDocs natively integrates with [Google Analytics][1], [other
analytics services][2] can be used, too.
[1]: https://developers.google.com/analytics
[2]: #using-other-analytics-services
## Configuration
### Google Analytics
[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: _none_
After heading over to your [Google Analytics][1] account to [create a new
property][4] in order to obtain a new tracking id of the form `UA-XXXXXXXX-X`,
add it to `mkdocs.yml`:
``` yaml
google_analytics:
- UA-XXXXXXXX-X
- auto
```
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html
[4]: https://support.google.com/analytics/answer/1042508
#### Enabling site search tracking
Besides basic page views, _site search_ can also be tracked to better understand
how people use your documentation and what they expect to find. To enable
search tracking:
1. Go to your Google Analytics __admin settings__
2. Select the property for the respective tracking code
3. Go to the __view settings__ tab.
4. Scroll down and enable __site search settings__
5. Set the __query parameter__ to `q`.
## Customization
### Using other analytics services
[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_
In order to integrate another analytics service provider offering an
asynchronous JavaScript-based tracking solution, you can [extend the theme][5]
and [override the `analytics` block][6]:
``` jinja
{% block analytics %}
{# Add custom analytics integration here #}
{% endblock %}
```
[5]: ../customization.md#extending-the-theme
[6]: ../customization.md#overriding-blocks
### Using instant loading
[:octicons-file-code-24: Source][2] ·
:octicons-mortar-board-24: Difficulty: _easy_
If you're using [instant loading][7], you may use the `location$` observable,
which will emit the current `URL` to listen for navigation events and register
a page view event with:
``` js
app.location$.subscribe(function(url) {
/* Add custom page event tracking here */
})
```
Note that this must be integrated with [additional JavaScript][8], and cannot be
included as part of the `analytics` block, which is included in the `head` of
the document.
[7]: setting-up-navigation.md#instant-loading
[8]: ../customization.md#additional-javascript

271
docs/setup/setting-up-site-search.md Normal file
View File

@ -0,0 +1,271 @@
---
template: overrides/main.html
---
# Setting up site search
Material for MkDocs provides a great, client-side search implementation,
omitting the need for the integration of third-party services, which might
violate data privacy regulations. Furthermore, with some effort, search can
be made available [offline][1].
[1]: #offline-search
## Configuration
### Built-in search
[:octicons-file-code-24: Source][2] ·
[:octicons-cpu-24: Plugin][3]
The [built-in search plugin][3] integrates seamlessly with Material for MkDocs,
adding multilingual client-side search with [lunr][4] and [lunr-languages][5].
It's enabled by default, but must be re-added to `mkdocs.yml` when other plugins
are used:
``` yaml
plugins:
- search
```
The following options are supported:
`lang`{: #lang }
: :octicons-milestone-24: Default: _automatically set_ – This option allows
to include the language-specific stemmers provided by [lunr-languages][5].
Note that Material for MkDocs will set this automatically based on the
[site language][6], but it may be overriden, e.g. to support multiple
languages:
=== "A single language"
``` yaml
plugins:
- search:
lang: ru
```
=== "Multiple languages"
``` yaml
plugins:
- search:
lang:
- en
- ru
```
The following languages are supported:
<ul class="tx-columns">
<li><code>ar</code> – Arabic</li>
<li><code>da</code> – Danish</li>
<li><code>du</code> – Dutch</li>
<li><code>en</code> – English</li>
<li><code>fi</code> – Finnish</li>
<li><code>fr</code> – French</li>
<li><code>de</code> – German</li>
<li><code>hu</code> – Hungarian</li>
<li><code>it</code> – Italian</li>
<li><code>ja</code> – Japanese</li>
<li><code>no</code> – Norwegian</li>
<li><code>pt</code> – Portuguese</li>
<li><code>ro</code> – Romanian</li>
<li><code>ru</code> – Russian</li>
<li><code>es</code> – Spanish</li>
<li><code>sv</code> – Swedish</li>
<li><code>th</code> – Thai</li>
<li><code>tr</code> – Turkish</li>
<li><code>vi</code> – Vietnamese</li>
</ul>
_Material for MkDocs also tries to support languages which are not part of
this list, by automatically chosing the best-matching stemmer_.
!!! warning "Only specify the languages you really need"
Be aware that including support for other languages increases the general
JavaScript payload by around 20kb (before `gzip`) and by another 15-30kb
per language.
`separator`{: #separator }
: :octicons-milestone-24: Default: _automatically set_ – The separator for
indexing and query tokenization can be customized, which makes it possible
to index parts of words that are separated by other characters than
whitespace and `-`, e.g. by including `.`:
``` yaml
plugins:
- search:
separator: '[\s\-\.]+'
```
`prebuild_index`{: #prebuild_index }
: :octicons-milestone-24: Default: `false` · :octicons-beaker-24:
Experimental – MkDocs can generate a [prebuilt index][7] of all pages during
build time, which provides performance improvements at the cost of more
bandwidth, as it reduces the build time of the search index:
``` yaml
plugins:
- search:
prebuild_index: true
```
This may be beneficial for large documentation projects served with
appropriate headers, i.e. `Content-Encoding: gzip`, but benchmarking before
deployment is recommended.
_Material for MkDocs doesn't provide official support for the other options of
this plugin, so they may be supported but can also yield weird results. Use
them at your own risk._
[2]: https://github.com/squidfunk/mkdocs-material/tree/master/src/assets/javascripts/integrations/search
[3]: https://www.mkdocs.org/user-guide/configuration/#search
[4]: https://lunrjs.com
[5]: https://github.com/MihaiValentin/lunr-languages
[6]: changing-the-language.md#site-language
[7]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
### Offline search
[:octicons-file-code-24: Source][8] ·
[:octicons-cpu-24: Plugin][9] · :octicons-beaker-24: Experimental
If you distribute your documentation as `*.html` files, the built-in search
will not work out-of-the-box due to the restrictions modern browsers impose for
security reasons. This can be mitigated with the [localsearch plugin][9] in
combination with @squidfunk's [iframe-worker][10] polyfill.
For setup instructions, refer to the [official documentation][11].
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L378-L390
[9]: https://github.com/wilhelmer/mkdocs-localsearch/
[10]: https://github.com/squidfunk/iframe-worker
[11]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5
## Customization
The search implementation of Material for MkDocs is probably its most
sophisticated feature, as it tries to balance a _great typeahead experience_,
_good performance_, _accessibility_ and a result list that is _easy to scan_.
This is where it deviates from other themes.
This section explains how search can be customized to tailor it to your needs.
### Query transformation
[:octicons-file-code-24: Source][12] ·
:octicons-mortar-board-24: Difficulty: _easy_
When a user enters a query into the search box, the query is pre-processed
before it is submitted to the search index. Material for MkDocs will apply the
following transformations, which can be customized by [extending the theme][13]:
``` ts
/**
* Default transformation function
*
* 1. Search for terms in quotation marks and prepend a `+` modifier to denote
* that the resulting document must contain all terms, converting the query
* to an `AND` query (as opposed to the default `OR` behavior). While users
* may expect terms enclosed in quotation marks to map to span queries, i.e.
* for which order is important, `lunr` doesn't support them, so the best
* we can do is to convert the terms to an `AND` query.
*
* 2. Replace control characters which are not located at the beginning of the
* query or preceded by white space, or are not followed by a non-whitespace
* character or are at the end of the query string. Furthermore, filter
* unmatched quotation marks.
*
* 3. Trim excess whitespace from left and right.
*
* 4. Append a wildcard to the end of every word to make every word a prefix
* query in order to provide a good typeahead experience, by adding an
* asterisk (wildcard) in between terms, which can be denoted by whitespace,
* any non-control character, or a word boundary.
*
* @param value - Query value
*
* @return Transformed query value
*/
function defaultTransform(value: string): string {
return value
.split(/"([^"]+)"/g) /* => 1 */
.map((terms, i) => i & 1
? terms.replace(/^\b|^(?![^\x00-\x7F]|$)|\s+/g, " +")
: terms
)
.join("")
.replace(/"|(?:^|\s+)[*+\-:^~]+(?=\s+|$)/g, "") /* => 2 */
.trim() /* => 3 */
.replace(/\s+|(?![^\x00-\x7F]|^)$|\b$/g, "* ") /* => 4 */
}
```
If you want to switch to the default behavior of the `mkdocs` or `readthedocs`
template, both of which don't transform the query prior to submission, or
customize the `transform` function, you can do this by [overriding the
`config` block][14]:
``` jinja
{% block config %}
<script>
var search = {
transform: function(query) {
return query
}
}
</script>
{% endblock %}
```
The `transform` function will receive the query string as entered by the user
and must return the processed query string to be submitted to the search index.
[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/transform/index.ts
[13]: ../customization.md#extending-the-theme
[14]: ../customization.md#overriding-blocks
### Custom search
[:octicons-file-code-24: Source][15] ·
:octicons-mortar-board-24: Difficulty: _challenging_
Material for MkDocs implements search as part of a [web worker][16]. If you
want to switch the web worker with your own implementation, e.g. to submit
search to an external service, you can add a custom JavaScript file to the `docs`
directory and [override the `config` block][14]:
``` jinja
{% block config %}
<script>
var search = {
worker: "<url>"
}
</script>
{% endblock %}
```
Communication with the search worker is implemented using a standardized
message format using _discriminated unions_, i.e. through the `type` property
of the message. See the following interface definitions to learn about the
message formats:
- [:octicons-file-code-24: `SearchMessage`][17]
- [:octicons-file-code-24: `SearchIndex` and `SearchResult`][18]
The sequence and direction of messages is rather intuitive:
- :octicons-arrow-right-24: `SearchSetupMessage`
- :octicons-arrow-left-24: `SearchReadyMessage`
- :octicons-arrow-right-24: `SearchQueryMessage`
- :octicons-arrow-left-24: `SearchResultMessage`
[15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker
[16]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers
[17]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/message/index.ts
[18]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/_/index.ts

116
docs/sponsorship.md Normal file
View File

@ -0,0 +1,116 @@
---
template: overrides/main.html
---
# <span hidden>Sponsorship</span> :logo: :material-plus: :octicons-heart-fill-24:
Material for MkDocs uses the [sponsorware][1] release strategy, which means that
__new features are first exclusively released to sponsors__. Read on to learn
[how sponsorship works][2] and how you can [become a sponsor][3] to enjoy the
latest features before everybody else.
[1]: https://github.com/sponsorware/docs
[2]: #how-sponsorship-works
[3]: #how-to-become-a-sponsor
## How sponsorship works
__Material for MkDocs is split into a community edition and a sponsor edition__.
New features will first land in the _sponsor edition_, which means that sponsors
will have access immediately. Every feature is tied to a funding goal in monthly
subscriptions. If this funding goal is hit, the feature is merged into the
_community edition_ and released to the public to be generally available. Bugs
will be fixed in the community edition and merged back into the sponsor edition.
See the [roadmap][4] for a list of available and upcoming features of the
_sponsor edition_, and for demonstration purposes, [__the official docs built
with the sponsor edition__][5].
[4]: #roadmap
[5]: https://squidfunk.github.io/mkdocs-material-next/
## How to become a sponsor
You've decided to become a sponsor? Great! You're just __three easy steps__ away
from enjoying the latest features of Material for MkDocs. Complete the following
steps and you're in:
- Visit [squidfunk's sponsor profile][6] and pick a tier that includes exclusive
access to squidfunk's sponsorware, which is any tier above $10/month. Select
the tier and complete the checkout.
- Within 24 hours, you will be added as a collaborator to a private GitHub
repository, which contains a fork of Material for MkDocs with [brand new and
exclusive features][7].
- Create a [personal access token][8], which allows installing the _sponsor
edition_ of Material for MkDocs from any destination, including other CI
providers like [GitLab][9] or [Bitbucket][10].
__Congratulations! :partying_face: You're now officially a sponsor and can use
the sponsor edition until you decide to cancel your monthly subscription, which
you're free to do at any time.__
[6]: https://github.com/sponsors/squidfunk
[7]: #roadmap
[8]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[9]: https://gitlab.com
[10]: https://bitbucket.org
## Roadmap
The following list of funding goals – named after varieties of chili peppers
[I'm growing on my balcony][11] – shows, which features are already part of the
sponsor edition or yet to come.
[11]: https://www.instagram.com/squidfunk/
### Madame Jeanette
[:octicons-fire-24: Funding goal: __$500__][6] ·
:octicons-lock-24: Status: _exclusively available_
Improve search UI and UX to show relevant results more prominently, show missing
terms that were not found on a specific page and highlight terms found when
following a search result.
- [x] #1790 – Added grouping of search results
- [x] #1799 – Added missing query terms to search result
- [x] #1799 – Improved search result relevance and scoring
- [ ] TBD – Improved search result summaries
- [ ] TBD – Added highlighting of query terms on target pages
### Bhut Jolokia
[:octicons-fire-24: Funding goal: __$1,500__][6] ·
:octicons-lock-24: Status: _pending_
Add native support to Material for MkDocs to build and deploy multiple versions
of a single documentation project, with the help of a plugin.
### Caribbean Red
[:octicons-fire-24: Funding goal: __$3,000__][6] ·
:octicons-lock-24: Status: _pending_
Add an alternative, completely different _vertical layout_, optimized to read
documentation and code side-by-side, e.g. for the documentation of APIs.
## Terms
Regardless of whether you're an individual or a company, you may use the
_sponsor edition_ exactly under the same terms as the _community edition_,
which are given by the [MIT license][12]. However, we kindly ask you to respect
the following guidelines:
- Please __don't distribute the source code__ from the _sponsor edition_.
You may freely use it for public, private or commercial projects, fork it,
mirror it, do whatever you want with it, as long as you're not releasing the
source code, as this would cannibalize the sponsorware model.
- If you cancel your subscription, you're removed as a collaborator and will not
receive future updates of the sponsor edition. However, you may continue to
use the latest version that's available to you for __as long as you like__.
Just remember that __[GitHub deletes private forks][13]__.
[12]: license.md
[13]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

102
docs/troubleshooting.md Normal file
View File

@ -0,0 +1,102 @@
---
template: overrides/main.html
---
# Troubleshooting
## 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:
1. __Installing in a virtual environment__: Virtual environments provide an easy
way of encapsulation.
2. __Installing in user space__: Provide the `--user` flag to the install
command and `pip` will install the package in a user-site location. Note
that while this is not a global installation, it's still not
3. __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`.
### 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][9]. First, ensure
that you have a Python version of 3 or higher installed:
``` sh
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 with `pip`, which will download and install
all packages in the `venv` folder you just created, including MkDocs and its
dependencies:
``` sh
pip install mkdocs-material
```
Verify that MkDocs and Material for MkDocs were both installed correctly:
``` sh
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
```
[9]: https://docs.python.org/3/tutorial/venv.html
## 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.

72
docs/releases/5.md → docs/upgrading.md
View File

@ -2,29 +2,43 @@
template: overrides/main.html
---
# Upgrading to 5.x
# Upgrading
## Highlights
Upgrade to the latest version with:
``` sh
pip install --upgrade mkdocs-material
```
Inspect the currently installed version with:
``` sh
pip show mkdocs-material
```
## Upgrading from 4.x to 5.x
### What's new?
* Reactive architecture – try `app.dialog$.next("Hi!")` in the console
* [Instant loading][5] – make Material behave like a Single Page Application
* Improved CSS customization with [CSS variables][1] – set your brand's colors
* [Instant loading][1] – make Material behave like a Single Page Application
* Improved CSS customization with [CSS variables][2] – set your brand's colors
* Improved CSS resilience, e.g. proper sidebar locking for customized headers
* Improved [icon integration][6] and configuration – now including over 5k icons
* Improved [icon integration][3] and configuration – now including over 5k icons
* Added possibility to use any icon for logo, repository and social links
* Search UI does not freeze anymore (moved to web worker)
* Search index built only once when using instant loading
* Improved extensible keyboard handling
* Support for [prebuilt search indexes][2]
* Support for [prebuilt search indexes][4]
* Support for displaying stars and forks for GitLab repositories
* Support for scroll snapping of sidebars and search results
* Reduced HTML and CSS footprint due to deprecation of Internet Explorer support
* Slight facelifting of some UI elements (Admonitions, tables, ...)
[1]: https://github.com/squidfunk/mkdocs-material/blob/081d540127c41703da3d73aa69eb521615c1cb89/src/assets/stylesheets/base/_colors.scss#L27-L55
[2]: https://www.mkdocs.org/user-guide/configuration/#prebuild_index
## How to upgrade
[1]: setup/setting-up-navigation.md#instant-loading
[2]: setup/changing-the-colors.md#custom-colors
[3]: setup/changing-the-logo-and-icons.md#icons
[4]: setup/setting-up-site-search.md#built-in-search
### Changes to `mkdocs.yml`
@ -34,7 +48,7 @@ does not contain the key, you can skip it.
#### `theme.feature`
Optional features like [tabs][4] and [instant loading][5] are now implemented as
Optional features like [tabs][5] and [instant loading][1] are now implemented as
flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`:
=== "5.x"
@ -54,13 +68,12 @@ flags and can be enabled by listing them in `mkdocs.yml` under `theme.features`:
tabs: true
```
[4]: ../../getting-started/#tabs
[5]: ../../getting-started/#instant-loading
[5]: setup/setting-up-navigation.md#navigation-tabs
#### `theme.logo.icon`
The logo icon configuration was centralized under `theme.icon.logo` and can now
be set to any of the [icons bundled with the theme][6]:
be set to any of the [icons bundled with the theme][3]:
=== "5.x"
@ -70,8 +83,6 @@ be set to any of the [icons bundled with the theme][6]:
logo: material/cloud
```
[6]: ../../getting-started/#icons
=== "4.x"
``` yaml
@ -83,7 +94,7 @@ be set to any of the [icons bundled with the theme][6]:
#### `extra.repo_icon`
The repo icon configuration was centralized under `theme.icon.repo` and can now
be set to any of the [icons bundled with the theme][6]:
be set to any of the [icons bundled with the theme][3]:
=== "5.x"
@ -102,7 +113,7 @@ be set to any of the [icons bundled with the theme][6]:
#### `extra.search.*`
Search is now configured as part of the [plugin options][7]. Note that the
Search is now configured as part of the [plugin options][6]. Note that the
search languages must now be listed as an array of strings and the `tokenizer`
was renamed to `separator`:
@ -127,7 +138,7 @@ was renamed to `separator`:
tokenizer: [\s\-\.]+
```
[7]: ../../plugins/search/#configuration
[6]: setup/setting-up-site-search.md#built-in-search
#### `extra.social.*`
@ -869,3 +880,26 @@ matches the new structure:
{% endif %}
</nav>
```
## Upgrading from 3.x to 4.x
### What's new?
Material for MkDocs 4 fixes incorrect layout on Chinese systems. The fix
includes a mandatory change of the base font-size from `10px` to `20px` which
means all `rem` values needed to be updated. Within the theme, `px` to `rem`
calculation is now encapsulated in a new function called `px2rem` which is part
of the SASS code base.
If you use Material for MkDocs with custom CSS that is based on `rem` values,
note that those values must now be divided by 2. Now, `1.0rem` doesn't map to
`10px`, but `20px`. To learn more about the problem and implications, please
refer to #911 in which the problem was discovered and fixed.
### Changes to `mkdocs.yml`
None.
### Changes to `*.html` files
None.

2
material/assets/javascripts/bundle.1b3af799.min.js vendored Normal file
View File

File diff suppressed because one or more lines are too long

2
material/assets/javascripts/bundle.2a81e305.min.js.map → material/assets/javascripts/bundle.1b3af799.min.js.map
View File

File diff suppressed because one or more lines are too long

2
material/assets/javascripts/bundle.2a81e305.min.js vendored
View File

File diff suppressed because one or more lines are too long

4
material/assets/javascripts/vendor.568ba93b.min.js → material/assets/javascripts/vendor.877163d5.min.js vendored
View File

File diff suppressed because one or more lines are too long

2
material/assets/javascripts/vendor.568ba93b.min.js.map → material/assets/javascripts/vendor.877163d5.min.js.map
View File

File diff suppressed because one or more lines are too long

18
material/assets/manifest.json
View File

@ -1,12 +1,14 @@
{
"assets/javascripts/bundle.js": "assets/javascripts/bundle.2a81e305.min.js",
"assets/javascripts/bundle.js.map": "assets/javascripts/bundle.2a81e305.min.js.map",
"assets/javascripts/vendor.js": "assets/javascripts/vendor.568ba93b.min.js",
"assets/javascripts/vendor.js.map": "assets/javascripts/vendor.568ba93b.min.js.map",
"assets/javascripts/bundle.js": "assets/javascripts/bundle.1b3af799.min.js",
"assets/javascripts/bundle.js.map": "assets/javascripts/bundle.1b3af799.min.js.map",
"assets/javascripts/vendor.js": "assets/javascripts/vendor.877163d5.min.js",
"assets/javascripts/vendor.js.map": "assets/javascripts/vendor.877163d5.min.js.map",
"assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js",
"assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.a68abb33.min.js.map",
"assets/stylesheets/main.css": "assets/stylesheets/main.61729dd2.min.css",
"assets/stylesheets/main.css.map": "assets/stylesheets/main.61729dd2.min.css.map",
"assets/stylesheets/palette.css": "assets/stylesheets/palette.e185632b.min.css",
"assets/stylesheets/palette.css.map": "assets/stylesheets/palette.e185632b.min.css.map"
"assets/stylesheets/main.css": "assets/stylesheets/main.364d010a.min.css",
"assets/stylesheets/main.css.map": "assets/stylesheets/main.364d010a.min.css.map",
"assets/stylesheets/overrides.css": "assets/stylesheets/overrides.823d2928.min.css",
"assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.823d2928.min.css.map",
"assets/stylesheets/palette.css": "assets/stylesheets/palette.a53427c9.min.css",
"assets/stylesheets/palette.css.map": "assets/stylesheets/palette.a53427c9.min.css.map"
}

3
material/assets/stylesheets/main.364d010a.min.css vendored Normal file
View File

File diff suppressed because one or more lines are too long

1
material/assets/stylesheets/main.364d010a.min.css.map Normal file
View File

File diff suppressed because one or more lines are too long

3
material/assets/stylesheets/main.61729dd2.min.css vendored
View File

File diff suppressed because one or more lines are too long

1
material/assets/stylesheets/main.61729dd2.min.css.map
View File

File diff suppressed because one or more lines are too long

3
material/assets/stylesheets/overrides.823d2928.min.css vendored Normal file
View File

@ -0,0 +1,3 @@
:root{--md-admonition-icon--sponsor: url( 'data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 20.408c-.492.308-.903.546-1.192.709-.153.086-.308.17-.463.252h-.002a.75.75 0 01-.686 0 16.709 16.709 0 01-.465-.252 31.147 31.147 0 01-4.803-3.34C3.8 15.572 1 12.331 1 8.513 1 5.052 3.829 2.5 6.736 2.5 9.03 2.5 10.881 3.726 12 5.605 13.12 3.726 14.97 2.5 17.264 2.5 20.17 2.5 23 5.052 23 8.514c0 3.818-2.801 7.06-5.389 9.262A31.146 31.146 0 0114 20.408z"/></svg>' )}.md-typeset .admonition.sponsor{border-color:#ea4aaa}.md-typeset .sponsor>.admonition-title{background-color:rgba(234,74,170,.1)}.md-typeset .sponsor>.admonition-title::before{background-color:#ea4aaa;-webkit-mask-image:var(--md-admonition-icon--sponsor);mask-image:var(--md-admonition-icon--sponsor)}.md-announce a,.md-announce a:focus,.md-announce a:hover{color:currentColor}.md-announce strong{white-space:nowrap}.md-announce .twitter{margin-left:.2em;color:#00acee}@-webkit-keyframes tx-sponsor{0%,40%,80%,100%{transform:scale(1)}20%,60%{transform:scale(1.1)}}@keyframes tx-sponsor{0%,40%,80%,100%{transform:scale(1)}20%,60%{transform:scale(1.1)}}.tx-sponsor{margin-top:1rem;text-align:center}.tx-sponsor a{color:#e91e63;font-variant:all-petite-caps}.tx-sponsor hr{display:inline-block;width:2rem;margin:1em;vertical-align:middle;background-color:currentColor;border:none}.tx-sponsor__heart{-webkit-animation:tx-sponsor 1000ms infinite;animation:tx-sponsor 1000ms infinite}.md-typeset .tx-switch button{cursor:pointer;transition:opacity 250ms}.md-typeset .tx-switch button:hover{opacity:.75}.md-typeset .tx-switch button>code{display:block;color:var(--md-primary-bg-color);background-color:var(--md-primary-fg-color)}.md-typeset .tx-columns{-moz-columns:2;columns:2}.md-typeset .tx-columns>*{-moz-column-break-inside:avoid;break-inside:avoid}
/*# sourceMappingURL=overrides.823d2928.min.css.map*/

1
material/assets/stylesheets/overrides.823d2928.min.css.map Normal file
View File

File diff suppressed because one or more lines are too long

4
material/assets/stylesheets/palette.e185632b.min.css → material/assets/stylesheets/palette.a53427c9.min.css vendored
View File

File diff suppressed because one or more lines are too long

1
material/assets/stylesheets/palette.a53427c9.min.css.map Normal file
View File

File diff suppressed because one or more lines are too long

1
material/assets/stylesheets/palette.e185632b.min.css.map
View File

File diff suppressed because one or more lines are too long

8
material/base.html
View File

@ -41,9 +41,9 @@
{% endif %}
{% endblock %}
{% block styles %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.61729dd2.min.css' | url }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.364d010a.min.css' | url }}">
{% if palette.scheme or palette.primary or palette.accent %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.e185632b.min.css' | url }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.a53427c9.min.css' | url }}">
{% endif %}
{% if palette.primary %}
{% import "partials/palette.html" as map %}
@ -182,8 +182,8 @@
{% endblock %}
</div>
{% block scripts %}
<script src="{{ 'assets/javascripts/vendor.568ba93b.min.js' | url }}"></script>
<script src="{{ 'assets/javascripts/bundle.2a81e305.min.js' | url }}"></script>
<script src="{{ 'assets/javascripts/vendor.877163d5.min.js' | url }}"></script>
<script src="{{ 'assets/javascripts/bundle.1b3af799.min.js' | url }}"></script>
{%- set translations = {} -%}
{%- for key in [
"clipboard.copy",

29
material/overrides/main.html
View File

@ -22,9 +22,9 @@
<meta name="twitter:title" content="{{ title }}">
<meta name="twitter:description" content="{{ config.site_description }}">
<meta name="twitter:image" content="{{ image }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/overrides.823d2928.min.css' | url }}">
{% endblock %}
{% block announce %}
<style>.md-announce a,.md-announce a:focus,.md-announce a:hover{color:currentColor}.md-announce strong{white-space:nowrap}.md-announce .twitter{margin-left:.2em;color:#00acee}</style>
<a href="https://twitter.com/squidfunk">
For updates follow <strong>@squidfunk</strong> on
<span class="twemoji twitter">
@ -35,3 +35,30 @@
<strong>Twitter</strong>
</a>
{% endblock %}
{% block content %}
{{ super() }}
<aside class="tx-sponsor md-typeset">
<a href="{{ 'sponsorship' | url }}" title="Becoming a sponsor">
<hr>
<span class="twemoji">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 89 89">
<path d="M3.136 17.387v42.932l42.932 21.467L3.136 17.387z"></path>
<path fill-opacity=".5" d="M21.91 8l42.933 64.398-18.775 9.388L3.136 17.387 21.91 8z"></path>
<path d="M67.535 17.387L40.273 35.543l21.878 32.818 5.384 2.691V17.387z"></path>
<path fill-opacity=".25" d="M67.535 17.387v53.666l18.774-9.388V8l-18.774 9.387z"></path>
</svg>
</span>
<span class="twemoji">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z"></path>
</svg>
</span>
<span class="twemoji tx-sponsor__heart">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M14 20.408c-.492.308-.903.546-1.192.709-.153.086-.308.17-.463.252h-.002a.75.75 0 01-.686 0 16.709 16.709 0 01-.465-.252 31.147 31.147 0 01-4.803-3.34C3.8 15.572 1 12.331 1 8.513 1 5.052 3.829 2.5 6.736 2.5 9.03 2.5 10.881 3.726 12 5.605 13.12 3.726 14.97 2.5 17.264 2.5 20.17 2.5 23 5.052 23 8.514c0 3.818-2.801 7.06-5.389 9.262A31.146 31.146 0 0114 20.408z"></path>
</svg>
</span>
<hr>
</a>
</aside>
{% endblock %}

11
material/partials/more.html
View File

@ -1,11 +0,0 @@
{#-
This file was automatically generated - do not edit
-#}
<div class="md-more">
<input class="md-toggle" data-md-toggle="more" type="checkbox" id="__more" autocomplete="off">
<ul class="md-more__list">
<li class="md-more__item">Item 1</li>
<li class="md-more__item">Item 2</li>
<li class="md-more__item">Item 3</li>
</ul>
</div>

2
material/partials/source-link.html
View File

@ -6,7 +6,7 @@
{% if repo | last == "/" %}
{% set repo = repo[:-1] %}
{% endif %}
{% set path = page.meta.path | default([""]) %}
{% set path = page.meta.path | default("") %}
<a href="{{ [repo, path, page.meta.source] | join('/') }}" title="{{ page.meta.source }}" class="md-content__button md-icon">
{{ lang.t("meta.source") }}
{% set icon = config.theme.icon.repo or "fontawesome/brands/git-alt" %}

66
mkdocs.yml
View File

@ -67,6 +67,20 @@ theme:
# Plugins
plugins:
- search
- redirects:
redirect_maps:
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
plugins/search.md: setup/setting-up-site-search.md
# plugins/minification.md:
# plugins/revision-date.md:
# plugins/awesome-pages.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
- minify:
minify_html: true
@ -90,8 +104,6 @@ extra:
markdown_extensions:
- markdown.extensions.admonition
- markdown.extensions.attr_list
- markdown.extensions.codehilite:
guess_lang: false
- markdown.extensions.def_list
- markdown.extensions.footnotes
- markdown.extensions.meta
@ -106,8 +118,7 @@ markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:materialx.emoji.to_svg
# - pymdownx.highlight:
# linenums_style: pymdownx-inline
- pymdownx.highlight
- pymdownx.inlinehilite
- pymdownx.keys
- pymdownx.magiclink:
@ -127,27 +138,38 @@ markdown_extensions:
# Page tree
nav:
- Home: index.md
- Getting started: getting-started.md
- Extensions:
- Admonition: extensions/admonition.md
- CodeHilite: extensions/codehilite.md
- Footnotes: extensions/footnotes.md
- Metadata: extensions/metadata.md
- Permalinks: extensions/permalinks.md
- PyMdown: extensions/pymdown.md
- Plugins:
- Search: plugins/search.md
- Minification: plugins/minification.md
- Revision date: plugins/revision-date.md
- Awesome pages: plugins/awesome-pages.md
- Releases:
- Upgrading to 5.x: releases/5.md
- Upgrading to 4.x: releases/4.md
- Changelog: releases/changelog.md
- Getting started:
- Installation: getting-started.md
- 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
- Contributing: contributing.md
- Sponsorship: sponsorship.md
- License: license.md
- Setup:
- 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
- Adding social links: setup/adding-social-links.md
- Adding a git repository: setup/adding-a-git-repository.md
- Adding a comment system: setup/adding-a-comment-system.md
#- Adding an announcement bar: setup/adding-an-announcement-bar.md
#- Adding a landing page: setup/adding-a-landing-page.md
- Reference:
- Admonitions: reference/admonitions.md
- Code blocks: reference/code-blocks.md
- Content tabs: reference/content-tabs.md
- Footnotes: reference/footnotes.md
- Lists: reference/lists.md
- Meta tags: reference/meta-tags.md
- Changelog:
- Release notes: changelog.md
- Upgrading: upgrading.md
# Google Analytics
google_analytics:

4
netlify.toml
View File

@ -21,6 +21,8 @@
[build]
publish = "site"
command = """
pip install mkdocs-minify-plugin
pip install \
mkdocs-minify-plugin>=0.3 \
mkdocs-redirects>=1.0
python -m mkdocs build
"""

2
src/assets/javascripts/integrations/search/transform/index.ts
View File

@ -55,7 +55,7 @@ export type SearchTransformFn = (value: string) => string
* 3. Trim excess whitespace from left and right.
*
* 4. Append a wildcard to the end of every word to make every word a prefix
* query in order to provide a good type-ahead experience, by adding an
* query in order to provide a good typeahead experience, by adding an
* asterisk (wildcard) in between terms, which can be denoted by whitespace,
* any non-control character, or a word boundary.
*

5
src/assets/stylesheets/base/_colors.scss
View File

@ -57,6 +57,11 @@
--md-code-bg-color: hsla(0, 0%, 96%, 1);
--md-code-fg-color: hsla(200, 18%, 26%, 1);
// Keyboard color shades
--md-kbd-color: hsla(0, 0%, 98%, 1);
--md-kbd-accent-color: hsla(0, 100%, 100%, 1);
--md-kbd-border-color: hsla(0, 0%, 72%, 1);
// Text color shades
--md-text-color: var(--md-default-fg-color);
--md-text-link-color: var(--md-primary-fg-color);

14
src/assets/stylesheets/base/_typeset.scss
View File

@ -52,7 +52,7 @@ kbd {
// ----------------------------------------------------------------------------
// Content that is typeset - if possible, all margins, paddings and font sizes
// should be set in ems, so nested blocks (e.g. Admonition) render correctly,
// should be set in ems, so nested blocks (e.g. admonitions) render correctly,
// except headlines that should only appear on the top level and need to have
// consistent spacing due to layout constraints.
.md-typeset {
@ -246,19 +246,21 @@ kbd {
}
}
// Keystrokes
// Keyboard key
kbd {
display: inline-block;
padding: 0 px2em(8px, 12px);
color: var(--md-default-fg-color);
font-size: px2em(12px);
line-height: 1.5;
vertical-align: text-top;
word-break: break-word;
background-color: var(--md-kbd-color);
border-radius: px2rem(2px);
box-shadow:
0 px2rem(2px) 0 px2rem(1px) var(--md-default-fg-color--lighter),
0 px2rem(2px) 0 var(--md-default-fg-color--lighter),
inset 0 px2rem(-2px) px2rem(4px) var(--md-default-bg-color);
0 px2rem(2px) 0 px2rem(1px) var(--md-kbd-border-color),
0 px2rem(2px) 0 var(--md-kbd-border-color),
0 px2rem(-2px) px2rem(4px) var(--md-kbd-accent-color) inset;
}
// Text highlighting marker
@ -374,7 +376,7 @@ kbd {
// Definition lists
dd {
margin: 1em 0 1em px2em(30px, 16px);
margin: 1em 0 1.5em px2em(30px, 16px);
// Adjust for right-to-left languages
[dir="rtl"] & {

14
src/assets/stylesheets/extensions/_admonition.scss
View File

@ -52,7 +52,7 @@ $admonitions: (
$name: nth($names, 1);
$icon: nth($props, 1);
// Inline icon through postcss in webpack
// Inline icon through PostCSS in Webpack
--md-admonition-icon--#{$name}: svg-load("@mdi/svg/svg/#{$icon}.svg");
}
}
@ -107,6 +107,11 @@ $admonitions: (
.md-typeset__table {
padding: 0 px2rem(12px);
}
// Tabbed block container is the only child
> .tabbed-set:only-child {
margin-top: 0;
}
}
// Admonition title
@ -144,7 +149,7 @@ $admonitions: (
}
}
// Reset code inside Admonition titles
// Reset code inside admonition titles
code {
margin: initial;
padding: initial;
@ -153,6 +158,11 @@ $admonitions: (
border-radius: initial;
box-shadow: none;
}
// Tabbed block container is the last child
+ .tabbed-set:last-child {
margin-top: 0;
}
}
}

2
src/assets/stylesheets/extensions/_codehilite.scss
View File

@ -242,7 +242,7 @@ $codehilite-whitespace: transparent;
// Add spacing to line number container
.linenodiv {
padding-right: px2em(8px, 13.6px);
box-shadow: inset px2rem(-1px) 0 var(--md-default-fg-color--lightest);
box-shadow: px2rem(-1px) 0 var(--md-default-fg-color--lightest) inset;
// Reset spacings
pre {

6
src/assets/stylesheets/extensions/_footnotes.scss
View File

@ -43,6 +43,7 @@
margin-top: -1 * px2rem(48px + 12px + 16px);
padding-top: px2rem(48px + 12px + 16px);
pointer-events: none;
scroll-margin-top: initial;
}
}
@ -56,6 +57,11 @@
content: "";
}
// Reset, as we use the anchor-correction hack here.
&:target {
scroll-margin-top: initial;
}
// Targeted anchor
&:target::before {
display: block;

2
src/assets/stylesheets/extensions/pymdown/_emoji.scss
View File

@ -32,6 +32,7 @@
img.twemoji,
img.gemoji {
width: px2em(18px);
max-height: 100%;
vertical-align: -15%;
}
@ -44,6 +45,7 @@
// Icon
svg {
width: px2em(18px);
max-height: 100%;
fill: currentColor;
}
}

2
src/assets/stylesheets/extensions/pymdown/_highlight.scss
View File

@ -40,7 +40,7 @@
padding-left: px2em(16px, 13.6px);
color: var(--md-default-fg-color--lighter);
background-color: var(--md-code-bg-color);
box-shadow: inset px2rem(-1px) 0 var(--md-default-fg-color--lightest);
box-shadow: px2rem(-1px) 0 var(--md-default-fg-color--lightest) inset;
content: attr(data-linenos);
user-select: none;
}

116
src/assets/stylesheets/extensions/pymdown/_keys.scss Normal file
View File

@ -0,0 +1,116 @@
////
/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
///
/// Permission is hereby granted, free of charge, to any person obtaining a
/// copy of this software and associated documentation files (the "Software"),
/// to deal in the Software without restriction, including without limitation
/// the rights to use, copy, modify, merge, publish, distribute, sublicense,
/// and/or sell copies of the Software, and to permit persons to whom the
/// Software is furnished to do so, subject to the following conditions:
///
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
/// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
/// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
/// DEALINGS
////
// ----------------------------------------------------------------------------
// Rules
// ----------------------------------------------------------------------------
// Scoped in typesetted content to match specificity of regular content
.md-typeset .keys {
// Keyboard key icon
kbd::before,
kbd::after {
position: relative;
margin: 0;
color: inherit;
-moz-osx-font-smoothing: initial;
-webkit-font-smoothing: initial;
}
// Surrounding text
span {
padding: 0 px2em(3.2px);
color: var(--md-default-fg-color--light);
}
// Build special keys with left icon
@each $name, $code in (
// Modifiers
"alt": "\2387",
"left-alt": "\2387",
"right-alt": "\2387",
"command": "\2318",
"left-command": "\2318",
"right-command": "\2318",
"control": "\2303",
"left-control": "\2303",
"right-control": "\2303",
"meta": "\25C6",
"left-meta": "\25C6",
"right-meta": "\25C6",
"option": "\2325",
"left-option": "\2325",
"right-option": "\2325",
"shift": "\21E7",
"left-shift": "\21E7",
"right-shift": "\21E7",
"super": "\2756",
"left-super": "\2756",
"right-super": "\2756",
"windows": "\229E",
"left-windows": "\229E",
"right-windows": "\229E",
// Other keys
"arrow-down": "\25bd",
"arrow-left": "\25c1",
"arrow-right": "\25b7",
"arrow-up": "\25b3",
"backspace": "\232B",
"backtab": "\21E4",
"caps-lock": "\21EA",
"clear": "\2327",
"context-menu": "\2630",
"delete": "\2326",
"eject": "\23CF",
"end": "\2913",
"escape": "\238b",
"home": "\2912",
"insert": "\2380",
"page-down": "\21df",
"page-up": "\21de",
"print-screen": "\2399"
) {
.key-#{$name} {
&::before {
padding-right: px2em(6.4px);
content: $code;
}
}
}
// Build special keys with right icon
@each $name, $code in (
"tab": "\21B9",
"num-enter": "\2324",
"enter": "\23CE"
) {
.key-#{$name} {
&::after {
padding-left: px2em(6.4px);
content: $code;
}
}
}
}

1
src/assets/stylesheets/extensions/pymdown/_tabbed.scss
View File

@ -35,6 +35,7 @@
box-shadow: 0 px2rem(-1px) var(--md-default-fg-color--lightest);
// Mirror old superfences behavior, if there's only a single code block.
> pre:only-child,
> .codehilite:only-child pre,
> .codehilitetable:only-child,
> .highlight:only-child pre,

8
src/assets/stylesheets/extensions/pymdown/_tasklist.scss
View File

@ -26,8 +26,12 @@
// Icon definitions
:root {
--md-tasklist-icon: svg-load("@mdi/svg/svg/checkbox-blank-circle.svg");
--md-tasklist-icon--checked: svg-load("@mdi/svg/svg/check-circle.svg");
--md-tasklist-icon: svg-load(
"@primer/octicons/build/svg/check-circle-fill-24.svg"
);
--md-tasklist-icon--checked: svg-load(
"@primer/octicons/build/svg/check-circle-fill-24.svg"
);
}
// ----------------------------------------------------------------------------

2
src/assets/stylesheets/layout/_nav.scss
View File

@ -208,7 +208,7 @@
overflow-y: auto;
background-color: var(--md-default-bg-color);
box-shadow:
inset 0 px2rem(1px) 0 var(--md-default-fg-color--lightest);
0 px2rem(1px) 0 var(--md-default-fg-color--lightest) inset;
scroll-snap-type: y mandatory;
touch-action: pan-y;

1
src/assets/stylesheets/main.scss
View File

@ -67,6 +67,7 @@
@import "extensions/pymdown/details";
@import "extensions/pymdown/emoji";
@import "extensions/pymdown/highlight";
@import "extensions/pymdown/keys";
@import "extensions/pymdown/tabbed";
@import "extensions/pymdown/tasklist";

42
src/assets/stylesheets/overrides.scss Normal file
View File

@ -0,0 +1,42 @@
////
/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
///
/// Permission is hereby granted, free of charge, to any person obtaining a
/// copy of this software and associated documentation files (the "Software"),
/// to deal in the Software without restriction, including without limitation
/// the rights to use, copy, modify, merge, publish, distribute, sublicense,
/// and/or sell copies of the Software, and to permit persons to whom the
/// Software is furnished to do so, subject to the following conditions:
///
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
/// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
/// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
/// DEALINGS
////
// ----------------------------------------------------------------------------
// Dependencies
// ----------------------------------------------------------------------------
@import "modularscale";
@import "material-color";
// ----------------------------------------------------------------------------
// Local imports
// ----------------------------------------------------------------------------
@import "utilities/break";
@import "utilities/convert";
@import "config";
@import "overrides/admonition";
@import "overrides/announce";
@import "overrides/sponsor";
@import "overrides/typeset";

83
src/assets/stylesheets/overrides/_admonition.scss Normal file
View File

@ -0,0 +1,83 @@
////
/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
///
/// Permission is hereby granted, free of charge, to any person obtaining a
/// copy of this software and associated documentation files (the "Software"),
/// to deal in the Software without restriction, including without limitation
/// the rights to use, copy, modify, merge, publish, distribute, sublicense,
/// and/or sell copies of the Software, and to permit persons to whom the
/// Software is furnished to do so, subject to the following conditions:
///
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
/// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
/// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
/// DEALINGS
////
// ----------------------------------------------------------------------------
// Variables
// ----------------------------------------------------------------------------
///
/// Admonition flavours
///
$admonitions: (
sponsor: heart-fill-24 #EA4AAA
) !default;
// ----------------------------------------------------------------------------
// Rules: layout
// ----------------------------------------------------------------------------
// Icon definitions
:root {
@each $names, $props in $admonitions {
$name: nth($names, 1);
$icon: nth($props, 1);
// Inline icon through PostCSS in Webpack
--md-admonition-icon--#{$name}: svg-load(
"@primer/octicons/build/svg/#{$icon}.svg"
);
}
}
// ----------------------------------------------------------------------------
// Rules: flavours
// ----------------------------------------------------------------------------
@each $names, $props in $admonitions {
$name: nth($names, 1);
$tint: nth($props, 2);
// Define base class
.md-typeset .admonition.#{$name} {
border-color: $tint;
}
// Define base class
.md-typeset .#{$name} > .admonition-title {
background-color: transparentize($tint, 0.9);
// Icon
&::before {
background-color: $tint;
mask-image: var(--md-admonition-icon--#{$name});
}
}
// Define synonyms for base class
@if length($names) > 1 {
@for $n from 2 through length($names) {
.#{nth($names, $n)} {
@extend .#{$name};
}
}
}
}

47
src/assets/stylesheets/overrides/_announce.scss Normal file
View File

@ -0,0 +1,47 @@
////
/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
///
/// Permission is hereby granted, free of charge, to any person obtaining a
/// copy of this software and associated documentation files (the "Software"),
/// to deal in the Software without restriction, including without limitation
/// the rights to use, copy, modify, merge, publish, distribute, sublicense,
/// and/or sell copies of the Software, and to permit persons to whom the
/// Software is furnished to do so, subject to the following conditions:
///
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
/// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
/// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
/// DEALINGS
////
// ----------------------------------------------------------------------------
// Rules
// ----------------------------------------------------------------------------
// Announcement bar
.md-announce {
// Preserve link colors
a,
a:focus,
a:hover {
color: currentColor;
}
// Don't wrap name of blog article
strong {
white-space: nowrap;
}
// Twitter icon
.twitter {
margin-left: .2em;
color: #00ACEE;
}
}

66
src/assets/stylesheets/overrides/_sponsor.scss Normal file
View File

@ -0,0 +1,66 @@
////
/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
///
/// Permission is hereby granted, free of charge, to any person obtaining a
/// copy of this software and associated documentation files (the "Software"),
/// to deal in the Software without restriction, including without limitation
/// the rights to use, copy, modify, merge, publish, distribute, sublicense,
/// and/or sell copies of the Software, and to permit persons to whom the
/// Software is furnished to do so, subject to the following conditions:
///
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
/// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
/// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
/// DEALINGS
////
// ----------------------------------------------------------------------------
// Keyframes
// ----------------------------------------------------------------------------
// Heart animation
@keyframes tx-sponsor {
0%, 40%, 80%, 100% {
transform: scale(1);
}
20%, 60% {
transform: scale(1.1);
}
}
// ----------------------------------------------------------------------------
// Rules
// ----------------------------------------------------------------------------
// Sponsor banner
.tx-sponsor {
margin-top: px2rem(20px);
text-align: center;
// Sponsor link
a {
color: $clr-pink-500;
font-variant: all-petite-caps;
}
// Horizontal separators
hr {
display: inline-block;
width: px2rem(40px);
margin: px2em(16px);
vertical-align: middle;
background-color: currentColor;
border: none;
}
// Pumping heart
&__heart {
animation: tx-sponsor 1000ms infinite;
}
}

57
src/assets/stylesheets/overrides/_typeset.scss Normal file
View File

@ -0,0 +1,57 @@
////
/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
///
/// Permission is hereby granted, free of charge, to any person obtaining a
/// copy of this software and associated documentation files (the "Software"),
/// to deal in the Software without restriction, including without limitation
/// the rights to use, copy, modify, merge, publish, distribute, sublicense,
/// and/or sell copies of the Software, and to permit persons to whom the
/// Software is furnished to do so, subject to the following conditions:
///
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
/// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
/// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
/// DEALINGS
////
// ----------------------------------------------------------------------------
// Rules
// ----------------------------------------------------------------------------
// Typesetted content
.md-typeset {
// Extension: switch buttons
.tx-switch button {
cursor: pointer;
transition: opacity 250ms;
// Hovered button
&:hover {
opacity: 0.75;
}
// Code block
> code {
display: block;
color: var(--md-primary-bg-color);
background-color: var(--md-primary-fg-color);
}
}
// Two-column layout
.tx-columns {
columns: 2;
// Column
> * {
break-inside: avoid;
}
}
}

7
src/assets/stylesheets/palette/_scheme.scss
View File

@ -39,7 +39,12 @@
// Code color shades
--md-code-bg-color: hsla(232, 15%, 18%, 1);
--md-code-fg-color: hsla(60, 30%, 96%, 1);
--md-code-fg-color: hsla(232, 18%, 86%, 1);
// Keyboard color shades
--md-kbd-color: hsla(232, 15%, 94%, 0.12);
--md-kbd-accent-color: hsla(232, 15%, 94%, 0.2);
--md-kbd-border-color: hsla(232, 15%, 14%, 1);
// Text color shades
--md-text-color: var(--md-default-fg-color--light);

57
src/overrides/main.html
View File

@ -51,30 +51,16 @@
<meta name="twitter:title" content="{{ title }}" />
<meta name="twitter:description" content="{{ config.site_description }}" />
<meta name="twitter:image" content="{{ image }}" />
<!-- Extra stylesheets -->
<link
rel="stylesheet"
href="{{ 'assets/stylesheets/overrides.css' | url }}"
/>
{% endblock %}
<!-- Announcement bar -->
{% block announce %}
<style>
/* Preserve link color */
.md-announce a,
.md-announce a:focus,
.md-announce a:hover {
color: currentColor;
}
/* Don't wrap name of blog article */
.md-announce strong {
white-space: nowrap;
}
/* Twitter icon */
.md-announce .twitter {
margin-left: .2em;
color: #00acee;
}
</style>
<a href="https://twitter.com/squidfunk">
For updates follow <strong>@squidfunk</strong> on
<span class="twemoji twitter">
@ -85,3 +71,34 @@
<strong>Twitter</strong>
</a>
{% endblock %}
<!-- Content -->
{% block content %}
{{ super() }}
<!-- Sponsor banner -->
<aside class="tx-sponsor md-typeset">
<a href="{{ 'sponsorship' | url }}" title="Becoming a sponsor">
<hr />
<span class="twemoji">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 89 89">
<path d="M3.136 17.387v42.932l42.932 21.467L3.136 17.387z"></path>
<path fill-opacity=".5" d="M21.91 8l42.933 64.398-18.775 9.388L3.136 17.387 21.91 8z"></path>
<path d="M67.535 17.387L40.273 35.543l21.878 32.818 5.384 2.691V17.387z"></path>
<path fill-opacity=".25" d="M67.535 17.387v53.666l18.774-9.388V8l-18.774 9.387z"></path>
</svg>
</span>
<span class="twemoji">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z"></path>
</svg>
</span>
<span class="twemoji tx-sponsor__heart">
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
<path d="M14 20.408c-.492.308-.903.546-1.192.709-.153.086-.308.17-.463.252h-.002a.75.75 0 01-.686 0 16.709 16.709 0 01-.465-.252 31.147 31.147 0 01-4.803-3.34C3.8 15.572 1 12.331 1 8.513 1 5.052 3.829 2.5 6.736 2.5 9.03 2.5 10.881 3.726 12 5.605 13.12 3.726 14.97 2.5 17.264 2.5 20.17 2.5 23 5.052 23 8.514c0 3.818-2.801 7.06-5.389 9.262A31.146 31.146 0 0114 20.408z"></path>
</svg>
</span>
<hr />
</a>
</aside>
{% endblock %}

39
src/partials/more.html
View File

@ -1,39 +0,0 @@
<!--
Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
-->
<!-- Options dialog -->
<div class="md-more">
<input
class="md-toggle"
data-md-toggle="more"
type="checkbox"
id="__more"
autocomplete="off"
/>
<!-- Options -->
<ul class="md-more__list">
<li class="md-more__item">Item 1</li>
<li class="md-more__item">Item 2</li>
<li class="md-more__item">Item 3</li>
</ul>
</div>

2
src/partials/source-link.html
View File

@ -27,7 +27,7 @@
{% if repo | last == "/" %}
{% set repo = repo[:-1] %}
{% endif %}
{% set path = page.meta.path | default([""]) %}
{% set path = page.meta.path | default("") %}
<a
href="{{ [repo, path, page.meta.source] | join('/') }}"
title="{{ page.meta.source }}"

12
webpack.config.ts
View File

@ -189,6 +189,7 @@ export default (_env: never, args: Configuration): Configuration[] => {
entry: {
"assets/javascripts/bundle": "src/assets/javascripts",
"assets/stylesheets/main": "src/assets/stylesheets/main.scss",
"assets/stylesheets/overrides": "src/assets/stylesheets/overrides.scss",
"assets/stylesheets/palette": "src/assets/stylesheets/palette.scss"
},
output: {
@ -312,16 +313,21 @@ export default (_env: never, args: Configuration): Configuration[] => {
new EventHooksPlugin({
afterEmit: () => {
/* Replace asset URLs in base template */
/* Replace asset URLs in templates */
if (args.mode === "production") {
const manifest = require("./material/assets/manifest.json")
for (const file of [
"material/base.html",
"material/overrides/main.html"
]) {
const template = toPairs<string>(manifest)
.reduce((content, [from, to]) => {
return content.replace(new RegExp(from, "g"), to)
}, fs.readFileSync("material/base.html", "utf8"))
}, fs.readFileSync(file, "utf8"))
/* Save template with replaced assets */
fs.writeFileSync("material/base.html", template, "utf8")
fs.writeFileSync(file, template, "utf8")
}
}
}
}),