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

Reworked customization documentation

Browse Source
This commit is contained in:
squidfunk 2020-03-10 14:07:03 +01:00
parent c044208dc4
commit 12d1ad61c4
5 changed files with 84 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
docs/customization.md
View File

@ -2,10 +2,10 @@
## A great starting point
Project documentation is as diverse as the projects themselves and the Material
theme is a good starting point for making it look great. However, as you write
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 the desired style.
necessary to preserve your brand's style.
## Adding assets
@ -35,7 +35,7 @@ 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 implements live reloading.
saving, as the MkDocs development server supports live reloading.
### Additional JavaScript
@ -62,35 +62,34 @@ Further assistance can be found in the [MkDocs documentation][2].
## Extending the theme
If you want to alter the HTML source (e.g. add or remove some part), you can
extend the theme. From version 0.16 on MkDocs implements [theme extension][3],
an easy way to override parts of a theme without forking and changing the
main theme.
extend the theme. MkDocs supports [theme extension][3], 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
### Setup and theme structure
Reference the Material theme as usual in your `mkdocs.yml`, and create a
new folder for overrides, e.g. `theme`, which you reference using `custom_dir`:
new folder for `overrides` which you reference using `custom_dir`:
``` yaml
theme:
name: material
custom_dir: theme
custom_dir: overrides
```
!!! warning "Theme extension prerequisites"
As the `custom_dir` variable is used for the theme extension process, the
Material theme needs to be installed via `pip` and referenced with the
Material for MkDocs needs to be installed via `pip` and referenced with the
`name` parameter in your `mkdocs.yml`.
The structure in the theme directory must mirror the directory structure of the
original theme, as any file in the theme 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 theme directory.
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 Material theme is as follows:
The directory layout of the theme is as follows:
``` sh
.
@ -109,6 +108,8 @@ The directory layout of the Material theme is as follows:
│ ├─ nav.html # Main navigation
│ ├─ search.html # Search box
│ ├─ social.html # Social links
│ ├─ 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
@ -123,15 +124,15 @@ The directory layout of the Material theme is as follows:
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
theme directory. MkDocs will now use the new partial when rendering the theme.
This can be done with any file.
`overrides` directory. MkDocs will now use the new partial when rendering the
theme. This can be done with any file.
### Overriding template blocks
Besides overriding partials, one can also override so called template blocks,
which are defined inside the Material theme and wrap specific features. To
override a template block, create a `main.html` inside the theme directory and
define the block, e.g.:
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.:
``` jinja
{% extends "base.html" %}
@ -141,11 +142,13 @@ define the block, e.g.:
{% endblock %}
```
The Material theme provides the following template blocks:
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 |
@ -168,19 +171,19 @@ For more on this topic refer to the [MkDocs documentation][4]
## Theme development
The Material theme uses [Webpack][5] as a build tool to leverage modern web
technologies like [Babel][6] and [SASS][7]. If you want to make more fundamental
changes, it may be necessary to make the adjustments directly in the source of
the Material theme and recompile it. This is fairly easy.
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
fundamental changes, it may be necessary to make the adjustments directly in
the source of the theme and recompile it. This is fairly easy.
[5]: https://webpack.js.org/
[6]: https://babeljs.io
[6]: https://www.typescriptlang.org/
[7]: https://sass-lang.com
### Environment setup
In order to start development on the Material theme, a [Node.js][8] version of
at least 8 is required. First, clone the repository:
In order to start development on Material for MkDocs, a [Node.js][8] version of
at least 12 is required. First, clone the repository:
``` sh
git clone https://github.com/squidfunk/mkdocs-material
@ -193,31 +196,20 @@ cd mkdocs-material
pip install -r requirements.txt
npm install
```
If you're on Windows, you may also need to install [GNU Make][9]
[8]: https://nodejs.org
[9]: http://gnuwin32.sourceforge.net/packages/make.htm
### Development mode
The development server can be started with:
``` sh
npm run watch
npm start
```
This will also start the MkDocs development server which will monitor changes
on assets, templates and documentation. Point your browser to
[localhost:8000][10] and you should see this documentation in front of you.
For example, changing the color palette is as simple as changing the
`$md-color-primary` and `$md-color-accent` variables in
`src/assets/stylesheets/_config.scss`:
``` css
$md-color-primary: $clr-red-400;
$md-color-accent: $clr-teal-a700;
```
[localhost:8000][190] and you should see this documentation in front of you.
!!! warning "Automatically generated files"
@ -225,7 +217,7 @@ $md-color-accent: $clr-teal-a700;
directory are automatically generated from the `src` directory and will be
overridden when the theme is built.
[10]: http://localhost:8000
[9]: http://localhost:8000
### Build process
@ -236,9 +228,9 @@ npm run build
```
This triggers the production-level compilation and minification of all
stylesheets and JavaScript sources. When the command exits, the final theme is
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`.
Now you can run `mkdocs build` and you should see your documentation with your
changes to the original Material theme.
changes to the original theme.

43
docs/getting-started.md
View File

@ -331,11 +331,48 @@ theme:
If the colors are set with these configuration options, an additional CSS file
that includes the hues of the color palette is automatically included and linked
from the template. If you want to define a custom color (e.g. your brand color),
see the [customization guide][13].
from the template.
??? tip "Custom colors with CSS variables"
Material for MkDocs defines all colors as CSS variables. If you want to
customize the colors beyond the palette (e.g. to use your brand's colors),
you can add an [additional stylesheet][13] and override the defaults:
``` css
:root {
/* Default color shades */
--md-default-fg-color: ...;
--md-default-fg-color--light: ...;
--md-default-fg-color--lighter: ...;
--md-default-fg-color--lightest: ...;
--md-default-bg-color: ...;
--md-default-bg-color--light: ...;
--md-default-bg-color--lighter: ...;
--md-default-bg-color--lightest: ...;
/* Primary color shades */
--md-primary-fg-color: ...;
--md-primary-fg-color--light: ...;
--md-primary-fg-color--dark: ...;
--md-primary-bg-color: ...;
--md-primary-bg-color--light: ...;
/* Accent color shades */
--md-accent-fg-color: ...;
--md-accent-fg-color--transparent: ...;
--md-accent-bg-color: ...;
--md-accent-bg-color--light: ...;
/* Code block color shades */
--md-code-bg-color: ...;
--md-code-fg-color: ...;
}
```
[12]: http://www.materialui.co/colors
[13]: customization.md
[13]: customization.md/#additional-stylesheets
#### Primary color

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

@ -1,9 +1,9 @@
# Revision date
The [mkdocs-git-revision-date-localized-plugin][1] is an extension that shows
the date on which a Markdown file was last updated in at the bottom of each
page. The date is extracted at the time of the build, so `mkdocs build` must be
triggered from within a git repository.
The [mkdocs-git-revision-date-localized-plugin][1] will add the date on which a
Markdown file was last updated at the bottom of each page. The date is extracted
at the time of the build, so `mkdocs build` must be triggered from within a git
repository.
!!! success "Bundled with the official Docker image"
@ -74,5 +74,5 @@ page, e.g.:
---
<small>
Last updated: 9 December, 2019
Last updated: 28 November, 2019
</small>