OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Improved getting started guide and added further guides

Browse Source
This commit is contained in:
squidfunk 2020-07-16 22:31:39 +02:00
parent 7c5a59a5ef
commit 71e9b1d745
20 changed files with 916 additions and 193 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 319 KiB

73
docs/creating-your-site.md
View File

@ -1,73 +0,0 @@
---
template: overrides/main.html
---
# Creating your site
After you've installed Material for MkDocs, bootstrap your site using the
`mkdocs` executable. Change to the directory where you want your documentation
to be located and enter:
``` sh
mkdocs new .
```
This will create the following structure along your existing files:
```
├─ docs/
│ └─ index.md
└─ mkdocs.yml
```
## Configuration
Depending on your [installation method][1], you can now add the following lines
to `mkdocs.yml` in your project root. If you installed Material for MkDocs with
`pip` or pulled the Docker image, add:
``` yaml
theme:
name: material
```
If you cloned Material for MkDocs from GitHub, add:
``` yaml
theme:
name: null
custom_dir: mkdocs-material/material
```
!!! todo "Add note about many customization options with links to guides"
## Previewing
MkDocs includes a live preview server, so you can preview your changes as you
write your documentation. 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][2] and you should see:
[![Creating your site][3]][3]
[1]: getting-started.md#installation
[2]: http://localhost:8000
[3]: assets/screenshots/creating-your-site.png

71
docs/getting-started.md
View File

@ -5,13 +5,16 @@ template: overrides/main.html
# Getting started # Getting started
Material for MkDocs is a theme for [MkDocs][1], a static site generator geared Material for MkDocs is a theme for [MkDocs][1], a static site generator geared
towards technical documentation. If you're familar with Python, you can install towards (technical) project documentation. If you're familar with Python, you
Material for MkDocs with [`pip`][2], the Python package manager. If not, we can install Material for MkDocs with [`pip`][2], the Python package manager.
recommended using [`docker`][3]. If not, we recommended using [`docker`][3].
In case you're running into problems, consult the [troubleshooting][4] section.
[1]: https://www.mkdocs.org [1]: https://www.mkdocs.org
[2]: #with-pip [2]: #with-pip
[3]: #with-docker [3]: #with-docker
[4]: getting-started/troubleshooting.md
## Installation ## Installation
@ -24,16 +27,13 @@ pip install mkdocs-material
``` ```
This will automatically install compatible versions of all dependencies: This will automatically install compatible versions of all dependencies:
[MkDocs][1], [Markdown][4], [Pygments][5] and [PyMdown Extensions][6]. Material [MkDocs][1], [Markdown][5], [Pygments][6] and [PyMdown Extensions][7]. Material
for MkDocs always strives to support the latest versions, so there's no need to for MkDocs always strives to support the latest versions, so there's no need to
install those packages separately. install those packages separately.
If you're running into problems, read the section on [virtual environments][7]. [5]: https://python-markdown.github.io/
[6]: https://pygments.org/
[4]: https://python-markdown.github.io/ [7]: https://facelessuser.github.io/pymdown-extensions/
[5]: https://pygments.org/
[6]: https://facelessuser.github.io/pymdown-extensions/
[7]: #virtual-environments
### with docker ### with docker
@ -69,54 +69,3 @@ pip install -r mkdocs-material/requirements.txt
``` ```
[9]: https://github.com/squidfunk/mkdocs-material [9]: https://github.com/squidfunk/mkdocs-material
## 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:
``` sh
which python
```
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

137
docs/getting-started/creating-your-site.md Normal file
View File

@ -0,0 +1,137 @@
---
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 .
```
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 colors][3]
* [Changing the fonts][4]
* [Changing the language][5]
* [Navigation structure][6]
* [Syntax highlighting][7]
* [Adding a landing page][8]
* [Adding an announcement bar][9]
* [Adding icons and emojis][10]
* [Adding footer links][11]
* [Adding site analytics][12]
* [Adding a comment system][13]
[2]: ../getting-started.md#installation
[3]: ../guides/changing-colors.md
[4]: ../guides/changing-the-fonts.md
[5]: ../guides/changing-the-language.md
[6]: ../guides/navigation-structure.md
[7]: ../guides/syntax-highlighting.md
[8]: ../guides/adding-a-landing-page.md
[9]: ../guides/adding-an-announcement-bar.md
[10]: ../guides/adding-icons-and-emojis.md
[11]: ../guides/adding-footer-links.md
[12]: ../guides/adding-site-analytics.md
[13]: ../guides/adding-a-comment-system.md
## Previewing as you write
MkDocs includes a live preview server, so you can preview your changes as you
write your documentation. The server will automatically rebuild the site upon
saving. Start it with:
```
mkdocs serve
```
If you're running Material for MkDocs from within Docker, use:
=== "Unix"
```
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][14] and you should see:
[![Creating your site][15]][14]
[14]: http://localhost:8000
[15]: ../assets/guides/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][16], [GitLab Pages][17], a CDN of your
choice or your private web space.
[16]: publishing-your-site.md#github-pages
[17]: publishing-your-site.md#gitlab-pages

247
docs/getting-started/customization.md Normal file
View File

@ -0,0 +1,247 @@
---
template: overrides/main.html
---
# Customization
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 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 the `docs` directory:
``` sh
mkdir docs/stylesheets
touch docs/stylesheets/extra.css
```
Then, add the following line to `mkdocs.yml`:
``` yaml
extra_css:
- stylesheets/extra.css
```
Spin up the [live preview server][2] and start typing your changes in your
additional stylesheet file – you should see them almost instantly after saving.
[2]: creating-your-site.md#previewing-as-you-write
### Additional JavaScript
The same is true for additional JavaScript. If you want to integrate another
syntax highlighter or add some custom logic to your theme, create a new
JavaScript file in the `docs` directory:
``` sh
mkdir docs/javascripts
touch docs/javascripts/extra.js
```
Then, add the following line to `mkdocs.yml`:
``` yaml
extra_javascript:
- javascripts/extra.js
```
Further assistance can be found in the [MkDocs documentation][3].
[3]: https://www.mkdocs.org/user-guide/styling-your-docs/#customizing-a-theme
## Extending the theme
If you want to alter the HTML source (e.g. add or remove some part), you can
extend the theme. MkDocs supports [theme extension][4], an easy way to override
parts of a theme without forking and changing the main theme.
[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 `mkdocs.yml`, and create a new folder
for `overrides` which you reference using `custom_dir`:
``` yaml
theme:
name: material
custom_dir: overrides
```
!!! warning "Theme extension prerequisites"
As the `custom_dir` variable is used for the theme extension process,
Material for MkDocs needs to be installed via `pip` and referenced with the
`name` parameter in `mkdocs.yml`. It will not work when cloning from `git`.
The structure in the `overrides` directory must mirror the directory structure
of the original theme, as any file in the `overrides` directory will replace the
file with the same name which is part of the original theme. Besides, further
assets may also be put in the `overrides` directory.
The directory layout of the theme is as follows:
``` sh
.
├─ assets/
│ ├─ images/ # Images and icons
│ ├─ javascripts/ # JavaScript
│ └─ stylesheets/ # Stylesheets
├─ partials/
│ ├─ integrations/ # 3rd-party integrations
│ ├─ language/ # Localized languages
│ ├─ footer.html # Footer bar
│ ├─ header.html # Header bar
│ ├─ hero.html # Hero teaser
│ ├─ language.html # Localized labels
│ ├─ logo.html # Logo in header and sidebar
│ ├─ nav.html # Main navigation
│ ├─ nav-item.html # Main navigation item
│ ├─ palette.html # Color palette
│ ├─ search.html # Search box
│ ├─ social.html # Social links
│ ├─ source.html # Repository information
│ ├─ source-date.html # Last updated date
│ ├─ source-link.html # Link to source file
│ ├─ tabs.html # Tabs navigation
│ ├─ tabs-item.html # Tabs navigation item
│ ├─ toc.html # Table of contents
│ └─ toc-item.html # Table of contents item
├─ 404.html # 404 error page
├─ base.html # Base template
└─ main.html # Default page
```
### Overriding partials
In order to override the footer, we can replace the `footer.html` partial with
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 blocks
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" %}
{% block htmltitle %}
<title>Lorem ipsum dolor sit amet</title>
{% endblock %}
```
Material for MkDocs provides the following template blocks:
| Block name | Wrapped contents |
| ------------ | ----------------------------------------------- |
| `analytics` | Wraps the Google Analytics integration |
| `announce` | Wraps the Announcement bar |
| `config` | Wraps the JavaScript application config |
| `content` | Wraps the main content |
| `disqus` | Wraps the disqus integration |
| `extrahead` | Empty block to define additional meta tags |
| `fonts` | Wraps the webfont definitions |
| `footer` | Wraps the footer with navigation and copyright |
| `header` | Wraps the fixed header bar |
| `hero` | Wraps the hero teaser (if available) |
| `htmltitle` | Wraps the `<title>` tag |
| `libs` | Wraps the JavaScript libraries (header) |
| `scripts` | Wraps the JavaScript application (footer) |
| `source` | Wraps the linked source files |
| `site_meta` | Wraps the meta tags in the document head |
| `site_nav` | Wraps the site navigation and table of contents |
| `styles` | Wraps the stylesheets (also extra sources) |
| `tabs` | Wraps the tabs navigation (if available) |
For more on this topic refer to the [MkDocs documentation][5].
[5]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks
## Theme development
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.
[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][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
```
[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][10] and you should see this documentation
in front of you.
!!! warning "Automatically generated files"
Never make any changes in the `material` directory, as the contents of this
directory are automatically generated from the `src` directory and will be
overridden when the theme is built.
[10]: http://localhost:8000
### Build process
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 the original `mkdocs.yml`.
Now you can run `mkdocs build` and you should see your documentation with your
changes to the original theme.

94
docs/getting-started/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 automatically deploy it 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
- pull_request
jobs:
deploy:
if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master'
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/

102
docs/getting-started/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.
1. **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
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`.
### 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.

0
docs/publishing-your-site.md → docs/guides/adding-a-comment-system.md
View File

0
docs/guides/adding-site-analytics.md Normal file
View File

274
docs/guides/changing-colors.md
View File

@ -0,0 +1,274 @@
---
template: overrides/main.html
---
# Changing 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 adjusted with a few lines of CSS to
fit your brand identity by using [CSS variables][2].
[1]: http://www.materialui.co/colors
[2]: #customization
## Configuration
### 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: default
```
:material-cursor-default-click-outline: click on a tile to change the color
scheme:
<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() {
var name = document.querySelector("#__code_0 code span:nth-child(7)")
document.body.setAttribute(attr, this.getAttribute(attr))
name.textContent = 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
```
### Primary color
> 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:
<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() {
var name = document.querySelector("#__code_2 code span:nth-child(7)")
document.body.setAttribute(attr, this.getAttribute(attr))
name.textContent = this.getAttribute(attr)
})
})
</script>
### Accent color
> 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] {
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() {
var name = document.querySelector("#__code_3 code span:nth-child(7)")
document.body.setAttribute(attr, this.getAttribute(attr))
name.textContent = this.getAttribute(attr)
})
})
</script>
## Customization
Material for MkDocs implements colors using [CSS variables][3] (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][4] 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][5], [admonitions][6], 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);
}
```
[3]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[4]: ../getting-started/customization.md#additional-stylesheets
## Caveats
!!! 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.

38
docs/guides/changing-the-fonts.md
View File

@ -0,0 +1,38 @@
---
template: overrides/main.html
---
# Changing the fonts
## Configuration
> Default: `Roboto` and `Roboto Mono`
The [Roboto font family][1] 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][2] and can be changed to any
supported typeface, like for example the [Ubuntu font family][3]:
``` 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
```
[1]: https://fonts.google.com/specimen/Roboto
[2]: https://fonts.google.com
[3]: https://fonts.google.com/specimen/Ubuntu
## Customization
TBD

4
material/assets/manifest.json
View File

@ -5,8 +5,8 @@
"assets/javascripts/vendor.js.map": "assets/javascripts/vendor.568ba93b.min.js.map", "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.568ba93b.min.js.map",
"assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js", "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/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": "assets/stylesheets/main.ee9eac3c.min.css",
"assets/stylesheets/main.css.map": "assets/stylesheets/main.61729dd2.min.css.map", "assets/stylesheets/main.css.map": "assets/stylesheets/main.ee9eac3c.min.css.map",
"assets/stylesheets/palette.css": "assets/stylesheets/palette.e185632b.min.css", "assets/stylesheets/palette.css": "assets/stylesheets/palette.e185632b.min.css",
"assets/stylesheets/palette.css.map": "assets/stylesheets/palette.e185632b.min.css.map" "assets/stylesheets/palette.css.map": "assets/stylesheets/palette.e185632b.min.css.map"
} }

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

File diff suppressed because one or more lines are too long

4
material/assets/stylesheets/main.61729dd2.min.css → material/assets/stylesheets/main.ee9eac3c.min.css vendored
View File

File diff suppressed because one or more lines are too long

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

File diff suppressed because one or more lines are too long

2
material/base.html
View File

@ -41,7 +41,7 @@
{% endif %} {% endif %}
{% endblock %} {% endblock %}
{% block styles %} {% block styles %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.61729dd2.min.css' | url }}"> <link rel="stylesheet" href="{{ 'assets/stylesheets/main.ee9eac3c.min.css' | url }}">
{% if palette.scheme or palette.primary or palette.accent %} {% 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.e185632b.min.css' | url }}">
{% endif %} {% endif %}

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>

9
mkdocs.yml
View File

@ -129,19 +129,22 @@ nav:
- Home: index.md - Home: index.md
- Getting started: - Getting started:
- Installation: getting-started.md - Installation: getting-started.md
- Creating your site: creating-your-site.md - Creating your site: getting-started/creating-your-site.md
- Publishing your site: publishing-your-site.md - Publishing your site: getting-started/publishing-your-site.md
- Customization: getting-started/customization.md
- Troubleshooting: getting-started/troubleshooting.md
- Guides: - Guides:
- Changing colors: guides/changing-colors.md - Changing colors: guides/changing-colors.md
- Changing the fonts: guides/changing-the-fonts.md - Changing the fonts: guides/changing-the-fonts.md
- Changing the language: guides/changing-the-language.md - Changing the language: guides/changing-the-language.md
- Navigation structure: guides/navigation-structure.md - Navigation structure: guides/navigation-structure.md
- Syntax highlighting: guides/syntax-highlighting.md - Syntax highlighting: guides/syntax-highlighting.md
- Third-party integrations: guides/third-party-integrations.md
- Adding a landing page: guides/adding-a-landing-page.md - Adding a landing page: guides/adding-a-landing-page.md
- Adding an announcement bar: guides/adding-an-announcement-bar.md - Adding an announcement bar: guides/adding-an-announcement-bar.md
- Adding icons and emojis: guides/adding-icons-and-emojis.md - Adding icons and emojis: guides/adding-icons-and-emojis.md
- Adding footer links: guides/adding-footer-links.md - Adding footer links: guides/adding-footer-links.md
- Adding site analytics: guides/adding-site-analytics.md
- Adding a comment systems: guides/adding-a-comment-system.md
- Extensions: - Extensions:
- Admonition: extensions/admonition.md - Admonition: extensions/admonition.md
- CodeHilite: extensions/codehilite.md - CodeHilite: extensions/codehilite.md

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

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

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>