From 9ecc9aa8c99b2d57e3eca83e7f1af9042f91961d Mon Sep 17 00:00:00 2001 From: Pascal Berger Date: Sat, 14 Jan 2017 12:42:53 +0100 Subject: [PATCH 1/3] Add documentation how to install using Chocolatey --- docs/getting-started.md | 75 ++++++++++++++++++++++++----------------- 1 file changed, 45 insertions(+), 30 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index fdd2fee65..81b9dda76 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -76,6 +76,21 @@ 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`. +### Installing using Chocolatey + +If you're on Windows you can use [Chocolatey][5] to install [mkdocs-material][6]: + +``` dos +choco install mkdocs-material +``` + +Installing [mkdocs-material][6] will take care of installing all required dependencies like [mkdocs][7] and [Python][8]. + + [5]: https://chocolatey.org + [6]: https://chocolatey.org/packages/mkdocs-material + [7]: https://chocolatey.org/packages/mkdocs + [8]: https://chocolatey.org/packages/Python + ## Usage In order to enable the Material theme just add one of the following lines to @@ -98,11 +113,11 @@ The development server can be started with the following command: mkdocs serve ``` -Now you can point your browser to [localhost:8000][5] and the Material theme +Now you can point your browser to [localhost:8000][9] and the Material theme should be visible. From here on, you can start writing your documentation, or read on and customize the theme through some options. - [5]: http://localhost:8000 + [9]: http://localhost:8000 ## Options @@ -112,7 +127,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][6]. This makes it very easy to change the +Material Design [color palette][10]. 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`: @@ -132,10 +147,10 @@ The last three colors can only be used as a primary color. 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 the -guide on [customization][7] for more information. +guide on [customization][11] for more information. - [6]: http://www.materialui.co/colors - [7]: customization.md + [10]: http://www.materialui.co/colors + [11]: customization.md #### Primary colors @@ -202,10 +217,10 @@ Click on a tile to change the accent color of the theme: ### Changing the font family -Material uses the [Roboto font family][8] by default, specifically the regular +Material uses the [Roboto font family][12] by default, specifically the regular sans-serif type for text and the `monospaced` type for code. Both fonts are -loaded from [Google Fonts][9] and can easily be changed to other fonts, like -for example the [Ubuntu font family][10]: +loaded from [Google Fonts][13] and can easily be changed to other fonts, like +for example the [Ubuntu font family][14]: ``` yaml extra: @@ -223,9 +238,9 @@ extra: font: 'none' ``` - [8]: https://fonts.google.com/specimen/Roboto - [9]: https://fonts.google.com/ - [10]: https://fonts.google.com/specimen/Ubuntu + [12]: https://fonts.google.com/specimen/Roboto + [13]: https://fonts.google.com/ + [14]: https://fonts.google.com/specimen/Ubuntu ### Adding a logo @@ -244,7 +259,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][11] webfont. The syntax is simple – the `type` must +included [FontAwesome][15] webfont. The syntax is simple – the `type` must denote the name of the social service, e.g. `github`, `twitter` or `linkedin` and the `link` must contain the URL you want to link to: @@ -263,7 +278,7 @@ The links are generated in order and the `type` of the links must match the name of the FontAwesome glyph. The `fa` is automatically added, so `github` will result in `fa fa-github`. - [11]: http://fontawesome.io/icons/ + [15]: http://fontawesome.io/icons/ ### Google Analytics integration @@ -296,7 +311,7 @@ translations inside the macro `t`: ``` Just copy the file from the original theme and make your adjustments. See the -section on [overriding partials][12] in the customization guide. +section on [overriding partials][16] in the customization guide. !!! warning "Migrating from Material 0.2.x" @@ -304,18 +319,18 @@ section on [overriding partials][12] in the customization guide. `mkdocs.yml`. With 1.0.0 this is no longer possible as the configuration will be ignored. - [12]: customization.md#overriding-partials + [16]: customization.md#overriding-partials ### More advanced customization If you want to change the general appearance of the Material theme, see -[this article][13] for more information on advanced customization. +[this article][17] for more information on advanced customization. - [13]: customization.md + [17]: customization.md ## Extensions -MkDocs supports several [Markdown extensions][14]. The following extensions +MkDocs supports several [Markdown extensions][18]. 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: @@ -329,18 +344,18 @@ markdown_extensions: For more information, see the following list of extensions supported by the Material theme including more information regarding installation and usage: -* [Admonition][15] -* [Codehilite][16] -* [Permalinks][17] -* [Footnotes][18] -* [PyMdown Extensions][19] +* [Admonition][19] +* [Codehilite][20] +* [Permalinks][21] +* [Footnotes][22] +* [PyMdown Extensions][23] - [14]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions - [15]: extensions/admonition.md - [16]: extensions/codehilite.md - [17]: extensions/permalinks.md - [18]: extensions/footnotes.md - [19]: extensions/pymdown.md + [18]: http://www.mkdocs.org/user-guide/writing-your-docs/#markdown-extensions + [19]: extensions/admonition.md + [20]: extensions/codehilite.md + [21]: extensions/permalinks.md + [22]: extensions/footnotes.md + [23]: extensions/pymdown.md ## Full example From 6f324afb3792dbb7aa0376caef664ca0845f18c3 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 14 Jan 2017 13:43:19 +0100 Subject: [PATCH 2/3] Put choco under general installation procedures --- docs/getting-started.md | 35 ++++++++++++++++++----------------- mkdocs.yml | 2 +- 2 files changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index 81b9dda76..fdc7d7b37 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -41,7 +41,7 @@ pip install pymdown-extensions ### Installing Material -#### by using pip +#### using pip Material can be installed with `pip`: @@ -63,7 +63,23 @@ pip install mkdocs-material to a self-contained solution by installing Python with Homebrew. This should eliminate a lot of problems you may be having with `pip`. -#### by cloning from GitHub +#### using choco + +If you're on Windows you can use [Chocolatey][5] to install [Material][6]: + +``` dos +choco install mkdocs-material +``` + +This will also install all required dependencies like [Python][7] and +[MkDocs][8]. + + [5]: https://chocolatey.org + [6]: https://chocolatey.org/packages/mkdocs-material + [8]: https://chocolatey.org/packages/python + [7]: https://chocolatey.org/packages/mkdocs + +#### cloning from GitHub Material can also be used without a system-wide installation by cloning the repository into a subfolder of your project's root directory: @@ -76,21 +92,6 @@ 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`. -### Installing using Chocolatey - -If you're on Windows you can use [Chocolatey][5] to install [mkdocs-material][6]: - -``` dos -choco install mkdocs-material -``` - -Installing [mkdocs-material][6] will take care of installing all required dependencies like [mkdocs][7] and [Python][8]. - - [5]: https://chocolatey.org - [6]: https://chocolatey.org/packages/mkdocs-material - [7]: https://chocolatey.org/packages/mkdocs - [8]: https://chocolatey.org/packages/Python - ## Usage In order to enable the Material theme just add one of the following lines to diff --git a/mkdocs.yml b/mkdocs.yml index e60f188ad..33ca68bb2 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -29,7 +29,7 @@ repo_name: squidfunk/mkdocs-material repo_url: https://github.com/squidfunk/mkdocs-material # Copyright -copyright: 'Copyright © 2016 Martin Donath' +copyright: 'Copyright © 2016-2017 Martin Donath' # Documentation and theme theme_dir: material From c0fe88004ade2b8cc6fa320260244864cc3e75fe Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sat, 14 Jan 2017 13:44:23 +0100 Subject: [PATCH 3/3] Fix link reference --- docs/getting-started.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started.md b/docs/getting-started.md index fdc7d7b37..3508438cd 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -76,8 +76,8 @@ This will also install all required dependencies like [Python][7] and [5]: https://chocolatey.org [6]: https://chocolatey.org/packages/mkdocs-material - [8]: https://chocolatey.org/packages/python - [7]: https://chocolatey.org/packages/mkdocs + [7]: https://chocolatey.org/packages/python + [8]: https://chocolatey.org/packages/mkdocs #### cloning from GitHub