mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Added documentation on contribution + some formatting
This commit is contained in:
squidfunk
parent
aca699f2cb
commit
efff866b62
@ -1,7 +1,7 @@
|
||||
# Contributing
|
||||
|
||||
Interested in contributing to the Material theme? Before you do, please read
|
||||
the following guidelines.
|
||||
Interested in contributing to the Material theme? Want to report a bug? Before
|
||||
you do, please read the following guidelines.
|
||||
|
||||
## Submission context
|
||||
|
||||
@ -15,8 +15,12 @@ For quick questions there's no need to open an issue as you can reach us on
|
||||
### Found a bug?
|
||||
|
||||
If you found a bug in the source code, you can help us by submitting an issue
|
||||
to our GitHub Repository. Even better, you can submit a Pull Request with a
|
||||
fix. However, before doing so, read the submission guidelines.
|
||||
to the [issue tracker][2] in our GitHub repository. Even better, you can submit
|
||||
a Pull Request with a fix. However, before doing so, please read the
|
||||
[submission guidelines][3].
|
||||
|
||||
[2]: https://github.com/squidfunk/mkdocs-material/issues
|
||||
[3]: #submission-guidelines
|
||||
|
||||
### Missing a feature?
|
||||
|
||||
@ -47,20 +51,31 @@ readily available.
|
||||
We want to fix all the issues as soon as possible, but before fixing a bug we
|
||||
need to reproduce and confirm it. In order to reproduce bugs we will
|
||||
systematically ask you to provide a minimal reproduction scenario using the
|
||||
custom issue template.
|
||||
custom issue template. Please stick to the issue template.
|
||||
|
||||
Unfortunately we are not able to investigate / fix bugs without a minimal
|
||||
reproduction, so if we don't hear back from you we are going to close issues
|
||||
that don't have enough information to be reproduced.
|
||||
reproduction scenario, so if we don't hear back from you we may close the issue.
|
||||
|
||||
### Submitting a Pull Request (PR)
|
||||
|
||||
Search GitHub for an open or closed PR that relates to your submission. You
|
||||
don't want to duplicate effort. Fork the project, make your changes in **a new
|
||||
git branch** and commit your changes with a descriptive commit message. Then
|
||||
push your branch to GitHub and send a PR to `mkdocs-material:master`. If we
|
||||
suggest changes, make the required updates, rebase your branch and push
|
||||
the changes to your GitHub repository, which will automatiaclly update your PR.
|
||||
don't want to duplicate effort. If you do not find a related issue or PR,
|
||||
go ahead.
|
||||
|
||||
1. **Development**: Fork the project, set up the [development environment][4],
|
||||
make your changes in a separate git branch and add descriptive messages to
|
||||
your commits.
|
||||
|
||||
2. **Build**: Before submitting a pull requests, build the theme. This is a
|
||||
mandatory requirement for your PR to get accepted, as the theme should at
|
||||
all times be installable through GitHub.
|
||||
|
||||
3. **Pull Request**: After building the theme, commit the compiled output, push
|
||||
your branch to GitHub and send a PR to `mkdocs-material:master`. If we
|
||||
suggest changes, make the required updates, rebase your branch and push the
|
||||
changes to your GitHub repository, which will automatically update your PR.
|
||||
|
||||
After your PR is merged, you can safely delete your branch and pull the changes
|
||||
from the main (upstream) repository.
|
||||
|
||||
[4]: http://localhost:8000/customization/#theme-development
|
||||
|
||||
@ -19,7 +19,7 @@ JavaScript files to the `docs` directory.
|
||||
|
||||
If you want to tweak some colors or change the spacing of certain elements,
|
||||
you can do this in a separate stylesheet. The easiest way is by creating a
|
||||
new stylesheet file in your docs directory:
|
||||
new stylesheet file in your `docs` directory:
|
||||
|
||||
``` sh
|
||||
mkdir docs/stylesheets
|
||||
@ -40,7 +40,7 @@ saving, as the MkDocs development server implements live reloading. Cool, huh?
|
||||
|
||||
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 your `docs` directory:
|
||||
|
||||
``` sh
|
||||
mkdir docs/javascripts
|
||||
@ -99,6 +99,7 @@ The directory layout of the Material theme is as follows:
|
||||
│ ├─ fonts.html # Webfont definitions
|
||||
│ ├─ footer.html # Footer bar
|
||||
│ ├─ header.html # Header bar
|
||||
│ ├─ i18n.html # Localized labels
|
||||
│ ├─ nav-item.html # Main navigation item
|
||||
│ ├─ nav.html # Main navigation
|
||||
│ ├─ search.html # Search box
|
||||
@ -183,6 +184,7 @@ Next, all dependencies need to be installed, which is done with:
|
||||
|
||||
``` sh
|
||||
cd mkdocs-material
|
||||
pip install -r requirements.txt
|
||||
npm install
|
||||
```
|
||||
|
||||
@ -199,8 +201,7 @@ npm run start
|
||||
|
||||
This will also start the MkDocs development server which will monitor changes
|
||||
on assets, templates and documentation. Point your browser to
|
||||
[localhost:8000](http://localhost:8000) and you should see this very
|
||||
documentation in front of your eyes.
|
||||
[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
|
||||
@ -211,7 +212,14 @@ $md-color-primary: $clr-red-400;
|
||||
$md-color-accent: $clr-teal-a700;
|
||||
```
|
||||
|
||||
!!! 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
|
||||
overriden when the theme is built.
|
||||
|
||||
[9]: http://gulpjs.com
|
||||
[10]: http://localhost:8000
|
||||
|
||||
### Build process
|
||||
|
||||
|
||||
@ -18,8 +18,8 @@ markdown_extensions:
|
||||
## Usage
|
||||
|
||||
Admonition blocks follow a simple syntax: every block is started with `!!!`,
|
||||
followed by a single keyword which is used as the [type qualifier](#types) of
|
||||
the block. The content of the block then follows on the next line, indented by
|
||||
followed by a single keyword which is used as the [type qualifier][2] of the
|
||||
block. The content of the block then follows on the next line, indented by
|
||||
four spaces.
|
||||
|
||||
Example:
|
||||
@ -38,6 +38,8 @@ Result:
|
||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
||||
massa, nec semper lorem quam in massa.
|
||||
|
||||
[2]: #types
|
||||
|
||||
### Changing the title
|
||||
|
||||
By default, the block title will equal the type qualifier. However, it can
|
||||
@ -61,8 +63,8 @@ Result:
|
||||
|
||||
### Removing the title
|
||||
|
||||
Similar to setting a [custom title](#changing-the-title), the icon and title
|
||||
can be omitted by providing an empty string after the type qualifier:
|
||||
Similar to setting a [custom title][3], the icon and title can be omitted by
|
||||
providing an empty string after the type qualifier:
|
||||
|
||||
Example:
|
||||
|
||||
@ -80,18 +82,20 @@ Result:
|
||||
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
|
||||
massa, nec semper lorem quam in massa.
|
||||
|
||||
[3]: #changing-the-title
|
||||
|
||||
### Embedded code blocks
|
||||
|
||||
Blocks can contain all kinds of text content, including headlines, lists,
|
||||
paragraphs and other blocks – except code blocks, because the parser from the
|
||||
standard Markdown library does not account for those.
|
||||
|
||||
However, the [PyMdown Extensions][2] package adds an extension called
|
||||
[SuperFences][3], which makes it possible to nest code blocks within other
|
||||
However, the [PyMdown Extensions][4] package adds an extension called
|
||||
[SuperFences][5], which makes it possible to nest code blocks within other
|
||||
blocks.
|
||||
|
||||
[2]: https://facelessuser.github.io/pymdown-extensions
|
||||
[3]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
||||
[4]: https://facelessuser.github.io/pymdown-extensions
|
||||
[5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
||||
|
||||
Example:
|
||||
|
||||
@ -125,7 +129,9 @@ Example:
|
||||
Admonition supports user-defined type qualifiers which may influence the style
|
||||
of the inserted block. Following is a list of type qualifiers supported by the
|
||||
Material theme, whereas the default type, and thus fallback for unknown type
|
||||
qualifiers, is [note](#note).
|
||||
qualifiers, is [note][6].
|
||||
|
||||
[6]: #note
|
||||
|
||||
### Note
|
||||
|
||||
|
||||
@ -15,8 +15,8 @@ The PyMdown Extensions package can be installed with the following command:
|
||||
pip install pymdown-extensions
|
||||
```
|
||||
|
||||
The following list of extensions that are part of the PyMdown Extensions package
|
||||
are recommended to be used together with the Material theme:
|
||||
The following list of extensions that are part of the PyMdown Extensions
|
||||
package are recommended to be used together with the Material theme:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -33,14 +33,6 @@ markdown_extensions:
|
||||
- pymdownx.tilde
|
||||
```
|
||||
|
||||
Additionally, there is a [MathJax integration](#arithmatex) which should only
|
||||
be switched on if needed, as it adds a few hundred kb of JavaScript:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.arithmatex
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### GitHub Flavored Markdown
|
||||
@ -138,31 +130,32 @@ The portion of text that should be erased must be enclosed in two tildes
|
||||
|
||||
#### Caret
|
||||
|
||||
[Caret][11] is the sister extension of [Tilde](#tilde) and makes it possible to
|
||||
[Caret][11] is the sister extension of [Tilde][12] and makes it possible to
|
||||
highlight ^^inserted text^^. The portion of text that should be marked as added
|
||||
must be enclosed in two carets `^^...^^`.
|
||||
|
||||
[11]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
|
||||
[12]: #tilde
|
||||
|
||||
#### Mark
|
||||
|
||||
[Mark][12] adds the ability to ==highlight text== like it was marked with a
|
||||
[Mark][13] adds the ability to ==highlight text== like it was marked with a
|
||||
==yellow text marker==. The portion of text that should be highlighted must be
|
||||
enclosed in two equal signs `==...==`.
|
||||
|
||||
[12]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
|
||||
[13]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
|
||||
|
||||
#### SmartSymbols
|
||||
|
||||
[SmartSymbols][13] converts markup for special characters into their
|
||||
[SmartSymbols][14] converts markup for special characters into their
|
||||
corresponding symbols, e.g. arrows (<--, -->, <-->), trademark and copyright
|
||||
symbols ((c), (tm), (r)) and fractions (1/2, 1/4, ...).
|
||||
|
||||
[13]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
|
||||
[14]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
|
||||
|
||||
#### Critic
|
||||
|
||||
[Critic][14] implements [Critic Markup][15], a Markdown extension that enables
|
||||
[Critic][15] implements [Critic Markup][16], a Markdown extension that enables
|
||||
the tracking of changes (additions, deletions and comments) on documents.
|
||||
During compilation of the Markdown document, changes can be rendered (default),
|
||||
accepted or rejected.
|
||||
@ -171,21 +164,21 @@ Text can be {--deleted--} and replacement text {++added++}. This can also be
|
||||
combined in {~~one~>a single~~} operation. {==Highlighting==} is also possible
|
||||
{>>and comments can be added inline<<}.
|
||||
|
||||
[14]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
|
||||
[15]: http://criticmarkup.com/
|
||||
[15]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
|
||||
[16]: http://criticmarkup.com/
|
||||
|
||||
### Math and code highlighting
|
||||
|
||||
#### Arithmatex
|
||||
|
||||
[Arithmatex][16] integrates Material with [MathJax][17] which parses
|
||||
[Arithmatex][17] integrates Material with [MathJax][18] which parses
|
||||
block-style and inline equations written in TeX markup and outputs them in
|
||||
mathematical notation. See [this thread][18] for a short introduction and quick
|
||||
mathematical notation. See [this thread][19] for a short introduction and quick
|
||||
reference on how to write equations in TeX syntax.
|
||||
|
||||
[16]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
|
||||
[17]: https://www.mathjax.org/
|
||||
[18]: http://meta.math.stackexchange.com/questions/5020/
|
||||
[17]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
|
||||
[18]: https://www.mathjax.org/
|
||||
[19]: http://meta.math.stackexchange.com/questions/5020/
|
||||
|
||||
##### Blocks
|
||||
|
||||
@ -221,9 +214,9 @@ Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$
|
||||
|
||||
#### Inlinehilite
|
||||
|
||||
[Inlinehilite][19] adds support for inline code highlighting. It's useful for
|
||||
[Inlinehilite][20] adds support for inline code highlighting. It's useful for
|
||||
short snippets included within body copy, e.g. `#!js var test = 0;` and can be
|
||||
achived by prefixing inline code with a shebang and language identifier,
|
||||
e.g. `#!js`.
|
||||
|
||||
[19]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
|
||||
[20]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
|
||||
|
||||
@ -26,8 +26,8 @@ pip install mkdocs && mkdocs --version
|
||||
|
||||
Material requires MkDocs >= 0.16.
|
||||
|
||||
Furthermore, it is highly recommended to install [Pygments][2] and the [PyMdown
|
||||
Extensions][3] to get the most out of the Material theme:
|
||||
Furthermore, it is highly recommended to install [Pygments][2] and the
|
||||
[PyMdown Extensions][3] to get the most out of the Material theme:
|
||||
|
||||
```sh
|
||||
pip install pygments
|
||||
@ -71,8 +71,9 @@ repository into a subfolder of your project's root directory:
|
||||
git clone https://github.com/squidfunk/mkdocs-material.git
|
||||
```
|
||||
|
||||
This is especially useful if you want to extend the theme and use partials.
|
||||
The theme will reside in the folder `mkdocs-material/material`.
|
||||
This is especially useful if you want to extend the theme and override some
|
||||
parts of the theme. The theme will reside in the folder
|
||||
`mkdocs-material/material`.
|
||||
|
||||
## Usage
|
||||
|
||||
@ -96,9 +97,11 @@ as you go - very handy. Spin it up with the following command:
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
Now you can point your browser to [localhost:8000](http://localhost:8000) and
|
||||
the Material theme should be visible. You can now start writing your
|
||||
documentation, or read on and customize the theme through some options.
|
||||
Now you can point your browser to [localhost:8000][4] and the Material theme
|
||||
should be visible. You can now start writing your documentation, or read on and
|
||||
customize the theme through some options.
|
||||
|
||||
[4]: http://localhost:8000
|
||||
|
||||
## Options
|
||||
|
||||
@ -108,7 +111,7 @@ project's `mkdocs.yml`. See the following section for all available options.
|
||||
### Changing the color palette
|
||||
|
||||
Material defines a default hue for every primary and accent color on Google's
|
||||
material design [color palette][4]. This makes it very easy to change the
|
||||
material design [color palette][5]. This makes it very easy to change the
|
||||
overall look of the theme. Just set the primary and accent colors using the
|
||||
following variables in your `mkdocs.yml`:
|
||||
|
||||
@ -127,10 +130,11 @@ green`, `lime`, `yellow`, `amber`, `orange`, `deep orange`, `brown`, `grey` and
|
||||
|
||||
If the color is set via this configuration, an additional CSS file that
|
||||
defines the color palette is included. If you want to keep things lean, clone
|
||||
the repository and recompile the theme with your custom colors set. See [this
|
||||
article](customization.md) for more information.
|
||||
the repository and recompile the theme with your custom colors set. See
|
||||
[this article][6] for more information.
|
||||
|
||||
[4]: http://www.materialui.co/colors
|
||||
[5]: http://www.materialui.co/colors
|
||||
[6]: customization.md
|
||||
|
||||
#### Primary colors
|
||||
|
||||
@ -197,10 +201,10 @@ Click on a tile to change the accent color of the theme:
|
||||
|
||||
### Changing the font family
|
||||
|
||||
Material uses the [Roboto font family][5] by default, specifically the regular
|
||||
sans-serif type for text and the monospaced type for code. Both fonts are
|
||||
loaded from [Google Fonts][6] and can easily be changed to other fonts, like
|
||||
for example the [Ubuntu font family][7]:
|
||||
Material uses the [Roboto font family][7] by default, specifically the regular
|
||||
sans-serif type for text and the `monospaced` type for code. Both fonts are
|
||||
loaded from [Google Fonts][8] and can easily be changed to other fonts, like
|
||||
for example the [Ubuntu font family][9]:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
@ -209,7 +213,7 @@ extra:
|
||||
code: 'Ubuntu Mono'
|
||||
```
|
||||
|
||||
The text font will be loaded in font-weights 400 and **700**, the monospaced
|
||||
The text font will be loaded in font-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 the Google Fonts loading magic, just set `font` to `'none'`:
|
||||
|
||||
@ -218,9 +222,9 @@ extra:
|
||||
font: 'none'
|
||||
```
|
||||
|
||||
[5]: https://fonts.google.com/specimen/Roboto
|
||||
[6]: https://fonts.google.com/
|
||||
[7]: https://fonts.google.com/specimen/Ubuntu
|
||||
[7]: https://fonts.google.com/specimen/Roboto
|
||||
[8]: https://fonts.google.com/
|
||||
[9]: https://fonts.google.com/specimen/Ubuntu
|
||||
|
||||
### Adding a logo
|
||||
|
||||
@ -239,7 +243,7 @@ extra:
|
||||
|
||||
If you want to link your social accounts, the Material theme provides an easy
|
||||
way for doing this in the footer of the documentation using the automatically
|
||||
included [FontAwesome][8] webfont. The syntax is simple – the `type` denotes
|
||||
included [FontAwesome][10] webfont. The syntax is simple – the `type` denotes
|
||||
the name of the social service, e.g. `github`, `twitter` or `linkedin` and
|
||||
the `link`, well, resembles the link:
|
||||
|
||||
@ -258,7 +262,7 @@ The links are generated in order and the type of the link must match the name
|
||||
of the FontAwesome glyph. The `fa` is automatically added, so `github` will
|
||||
result in `fa fa-github`.
|
||||
|
||||
[8]: http://fontawesome.io/icons/
|
||||
[10]: http://fontawesome.io/icons/
|
||||
|
||||
### Google Analytics integration
|
||||
|
||||
@ -291,19 +295,22 @@ inside the macro `t`:
|
||||
```
|
||||
|
||||
Just copy the file from the original theme and make your adjustments. See the
|
||||
section on [overriding partials](customization.md/#overriding-partials) in the
|
||||
customization guide.
|
||||
section on [overriding partials][11] in the customization guide.
|
||||
|
||||
[11]: customization.md#overriding-partials
|
||||
|
||||
### More advanced customization
|
||||
|
||||
If you want to change the general appearance of the Material theme, see
|
||||
[this article](customization.md) for more information on advanced customization.
|
||||
[this article][12] for more information on advanced customization.
|
||||
|
||||
[12]: customization.md
|
||||
|
||||
## Extensions
|
||||
|
||||
MkDocs supports several [Markdown extensions][9]. The following extensions are
|
||||
not enabled by default (see the link for which are enabled by default) but
|
||||
highly recommended, so they should be switched on at all times:
|
||||
MkDocs supports several [Markdown extensions][13]. The following extensions
|
||||
are not enabled by default (see the link for which are enabled by default)
|
||||
but highly recommended, so they should be switched on at all times:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
@ -312,16 +319,29 @@ markdown_extensions:
|
||||
- toc(permalink=true)
|
||||
```
|
||||
|
||||
!!! warning "Migrating from Material 0.2.x"
|
||||
|
||||
The [CodeHilite][14] extension was included with
|
||||
`codehilite(css_class=code)` which switched the CSS class from
|
||||
`.codehilite` to `.code`. The current version of the theme doesn't require
|
||||
that and defines styles for the default `.codehilite` class, so the part
|
||||
`css_class=code` needs to be removed.
|
||||
|
||||
For more information, see the following list of extensions supported by the
|
||||
Material theme including more information regarding installation and usage:
|
||||
|
||||
* [Admonition](extensions/admonition.md)
|
||||
* [Codehilite](extensions/codehilite.md)
|
||||
* [Permalinks](extensions/permalinks.md)
|
||||
* [Footnotes](extensions/footnotes.md)
|
||||
* [PyMdown Extensions](extensions/pymdown.md)
|
||||
* [Admonition][15]
|
||||
* [Codehilite][14]
|
||||
* [Permalinks][16]
|
||||
* [Footnotes][17]
|
||||
* [PyMdown Extensions][18]
|
||||
|
||||
[9]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
|
||||
[13]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
|
||||
[14]: extensions/codehilite.md
|
||||
[15]: extensions/admonition.md
|
||||
[16]: extensions/permalinks.md
|
||||
[17]: extensions/footnotes.md
|
||||
[18]: extensions/pymdown.md
|
||||
|
||||
## Full example
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
**MIT License**
|
||||
|
||||
Copyright (c) 2016 Martin Donath
|
||||
Copyright © 2016 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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user