diff --git a/README.md b/README.md index d34a63bed..967fa8a67 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/customization.md b/docs/customization.md index 04ade664c..7814b6a8c 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -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 diff --git a/docs/getting-started.md b/docs/getting-started.md index 9574c5631..0a1a8c6ba 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -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 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index f6fc12fec..b6d7fd5ba 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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/ \ No newline at end of file +[SASS]: http://sass-lang.com \ No newline at end of file diff --git a/docs/license.md b/docs/license.md index 01ce921bb..27d4332be 100644 --- a/docs/license.md +++ b/docs/license.md @@ -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 diff --git a/material/base.html b/material/base.html index 9817bf7f6..48a88fe00 100644 --- a/material/base.html +++ b/material/base.html @@ -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(' ', '+') %}