140 docs/creating-your-site.md
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:

```
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 _setup_
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
122 docs/customization.md
View file
@@ -4,77 +4,76 @@ 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
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

### Additional stylesheets

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,14 +135,14 @@ 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
``` html
{% extends "base.html" %}

{% block htmltitle %}
@@ -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,76 +173,78 @@ 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
```
git clone https://github.com/squidfunk/mkdocs-material
```

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

Start the Webpack watchdog with:

``` sh
```
npm start
```

Then, in a second session, start the MkDocs server with:

```sh
```
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"

Never make any changes in the `material` directory, as the contents of this
directory are automatically generated from the `src` directory and will be
overridden when the theme is built.

[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
```

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.
34 docs/data-privacy.md
View file
@@ -14,30 +14,18 @@ some third-party services that may not.

### Google Fonts

Material for MkDocs makes fonts [easily configurable][2] by relying on Google
Fonts CDN. Embedding fonts from Google is currently within a gray area as there's
no official statement or ruling regarding GDPR compliance and the topic is still
[actively discussed][3]. If you need to ensure GDPR compliance, you may disable
the usage of the Google Font CDN with:

``` yaml
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
fonts. You can easily include your own, self-hosted webfont by [overriding][4]
the `fonts` block.

[2]: getting-started.md#fonts
[3]: https://github.com/google/fonts/issues/1495
[4]: customization.md#overriding-template-blocks
Material for MkDocs makes fonts [configurable][2] by relying on Google Fonts
CDN, which may be in breach with GDPR. The usage of Google's CDN can be [easily
disabled][3] via `mkdocs.yml`.

[2]: setup/changing-the-fonts.md
[3]: setup/changing-the-fonts.md#disabling-font-loading

### Google Analytics and Disqus

Material for MkDocs comes with optional [Google Analytics][5] and [Disqus][6]
integrations, both of which must be enabled explicitly.
Material for MkDocs comes with optional [Google Analytics][4] and [Disqus][5]
integrations, both of which must be enabled explicitly, so there's no immediate
action if you don't use those.

[5]: getting-started.md#google-analytics
[6]: getting-started.md#disqus
[4]: setup/setting-up-site-analytics.md#google-analytics
[5]: setup/adding-a-comment-system.md#disqus
114 docs/deprecations.md
View file
@@ -0,0 +1,114 @@
---
template: overrides/main.html
---

# Deprecations

This page includes a list of deprecations, indicating which features of Material
for MkDocs were replaced with newer, more flexible alternatives, and thus should
not be used anymore.

## Front matter

### Redirect

:octicons-archive-24: Deprecated: 5.5.0 ·
:octicons-trash-24: Removal: 6.x

The `redirect` key, which could be added via [Metadata][1], allowed to
specify a redirect from within a document to a new address, which is a good
idea when moving content around:

``` markdown
---
redirect: /path/to/new/file
---
```

The [redirects][2] plugin provides the ability to define redirect mappings via
`mkdocs.yml`, which is considered to be a much better solution to achieve the
same result. It can be installed with `pip`:

```
pip install mkdocs-redirects
```

Redirect mappings can then be added to `mkdocs.yml`:

``` yaml
plugins:
- redirects:
redirect_maps:
path/to/old/file.md: path/to/new/file.md
```

[1]: reference/meta-tags.md#metadata
[2]: https://github.com/datarobot/mkdocs-redirects

### Source link

:octicons-archive-24: Deprecated: 5.5.0 ·
:octicons-trash-24: Removal: 6.x

The `source` and `path` keys, which could be added via [Metadata][1], showed
a source icon at the top right corner of a document, linking a document to a
single source file:

``` markdown
---
path: tree/master/docs
source: deprecations.md
---
```

Only a single source file could be linked, which is useless if a document refers
to multiple files (or multiple sections within a single file). A more flexible
approach is to use the new [icon integration][3]:

``` markdown
[:octicons-file-code-24: Source](https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md)
```

This will render as [:octicons-file-code-24: Source][4], which can be included
at arbitrary positions in any document.

[3]: setup/changing-the-logo-and-icons.md#icons
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md

### Hero

:octicons-archive-24: Deprecated: 5.5.0 ·
:octicons-trash-24: Removal: 6.x

The `hero` key, which could be added via [Metadata][1], allowed to render a
simple, text-only and page-local teaser text as part of a document. It could
be set from front matter with:

``` markdown
---
hero: Lorem ipsum dolor sit amet
---
```

The recommended way is to [override the `hero` block][5] via [theme
extension][6] for a specific page, which has the nice side effect that hero
templates can be shared among multiple pages:

=== "Markdown"

``` markdown
---
template: overrides/hero.html
---
```

=== "Template"

``` html
{% block hero %}
<!-- Add custom hero here -->
{% endblock %}
```

[5]: customization.md#overriding-blocks
[6]: customization.md#extending-the-theme
459 docs/extensions/admonition.md
View file

This file was deleted.

966 docs/extensions/codehilite.md
View file

This file was deleted.

89 docs/extensions/footnotes.md
View file

This file was deleted.

135 docs/extensions/metadata.md
View file

This file was deleted.

37 docs/extensions/permalinks.md
View file

This file was deleted.

375 docs/extensions/pymdown.md
View file

This file was deleted.

806 docs/getting-started.md
View file

Large diffs are not rendered by default.

154 docs/insiders.md
View file
@@ -0,0 +1,154 @@
---
template: overrides/main.html
---

# <span hidden>Insiders</span> :logo: :material-plus: :octicons-heart-fill-24:{: .tx-heart }

Material for MkDocs uses the [sponsorware][1] release strategy, which means
that _new features are first exclusively released to sponsors_ as part of
__Material for MkDocs Insiders__. Read on to learn [how sponsorship works][2],
and how you can [become a sponsor][3].

[1]: https://github.com/sponsorware/docs
[2]: #how-sponsorship-works
[3]: #how-to-become-a-sponsor

<div style="width:100%;height:0px;position:relative;padding-bottom:56.138%;">
<iframe src="https://streamable.com/e/h9pyjk" frameborder="0" width="100%" height="100%" allowfullscreen style="width:100%;height:100%;position:absolute;left:0px;top:0px;overflow:hidden;"></iframe>
</div>
<p style="text-align: center; font-style: oblique">
A demo is worth a thousand words — check it out at <br />
<a href="https://squidfunk.github.io/mkdocs-material-insiders/">
squidfunk.github.io/mkdocs-material-insiders
</a>
</p>

## How sponsorship works

New features will first land in Material for MkDocs Insiders, which means that
_sponsors will have access immediately_. Every feature is tied to a funding
goal in monthly subscriptions. If a funding goal is hit, the features that are
tied to it are merged back into Material for MkDocs and released for general
availability. Bugfixes will always be released simultaneously in both editions.

See the [roadmap][4] for a list of already available and upcoming features, and
for demonstration purposes, [the official documentation][5] built with Material
for MkDocs Insiders.

[4]: #roadmap
[5]: https://squidfunk.github.io/mkdocs-material-insiders/

## How to become a sponsor

So you've decided to become a sponsor? Great! You're just __three easy steps__
away from enjoying the latest features of Material for MkDocs Insiders.
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 from $10/month_. Select
the tier and complete the checkout.
- Within 24 hours, you will become a collaborator of the private Material for
MkDocs Insiders GitHub repository, a fork of Material for MkDocs with
[brand new and exclusive features][7].
- Create a [personal access token][8], which allows installing Material for
MkDocs Insiders from any destination, including other CI providers like
[GitLab][9] or [Bitbucket][10].

__Congratulations! :partying_face: You're now officially a sponsor and will
get updates for Material for MkDocs Insiders, until you decide to cancel your
monthly subscription, which you can 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 available
in Material for MkDocs Insiders.

[11]: https://www.instagram.com/squidfunk/

### Madame Jeanette

[:octicons-fire-24: Funding goal: __$500__][6] ·
:octicons-lock-24: Status: _exclusive_

New features and improvements for _search_, including:

- [x] Improved search result grouping (pages + headings)
- [x] Improved search result relevance and scoring
- [x] Display of missing query terms in search results
- [ ] Improved search result summaries
- [ ] ... more to come

### Prairie Fire

[:octicons-fire-24: Funding goal: __$1,000__][6] ·
:octicons-lock-24: Status: _exclusive_

New features and improvements for _content and toc_, including:

- [x] Highlighting of matched search terms in content area
- [x] Navigation can always be expanded via configuration
- [ ] Better support for wide screens, i.e. more horizontal space
- [ ] Table of contents can be moved into navigation for more space
- [ ] Table of contents shows which sections have search results
- [ ] Table of contents auto-collapses and expands only the active section
- [ ] ... more to come

### Bhut Jolokia

[:octicons-fire-24: Funding goal: __$1,500__][6] ·
:octicons-lock-24: Status: _pending_

New features and improvements for _hosting multiple versions_, including:

- [ ] Support for multiple languages of documents
- [ ] Support for multiple versions of documents
- [ ] Support for one or more management plugins
- [ ] ... more to come

### Black Pearl

[:octicons-fire-24: Funding goal: __$2,000__][6] ·
:octicons-lock-24: Status: _pending_

New features and improvements for _user preferences_, including:

- [ ] Support for user-toggleable themes
- [ ] Support for user-toggleable code-block styles (light/dark)
- [ ] Display last searches when search is empty
- [ ] ... more to come

### Caribbean Red

[:octicons-fire-24: Funding goal: __$3,000__][6] ·
:octicons-lock-24: Status: _pending_

Alternative, completely different _vertical layout_, optimized to read
documentation and code side-by-side, e.g. for the documentation of APIs with
the same functionality as Material for MkDocs.

## Terms

Whether you're an individual or a company, you may use _Material for MkDocs
Insiders_ precisely under the same terms as _Material for MkDocs_, 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 Material for MkDocs Insiders.
You may freely use it for public, private or commercial projects, fork it,
mirror it, do whatever you want with it, but please don't release the source
code, as it would cannibalize the sponsorware strategy.

- If you cancel your subscription, you're removed as a collaborator and will
miss out on future updates of Material for MkDocs Insiders. However, you may
__use the latest version__ that's available to you __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
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

This file was deleted.

42 docs/plugins/minification.md
View file

This file was deleted.

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

This file was deleted.

133 docs/plugins/search.md
View file

This file was deleted.

94 docs/publishing-your-site.md
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/

400 docs/reference/admonitions.md
View file

Large diffs are not rendered by default.

83 docs/reference/buttons.md
View file
@@ -0,0 +1,83 @@
---
template: overrides/main.html
---

# Buttons

Material for MkDocs provides dedicated styles for primary and secondary buttons
that can be added to any link, `label` or `button` element. This is especially
useful for documents or landing pages with dedicated _call-to-actions_.

## Configuration

### Attribute List

The [Attribute List][1] extension, which is part of the standard Markdown
library, allows to __add HTML attributes and CSS classes to Markdown elements__,
and can be enabled via `mkdocs.yml`

``` yaml
markdown_extensions:
- attr_list
```

[1]: https://python-markdown.github.io/extensions/attr_list/

## Usage

### Adding buttons

When the [Attribute List][2] extension is enabled, any clickable element can be
converted into a button by adding the `.md-button` CSS class, which will receive
the selected [primary color][3].

_Example_:

``` markdown
[Subscribe to our mailing list](#){: .md-button }
```

_Result_:

[Subscribe to our mailing list][4]{: .md-button }

[2]: #attribute-list
[3]: ../setup/changing-the-colors.md#primary-color
[4]: javascript:app.dialog$.next("Done!")

### Adding primary buttons

If you want to display a filled, primary button (like on the [landing page][5]
of Material for MkDocs), add both the `.md-button` and `.md-button--primary`
CSS classes.

_Example_:

``` markdown
[Subscribe to our mailing list](#){: .md-button .md-button--primary }
```

_Result_:

[Subscribe to our mailing list][4]{: .md-button .md-button--primary }

[5]: ../index.md

### Adding icon buttons

Of course, icons can be added to both types of buttons by using the [regular
icon syntax][6] and referencing a valid path to [any icon bundled with the
theme][7].

_Example_:

``` markdown
[Submit :fontawesome-solid-paper-plane:](#){: .md-button .md-button--primary }
```

_Result_:

[Submit :fontawesome-solid-paper-plane:][4]{: .md-button .md-button--primary }

[6]: icons-emojis.md#using-icons
[7]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
387 docs/reference/code-blocks.md
View file
@@ -0,0 +1,387 @@
---
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/config.js"

``` js
hljs.initHighlighting()
```

=== "mkdocs.yml"

``` yaml
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js
- javascripts/config.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/main/extensions/pymdownx/_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 via `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

### Keys

[:octicons-file-code-24: Source][13] · [:octicons-workflow-24: Extension][14]

The [Keys][14] extension, which is part of [Python Markdown Extensions][5],
allows for inserting __keyboard keys__, e.g. ++ctrl+alt+delete++ , and
can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.keys
```

[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_keys.scss
[14]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/

### SuperFences

The [SuperFences][15] 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
```

[15]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/

### Snippets

The [Snippets][16] extension, which is also part of [Python Markdown
Extensions][5], allows to __insert content from other files__ or other, regular
content, and can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.snippets
```

[16]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/

## 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_:

``` markdown
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

### Adding keyboard keys

When [Keys][19] is enabled, keyboard keys can be rendered with a simple syntax.
Consult the [Python Markdown Extensions][16] documentation to learn about all
available key codes.

_Example_:

``` markdown
++ctrl+alt+del++
```

_Result_:

++ctrl+alt+del++

[19]: #keys

### Embedding external files

_Also known as transcludes or file transclusion in [MultiMarkdown][20]_.

When [Snippets][21] is enabled, content from other files can be embedded, which
is especially useful to reference and embed the contents of source files
directly into your project documentation.

_Example_:

```` markdown
```
--8<--​ ".browserslistrc"
```
````

_Result_:

```
--8<-- ".browserslistrc"
```

Note that [Snippets][21] is not limited to code blocks, but can be used anywhere
from a document to move repeating content to separate files, which is also
explained in the [official documentation][16].

[20]: https://fletcher.github.io/MultiMarkdown-5/transclusion.html
[21]: #snippets

## Customization

### Custom syntax theme

[:octicons-file-code-24: Source][22] ·
:octicons-mortar-board-24: Difficulty: _easy_

If [Pygments][23] is used, Material for MkDocs provides the [styles for code
blocks][22], which are built with a custom and well-balanced palette that works
equally well for both [color schemes][24]:

* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-function-color) " } `--md-code-hl-function-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-constant-color) " } `--md-code-hl-constant-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-keyword-color) " } `--md-code-hl-keyword-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-string-color) " } `--md-code-hl-string-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-name-color) " } `--md-code-hl-name-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-operator-color) " } `--md-code-hl-operator-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-punctuation-color) " } `--md-code-hl-punctuation-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-comment-color) " } `--md-code-hl-comment-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-generic-color) " } `--md-code-hl-generic-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-variable-color) " } `--md-code-hl-variable-color`

Code block foreground, background and line highlight colors are defined via:

* :material-checkbox-blank-circle:{: style="color: var(--md-code-fg-color) " } `--md-code-fg-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-bg-color) " } `--md-code-bg-color`
* :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-color) " } `--md-code-hl-color`

Let's say you want to change the color of `#!js "strings"`. While there are
several [types of string tokens][25], Material for MkDocs assigns a single color
to most of them.

Create an [additional stylesheet][6], and add:

``` css
:root > * {
--md-code-hl-string-color: #0FF1CE;
}
```

If you want to tweak a specific type of string, i.e. ``#!js `backticks` ``, you
can lookup the specific class name in the [syntax theme definition][26], and
override it as part of your additional stylesheet:

``` css
.highlight .sb {
color: #0FF1CE;
}
```

[22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#L60-L73
[23]: #use-pygments
[24]: ../setup/changing-the-colors.md#color-scheme
[25]: https://pygments.org/docs/tokens/#literals
[26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss#L42
218 docs/reference/content-tabs.md
View file
@@ -0,0 +1,218 @@
---
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 via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.tabbed
```

[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_tabbed.scss
[2]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
[3]: https://facelessuser.github.io/pymdown-extensions/

### SuperFences

The [SuperFences][4] extension, which is also part of [Python Markdown
Extensions][3], allows for the __nesting of code and content blocks inside
tabs__, and is therefore strongly recommended:

``` yaml
markdown_extensions:
- pymdownx.superfences
```

[4]: 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

When [SuperFences][5] is enabled, 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

[5]: #superfences
[6]: admonitions.md
[7]: admonitions.md#details
171 docs/reference/data-tables.md
View file
@@ -0,0 +1,171 @@
---
template: overrides/main.html
---

# Data tables

Material for MkDocs defines default styles for data tables – an excellent way
of rendering tabular data in project documentation. Furthermore, customizations
like [sortable tables][1] can be achieved with a third-party library and some
[additional JavaScript][2].

[1]: #sortable-tables
[2]: ../customization.md#additional-javascript

## Configuration

None.

## Usage

### Using data tables

Data tables can be used at any position in your project documentation and can
contain arbitrary Markdown, including inline code blocks, as well as [icons and
emojis][3].

_Example_:

``` markdown
| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
```

_Result_:

| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |

[3]: icons-emojis.md

### Column alignment

If you want to align a specific column to the `left`, `center` or `right`, you
can use the [regular Markdown syntax][4] placing `:` characters at the beginning
and/or end of the divider.

=== "Left"

_Example_:

``` markdown hl_lines="2"
| Method | Description |
| :---------- | :----------------------------------- |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
```

_Result_:

| Method | Description |
| :---------- | :----------------------------------- |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |

=== "Center"

_Example_:

``` markdown hl_lines="2"
| Method | Description |
| :---------: | :----------------------------------: |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
```

_Result_:

| Method | Description |
| :---------: | :----------------------------------: |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |

=== "Right"

_Example_:

``` markdown hl_lines="2"
| Method | Description |
| ----------: | -----------------------------------: |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
```

_Result_:

| Method | Description |
| ----------: | -----------------------------------: |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |

[4]: https://www.markdownguide.org/extended-syntax/#tables

## Customization

### Sortable tables

If you want to make data tables sortable, you can add [tablesort][5], which is
natively integrated with Material for MkDocs and will also work with [instant
loading][6] via [additional JavaScript][2]:

=== "docs/javascripts/tables.js"

``` js
app.document$.subscribe(function() {
var tables = document.querySelectorAll("article table")
tables.forEach(function(table) {
new Tablesort(table)
})
})
```

=== "mkdocs.yml"

``` yaml
extra_javascript:
- https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
- javascripts/tables.js
```

_Note that [tablesort][5] provides alternative comparison implementations like
numbers, dates, filesizes and month names. See the official documentation for
more information._

_Example_:

``` markdown
| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |
```

_Result_:

| Method | Description |
| ----------- | ------------------------------------ |
| `GET` | :material-check: Fetch resource |
| `PUT` | :material-check-all: Update resource |
| `DELETE` | :material-close: Delete resource |

<script src="https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js"></script>
<script>
var tables = document.querySelectorAll("article table")
new Tablesort(tables.item(tables.length - 1));
</script>

[5]: http://tristen.ca/tablesort/demo/
[6]: ../setup/setting-up-navigation.md#instant-loading
91 docs/reference/footnotes.md
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 via
`mkdocs.yml`:

``` yaml
markdown_extensions:
- footnotes
```

[1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_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)
189 docs/reference/formatting.md
View file
@@ -0,0 +1,189 @@
---
template: overrides/main.html
---

# Formatting

Material for MkDocs provides support for several HTML elements that can be used
to highlight sections of a document or apply specific formatting. Additionally,
[Critic Markup][1] is supported, adding the ability to display suggested changes
for a document.

[1]: http://criticmarkup.com/

## Configuration

### Critic

[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]

The [Critic][3] extension, which is part of [Python Markdown Extensions][4],
allows for the __usage of [Critic Markup][1] to highlight changes__ in a
document, and can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.critic
```

The following options are supported:

`mode`{: #mode }

: :octicons-milestone-24: Default: `view` – This option defines how the markup
should be parsed, i.e. whether to just `view` all suggest changes, or
alternatively `accept` or `reject` them:

=== "View changes"

``` yaml
markdown_extensions:
- pymdownx.critic:
mode: view
```

=== "Accept changes"

``` yaml
markdown_extensions:
- pymdownx.critic:
mode: accept
```

=== "Reject changes"

``` yaml
markdown_extensions:
- pymdownx.critic:
mode: reject
```

[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_critic.scss
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
[4]: https://facelessuser.github.io/pymdown-extensions/

### BetterEm

The [BetterEm][5] extension, which is part of [Python Markdown Extensions][4],
improves the handling of Markup to emphasize text (e.g. __bold__ and _italic_),
and can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.betterem:
smart_enable: all
```

[5]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/

### Caret, Mark & Tilde

The [Caret][6], [Mark][7] and [Tilde][8] extensions, which are part of [Python
Markdown Extensions][4], allow for the __highlighting of text__, as well as
__handling sub- and superscripts__:

``` yaml
markdown_extensions:
- pymdownx.caret
- pymdownx.mark
- pymdownx.tilde
```

[6]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
[7]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
[8]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/

### SmartSymbols

The [SmartSymbols][9] extension, which is also part of [Python Markdown
Extensions][4], __converts special characters into their corresponding
symbols__, and can be enabled via `mkdocs.yml`:

``` yaml
markdown_extensions:
- pymdownx.smartsymbols
```

See the [official documentation][9] for a list of supported symbols.

[9]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/

## Usage

### Highlighting changes

When [Critic][10] is enabled, [Critic Markup][1] can be used, which adds the
ability to _highlight suggested changes_, as well as add _inline comments_ to a
document:

[10]: #critic

_Example_:

``` markdown
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.

==}
```

_Result_:

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.

==}

### Highlighting text

When the [Caret, Mark & Tilde][11] extensions are enabled, text can be
highlighted with a nicer syntax than using the corresponding `mark`, `ins` and
`del` HTML tags:

_Example_:

``` markdown
* ==This was marked==
* ^^This was inserted^^
* ~~This was deleted~~
```

_Result_:

* ==This was marked==
* ^^This was inserted^^
* ~~This was deleted~~

[11]: #caret-mark-tilde

### Sub- and superscripts

When the [Caret & Tilde][11] extensions are enabled, text can be sub- and
superscripted with a nicer syntax than using the corresponding `sub` and `sup`
HTML tags:

_Example_:

``` markdown
* H~2~0
* A^T^A
```

_Result_:

* H~2~0
* A^T^A

[11]: #caret-mark-tilde