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

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 ## License
**MIT License** **MIT License**
Copyright (c) 2016 Martin Donath Copyright (c) 2016 Martin Donath
Permission is hereby granted, free of charge, to any person obtaining a copy 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 ## Fundamental changes
If you want to make larger adjustments like changing the color palette or 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 typography, you should check out or download the repository of the project and
the SASS sources with your changes. The project design is very modular, so compile the SASS sources with your changes. The project design is very modular,
most things can be changed by tweaking a few variables. so most things can be tweaked by changing a few variables.
### Setup ### Setup
In order to compile the project, you need `node`, `bower` and `gulp` up and In order to compile the project, you need `node` with a version greater than
running. It's best to use the most recent versions, but it should also work if `0.11` up and running. Then, make sure `bower` is installed or install it:
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: ``` 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 ``` sh
git clone https://github.com/squidfunk/mkdocs-material git clone https://github.com/squidfunk/mkdocs-material
``` ```
Then you change the directory and install all dependencies specified in the 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 ``` sh
cd mkdocs-material cd mkdocs-material
@ -52,12 +57,12 @@ npm install && bower install
### Development ### Development
The asset pipeline is contained in `Gulpfile.js`, which you can start with 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 `gulp watch`. If you specify the `--mkdocs` flag, this will also run
documentation. Point your browser to [localhost:8000](http://localhost:8000) `mkdocs serve`, to monitor changes to the documentation. Point your browser to [localhost:8000](http://localhost:8000) and you should see this very
and you should see this very documentation in front of your eyes. documentation in front of your eyes.
``` sh ``` sh
gulp watch gulp watch --mkdocs
``` ```
For example, changing the color palette is as simple as changing the `$primary` 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 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, 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` the final theme is located in the `material` directory. Add the `theme_dir`
variable pointing to the aforementioned directory in your original 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]: http://www.mkdocs.org
[MkDocs documentation]: http://www.mkdocs.org/user-guide/styling-your-docs/#customising-a-theme [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 ### 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 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 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 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 The Material theme adds some extra variables for configuration via your
project's `mkdocs.yml`. See the following section for all available options. 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 ### Adding a version
In order to add the current version next to the project banner inside the In order to add the current version next to the project banner inside the
@ -99,6 +86,46 @@ extra:
version: '0.1.0' 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 ### Adding a GitHub and Twitter account
If you have a GitHub and/or Twitter account, you can add links to your If you have a GitHub and/or Twitter account, you can add links to your
@ -114,9 +141,8 @@ extra:
### More advanced customization ### More advanced customization
If you want to change the fonts or colors - you are lucky. The Material theme If you want to change the colors or general appearance of the Material theme,
is built with a sophisticated asset pipeline. See see [this article](customization.md) for more information on advanced
[this article](customization.md) for more information on advanced
customization. customization.
## Extensions ## Extensions
@ -170,7 +196,7 @@ In order to add a note, use the following syntax inside your article:
Nothing to see here, move along. Nothing to see here, move along.
``` ```
This will print the following: This will print the following block:
!!! note !!! note
Nothing to see here, move along. Nothing to see here, move along.
@ -209,6 +235,9 @@ theme: 'material'
extra: extra:
version: '0.1.0' version: '0.1.0'
logo: 'images/logo.png' logo: 'images/logo.png'
font:
text: 'Roboto'
code: 'Roboto Mono'
author: author:
github: 'my-github-handle' github: 'my-github-handle'
twitter: 'my-twitter-handle' twitter: 'my-twitter-handle'
@ -222,8 +251,11 @@ markdown_extensions:
``` ```
[MkDocs]: http://www.mkdocs.org [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 [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 [extra]: http://www.mkdocs.org/user-guide/styling-your-docs/#customising-a-theme
[permalinks]: https://en.wikipedia.org/wiki/Permalink [permalinks]: https://en.wikipedia.org/wiki/Permalink
[Admonition]: https://pythonhosted.org/Markdown/extensions/admonition.html [Admonition]: https://pythonhosted.org/Markdown/extensions/admonition.html

47
docs/index.md
View File

@ -2,46 +2,49 @@
## Beautiful documentation ## Beautiful documentation
You're currently looking at a full responsive [MkDocs][] theme in the spirit of Material is a theme for [MkDocs][], an excellent static site generator geared
Google's [material design][] guidelines. MkDocs is an excellent static site towards project documentation. It is built using Google's [material design][]
documentation generator that is meant for building good looking project guidelines, full responsive, optimized for touch and pointer devices as well
documentation. as all sorts of screen sizes.
![Material Screenshot](images/screen.png) ![Material Screenshot](images/screen.png)
This theme is **optimized for all sorts of devices** and is built from scratch Material is very lightweight – it is built from scratch using Javascript and
without any bloated Javascript or CSS Frameworks with **only 24kb of JS and CSS that weighs less than 30kb (minified, gzipped and excluding Google Fonts
CSS** (minified, gzipped and excluding Google WebFonts and Analytics). Yet, it and Analytics). Yet, it is highly customizable and degrades gracefully in older
is highly customizable in terms of fonts, colors and gracefully supports older
browsers. browsers.
## Features ## Features
- Beautiful, readable and very user-friendly design based on Google's - Beautiful, readable and very user-friendly design based on Google's material
**material design** guidelines, packed in a **full responsive** template design guidelines, packed in a full responsive template with a well-defined
with a well-defined color palette, great typography, as well as a beautiful color palette, great typography, as well as a beautiful search interface and
search interface and footer. 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 fixed/sticky header, a drawer that even works without Javascript using
the `:checked` hack with fallbacks, **responsive tables** that scroll when the [checkbox hack][] with fallbacks, responsive tables that scroll when
the screen is too small and **well-defined print styles**. the screen is too small and well-defined print styles.
- Extra configuration options like **project logo**, links to the authors - Extra configuration options like a [project logo][], links to the authors
**GitHub and Twitter accounts** and display of the **amount of stars** the [GitHub and Twitter accounts][] and display of the amount of stars the
project has on GitHub. 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 built on-top of [Gulp][] with `npm` and `bower` and modular and abstracted
style definitions built with [SASS][]. style definitions built with [SASS][].
- **Web application capability** on iOS - when the page is saved to the - Web application capability on iOS - when the page is saved to the homescreen,
homescreen, it behaves and looks like a native application. it behaves and looks like a native application.
See the [getting started guide](getting-started.md) for instructions how to get See the [getting started guide](getting-started.md) for instructions how to get
it up and running. it up and running.
[material design]: https://www.google.com/design/spec/material-design
[MkDocs]: http://www.mkdocs.org [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 [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 # License
**MIT License** **MIT License**
Copyright (c) 2016 Martin Donath Copyright (c) 2016 Martin Donath
Permission is hereby granted, free of charge, to any person obtaining a copy 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 %} {% if config.extra.font and config.extra.font.code %}
{% set code = config.extra.font.code %} {% set code = config.extra.font.code %}
{% endif %} {% 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 }}"> <link rel="stylesheet" href="//fonts.googleapis.com/css?family={{ font }}">
<style> <style>
body, input { body, input {

2
src/base.html
View File

@ -96,7 +96,7 @@
{% if config.extra.font and config.extra.font.code %} {% if config.extra.font and config.extra.font.code %}
{% set code = config.extra.font.code %} {% set code = config.extra.font.code %}
{% endif %} {% endif %}
{% set font = text + ':400,700|' + code | replace('+', ' ') %} {% set font = text + ':400,700|' + code | replace(' ', '+') %}
<link rel="stylesheet" type="text/css" <link rel="stylesheet" type="text/css"
href="//fonts.googleapis.com/css?family={{ font }}" /> href="//fonts.googleapis.com/css?family={{ font }}" />
<style> <style>