mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-27 17:00:54 +01:00
Updated documentation
This commit is contained in:
squidfunk
parent
e1cf87b483
commit
9d9effc106
@ -27,7 +27,8 @@ http://squidfunk.github.io/mkdocs-material/
|
||||
|
||||
## License
|
||||
|
||||
**MIT License**
|
||||
**MIT License**
|
||||
|
||||
Copyright (c) 2016 Martin Donath
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
|
||||
@ -26,23 +26,28 @@ Further assistance on including extra CSS and Javascript can be found in the
|
||||
## Fundamental changes
|
||||
|
||||
If you want to make larger adjustments like changing the color palette or
|
||||
typography, you should check out the repository of the project and compile
|
||||
the SASS sources with your changes. The project design is very modular, so
|
||||
most things can be changed by tweaking a few variables.
|
||||
typography, you should check out or download the repository of the project and
|
||||
compile the SASS sources with your changes. The project design is very modular,
|
||||
so most things can be tweaked by changing a few variables.
|
||||
|
||||
### Setup
|
||||
|
||||
In order to compile the project, you need `node`, `bower` and `gulp` up and
|
||||
running. It's best to use the most recent versions, but it should also work if
|
||||
your installations are not too dated. The project itself is hosted on GitHub,
|
||||
so the next thing you should do is clone the project from GitHub:
|
||||
In order to compile the project, you need `node` with a version greater than
|
||||
`0.11` up and running. Then, make sure `bower` is installed or install it:
|
||||
|
||||
``` sh
|
||||
npm install -g bower
|
||||
```
|
||||
|
||||
The project itself is hosted on GitHub, so the next
|
||||
thing you should do is clone the project from GitHub:
|
||||
|
||||
``` sh
|
||||
git clone https://github.com/squidfunk/mkdocs-material
|
||||
```
|
||||
|
||||
Then you change the directory and install all dependencies specified in the
|
||||
`package.json` and `bower.json`:
|
||||
`package.json` and `bower.json` with the following command:
|
||||
|
||||
``` sh
|
||||
cd mkdocs-material
|
||||
@ -52,12 +57,12 @@ npm install && bower install
|
||||
### Development
|
||||
|
||||
The asset pipeline is contained in `Gulpfile.js`, which you can start with
|
||||
`gulp watch`. This will also run `mkdocs serve`, to monitor changes to the
|
||||
documentation. Point your browser to [localhost:8000](http://localhost:8000)
|
||||
and you should see this very documentation in front of your eyes.
|
||||
`gulp watch`. If you specify the `--mkdocs` flag, this will also run
|
||||
`mkdocs serve`, to monitor changes to the documentation. Point your browser to [localhost:8000](http://localhost:8000) and you should see this very
|
||||
documentation in front of your eyes.
|
||||
|
||||
``` sh
|
||||
gulp watch
|
||||
gulp watch --mkdocs
|
||||
```
|
||||
|
||||
For example, changing the color palette is as simple as changing the `$primary`
|
||||
@ -80,11 +85,18 @@ When you finished making your changes, you can build the theme by invoking:
|
||||
gulp build --production
|
||||
```
|
||||
|
||||
The `production` flag triggers the production-level compilation and
|
||||
The `--production` flag triggers the production-level compilation and
|
||||
minification of all CSS and Javascript sources. When the command is ready,
|
||||
the final theme is located in the `material` directory. Add the `theme_dir`
|
||||
variable pointing to the aforementioned directory in your original
|
||||
`mkdocs.yml` and you should see your documentation with your changes!
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
theme_dir: 'mkdocs-material/material'
|
||||
```
|
||||
|
||||
Now you can run `mkdocs build` and you should see your documentation with your
|
||||
changes to the original Material theme.
|
||||
|
||||
[MkDocs]: http://www.mkdocs.org
|
||||
[MkDocs documentation]: http://www.mkdocs.org/user-guide/styling-your-docs/#customising-a-theme
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
### Installing MkDocs
|
||||
|
||||
In order to install [MkDocs][], Python and `pip` - the Python package manager -
|
||||
In order to install [MkDocs][], Python and `pip` – the Python package manager –
|
||||
need to be up and running. Assuming you are a developer and have a basic
|
||||
understanding of how things work and what StackOverflow is, we won't provide
|
||||
guidelines on setting those up. You can verify if you're already good to go
|
||||
@ -76,19 +76,6 @@ on and customize the theme through some options.
|
||||
The Material theme adds some extra variables for configuration via your
|
||||
project's `mkdocs.yml`. See the following section for all available options.
|
||||
|
||||
### Adding a logo
|
||||
|
||||
If your project has a logo, you can add it to the drawer/navigation by defining
|
||||
the variable `extra.logo`. Ideally, the image of your logo should have
|
||||
rectangular shape with a minimum resolution of 128x128. The logo will also be
|
||||
used as a web application icon on iOS. Simply create the folder `docs/images`,
|
||||
add your image and reference it via:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
logo: 'images/logo.png'
|
||||
```
|
||||
|
||||
### Adding a version
|
||||
|
||||
In order to add the current version next to the project banner inside the
|
||||
@ -99,6 +86,46 @@ extra:
|
||||
version: '0.1.0'
|
||||
```
|
||||
|
||||
This will also change the link behind the download button to point to the
|
||||
archive with the respective version on GitHub, assuming a release tagged with
|
||||
this exact version identifier.
|
||||
|
||||
### Adding a logo
|
||||
|
||||
If your project has a logo, you can add it to the drawer/navigation by defining
|
||||
the variable `extra.logo`. Ideally, the image of your logo should have
|
||||
rectangular shape with a minimum resolution of 128x128 and leave some room
|
||||
towards the edges. The logo will also be used as a web application icon on iOS.
|
||||
Simply create the folder `docs/images`, add your image and reference it via:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
logo: 'images/logo.png'
|
||||
```
|
||||
|
||||
### Changing the font family
|
||||
|
||||
Material uses the [Ubuntu font family][] by default, specifically the regular
|
||||
sans-serif type for text and the monospaced type for code. Both fonts are
|
||||
loaded from [Google Fonts][] and can be easily changed to other fonts, like for
|
||||
example Google's own [Roboto font][]:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
font:
|
||||
text: 'Roboto'
|
||||
code: 'Roboto Mono'
|
||||
```
|
||||
|
||||
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 `extra.font` to `'none'`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
font: 'none'
|
||||
```
|
||||
|
||||
### Adding a GitHub and Twitter account
|
||||
|
||||
If you have a GitHub and/or Twitter account, you can add links to your
|
||||
@ -114,9 +141,8 @@ extra:
|
||||
|
||||
### More advanced customization
|
||||
|
||||
If you want to change the fonts or colors - you are lucky. The Material theme
|
||||
is built with a sophisticated asset pipeline. See
|
||||
[this article](customization.md) for more information on advanced
|
||||
If you want to change the colors or general appearance of the Material theme,
|
||||
see [this article](customization.md) for more information on advanced
|
||||
customization.
|
||||
|
||||
## Extensions
|
||||
@ -170,7 +196,7 @@ In order to add a note, use the following syntax inside your article:
|
||||
Nothing to see here, move along.
|
||||
```
|
||||
|
||||
This will print the following:
|
||||
This will print the following block:
|
||||
|
||||
!!! note
|
||||
Nothing to see here, move along.
|
||||
@ -209,6 +235,9 @@ theme: 'material'
|
||||
extra:
|
||||
version: '0.1.0'
|
||||
logo: 'images/logo.png'
|
||||
font:
|
||||
text: 'Roboto'
|
||||
code: 'Roboto Mono'
|
||||
author:
|
||||
github: 'my-github-handle'
|
||||
twitter: 'my-twitter-handle'
|
||||
@ -222,8 +251,11 @@ markdown_extensions:
|
||||
```
|
||||
|
||||
[MkDocs]: http://www.mkdocs.org
|
||||
[Ubuntu font family]: http://font.ubuntu.com
|
||||
[Google Fonts]: https://www.google.com/fonts
|
||||
[Roboto font]: https://www.google.com/fonts/specimen/Roboto
|
||||
[Markdown extensions]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions
|
||||
[highlight.js]: https://highlightjs.org/
|
||||
[highlight.js]: https://highlightjs.org
|
||||
[extra]: http://www.mkdocs.org/user-guide/styling-your-docs/#customising-a-theme
|
||||
[permalinks]: https://en.wikipedia.org/wiki/Permalink
|
||||
[Admonition]: https://pythonhosted.org/Markdown/extensions/admonition.html
|
||||
@ -2,46 +2,49 @@
|
||||
|
||||
## Beautiful documentation
|
||||
|
||||
You're currently looking at a full responsive [MkDocs][] theme in the spirit of
|
||||
Google's [material design][] guidelines. MkDocs is an excellent static site
|
||||
documentation generator that is meant for building good looking project
|
||||
documentation.
|
||||
Material is a theme for [MkDocs][], an excellent static site generator geared
|
||||
towards project documentation. It is built using Google's [material design][]
|
||||
guidelines, full responsive, optimized for touch and pointer devices as well
|
||||
as all sorts of screen sizes.
|
||||
|
||||
|
||||
|
||||
This theme is **optimized for all sorts of devices** and is built from scratch
|
||||
without any bloated Javascript or CSS Frameworks with **only 24kb of JS and
|
||||
CSS** (minified, gzipped and excluding Google WebFonts and Analytics). Yet, it
|
||||
is highly customizable in terms of fonts, colors and gracefully supports older
|
||||
Material is very lightweight – it is built from scratch using Javascript and
|
||||
CSS that weighs less than 30kb (minified, gzipped and excluding Google Fonts
|
||||
and Analytics). Yet, it is highly customizable and degrades gracefully in older
|
||||
browsers.
|
||||
|
||||
## Features
|
||||
|
||||
- Beautiful, readable and very user-friendly design based on Google's
|
||||
**material design** guidelines, packed in a **full responsive** template
|
||||
with a well-defined color palette, great typography, as well as a beautiful
|
||||
search interface and footer.
|
||||
- Beautiful, readable and very user-friendly design based on Google's material
|
||||
design guidelines, packed in a full responsive template with a well-defined
|
||||
color palette, great typography, as well as a beautiful search interface and
|
||||
footer.
|
||||
|
||||
- Well-tested and **optimized CSS and Javascript**, including a cross-browser
|
||||
- Well-tested and optimized Javascript and CSS including a cross-browser
|
||||
fixed/sticky header, a drawer that even works without Javascript using
|
||||
the `:checked` hack with fallbacks, **responsive tables** that scroll when
|
||||
the screen is too small and **well-defined print styles**.
|
||||
the [checkbox hack][] with fallbacks, responsive tables that scroll when
|
||||
the screen is too small and well-defined print styles.
|
||||
|
||||
- Extra configuration options like **project logo**, links to the authors
|
||||
**GitHub and Twitter accounts** and display of the **amount of stars** the
|
||||
- Extra configuration options like a [project logo][], links to the authors
|
||||
[GitHub and Twitter accounts][] and display of the amount of stars the
|
||||
project has on GitHub.
|
||||
|
||||
- **Easily extendable and customizable** due to a well-designed asset pipeline
|
||||
- Easily [extendable and customizable][] due to a well-designed asset pipeline
|
||||
built on-top of [Gulp][] with `npm` and `bower` and modular and abstracted
|
||||
style definitions built with [SASS][].
|
||||
|
||||
- **Web application capability** on iOS - when the page is saved to the
|
||||
homescreen, it behaves and looks like a native application.
|
||||
- Web application capability on iOS - when the page is saved to the homescreen,
|
||||
it behaves and looks like a native application.
|
||||
|
||||
See the [getting started guide](getting-started.md) for instructions how to get
|
||||
it up and running.
|
||||
|
||||
[material design]: https://www.google.com/design/spec/material-design
|
||||
[MkDocs]: http://www.mkdocs.org
|
||||
[material design]: https://www.google.com/design/spec/material-design
|
||||
[checkbox hack]: http://tutorialzine.com/2015/08/quick-tip-css-only-dropdowns-with-the-checkbox-hack/
|
||||
[project logo]: getting-started.md#adding-a-logo
|
||||
[GitHub and Twitter accounts]: getting-started.md#adding-a-github-and-twitter-account
|
||||
[extendable and customizable]: customization.md
|
||||
[Gulp]: http://gulpjs.com
|
||||
[SASS]: http://sass-lang.com/
|
||||
[SASS]: http://sass-lang.com
|
||||
@ -1,6 +1,7 @@
|
||||
# License
|
||||
|
||||
**MIT License**
|
||||
**MIT License**
|
||||
|
||||
Copyright (c) 2016 Martin Donath
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
|
||||
@ -63,7 +63,7 @@
|
||||
{% if config.extra.font and config.extra.font.code %}
|
||||
{% set code = config.extra.font.code %}
|
||||
{% endif %}
|
||||
{% set font = text + ':400,700|' + code | replace('+', ' ') %}
|
||||
{% set font = text + ':400,700|' + code | replace(' ', '+') %}
|
||||
<link rel="stylesheet" href="//fonts.googleapis.com/css?family={{ font }}">
|
||||
<style>
|
||||
body, input {
|
||||
|
||||
@ -96,7 +96,7 @@
|
||||
{% if config.extra.font and config.extra.font.code %}
|
||||
{% set code = config.extra.font.code %}
|
||||
{% endif %}
|
||||
{% set font = text + ':400,700|' + code | replace('+', ' ') %}
|
||||
{% set font = text + ':400,700|' + code | replace(' ', '+') %}
|
||||
<link rel="stylesheet" type="text/css"
|
||||
href="//fonts.googleapis.com/css?family={{ font }}" />
|
||||
<style>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user