Cool_Tools/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-12 01:50:52 +01:00
Code Issues Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
squidfunk 2016-02-17 18:08:11 +01:00
parent e1cf87b483
commit 9d9effc106
7 changed files with 108 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
README.md
View File

@ -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

40
docs/customization.md
View File

@ -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

70
docs/getting-started.md
View File

@ -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

47
docs/index.md
View File

@ -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.
![Material Screenshot](images/screen.png)
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

3
docs/license.md
View File

@ -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

2
material/base.html
View File

@ -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 {

2
src/base.html
View File

@ -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>