Reworked customization documentation

CHANGELOG

@@ -651,7 +651,7 @@ mkdocs-material-1.0.0 (2017-01-13)
   * Rewrite of the complete typographical system
   * Rewrite of Gulp asset pipeline in ES6 and separation of tasks
   * Removed Bower as a dependency in favor of NPM
-  * Removed custom icon build in favor of the Material Design iconset
+  * Removed custom icon build in favor of the Material Design icon set
   * Removed _blank targets on links due to vulnerability: http://bit.ly/1Mk2Rtw
   * Removed unversioned assets from build directory
   * Restructured templates into base templates and partials

docs/customization.md

@@ -2,10 +2,10 @@
 
 ## A great starting point
 
-Project documentation is as diverse as the projects themselves and the Material
+Project documentation is as diverse as the projects themselves and Material for
-theme is a good starting point for making it look great. However, as you write
+MkDocs is a good starting point for making it look great. However, as you write
 your documentation, you may reach a point where some small adjustments are
-necessary to preserve the desired style.
+necessary to preserve your brand's style.
 
 ## Adding assets
 
@@ -35,7 +35,7 @@ extra_css:
 
 Spin up the development server with `mkdocs serve` and start typing your
 changes in your additional stylesheet file – you can see them instantly after
-saving, as the MkDocs development server implements live reloading.
+saving, as the MkDocs development server supports live reloading.
 
 ### Additional JavaScript
 
@@ -62,35 +62,34 @@ Further assistance can be found in the [MkDocs documentation][2].
 ## Extending the theme
 
 If you want to alter the HTML source (e.g. add or remove some part), you can
-extend the theme. From version 0.16 on MkDocs implements [theme extension][3],
+extend the theme. MkDocs supports [theme extension][3], an easy way to override
-an easy way to override parts of a theme without forking and changing the
+parts of a theme without forking and changing the main theme.
-main theme.
 
   [3]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
 
 ### Setup and theme structure
 
 Reference the Material theme as usual in your `mkdocs.yml`, and create a
-new folder for overrides, e.g. `theme`, which you reference using `custom_dir`:
+new folder for `overrides` which you reference using `custom_dir`:
 
 ``` yaml
 theme:
   name: material
-  custom_dir: theme
+  custom_dir: overrides
 ```
 
 !!! warning "Theme extension prerequisites"
 
     As the `custom_dir` variable is used for the theme extension process, the
-    Material theme needs to be installed via `pip` and referenced with the
+    Material for MkDocs needs to be installed via `pip` and referenced with the
     `name` parameter in your `mkdocs.yml`.
 
-The structure in the theme directory must mirror the directory structure of the
+The structure in the `overrides` directory must mirror the directory structure
-original theme, as any file in the theme directory will replace the file with
+of the original theme, as any file in the `overrides` directory will replace the
-the same name which is part of the original theme. Besides, further assets
+file with the same name which is part of the original theme. Besides, further
-may also be put in the theme directory.
+assets may also be put in the `overrides` directory.
 
-The directory layout of the Material theme is as follows:
+The directory layout of the theme is as follows:
 
 ``` sh
 .
@@ -109,6 +108,8 @@ The directory layout of the Material theme is as follows:
 │  ├─ nav.html                         # Main navigation
 │  ├─ search.html                      # Search box
 │  ├─ social.html                      # Social links
+│  ├─ source-date.html                 # Last updated date
+│  ├─ source-link.html                 # Link to source file
 │  ├─ source.html                      # Repository information
 │  ├─ tabs-item.html                   # Tabs navigation item
 │  ├─ tabs.html                        # Tabs navigation
@@ -123,15 +124,15 @@ The directory layout of the Material theme is as follows:
 
 In order to override the footer, we can replace the `footer.html` partial with
 our own partial. To do this, create the file `partials/footer.html` in the
-theme directory. MkDocs will now use the new partial when rendering the theme.
+`overrides` directory. MkDocs will now use the new partial when rendering the
-This can be done with any file.
+theme. This can be done with any file.
 
 ### Overriding template blocks
 
-Besides overriding partials, one can also override so called template blocks,
+Besides overriding partials, one can also override so called *template blocks*,
-which are defined inside the Material theme and wrap specific features. To
+which are defined inside the templates and wrap specific features. To override a
-override a template block, create a `main.html` inside the theme directory and
+template block, create a `main.html` inside the `overrides` directory and define
-define the block, e.g.:
+the block, e.g.:
 
 ``` jinja
 {% extends "base.html" %}
@@ -141,11 +142,13 @@ define the block, e.g.:
 {% endblock %}
 ```
 
-The Material theme provides the following template blocks:
+Material for MkDocs provides the following template blocks:
 
 | Block name   | Wrapped contents                                |
 | ------------ | ----------------------------------------------- |
 | `analytics`  | Wraps the Google Analytics integration          |
+| `announce`   | Wraps the Announcement bar                      |
+| `config`     | Wraps the JavaScript application config         |
 | `content`    | Wraps the main content                          |
 | `disqus`     | Wraps the disqus integration                    |
 | `extrahead`  | Empty block to define additional meta tags      |
@@ -168,19 +171,19 @@ For more on this topic refer to the [MkDocs documentation][4]
 
 ## Theme development
 
-The Material theme uses [Webpack][5] as a build tool to leverage modern web
+Material for MkDocs uses [Webpack][5] as a build tool to leverage modern web
-technologies like [Babel][6] and [SASS][7]. If you want to make more fundamental
+technologies like [TypeScript][6] and [SASS][7]. If you want to make more
-changes, it may be necessary to make the adjustments directly in the source of
+fundamental changes, it may be necessary to make the adjustments directly in
-the Material theme and recompile it. This is fairly easy.
+the source of the theme and recompile it. This is fairly easy.
 
   [5]: https://webpack.js.org/
-  [6]: https://babeljs.io
+  [6]: https://www.typescriptlang.org/
   [7]: https://sass-lang.com
 
 ### Environment setup
 
-In order to start development on the Material theme, a [Node.js][8] version of
+In order to start development on Material for MkDocs, a [Node.js][8] version of
-at least 8 is required. First, clone the repository:
+at least 12 is required. First, clone the repository:
 
 ``` sh
 git clone https://github.com/squidfunk/mkdocs-material
@@ -193,31 +196,20 @@ cd mkdocs-material
 pip install -r requirements.txt
 npm install
 ```
-If you're on Windows, you may also need to install [GNU Make][9]
 
   [8]: https://nodejs.org
-  [9]: http://gnuwin32.sourceforge.net/packages/make.htm
 
 ### Development mode
 
 The development server can be started with:
 
 ``` sh
-npm run watch
+npm start
 ```
 
 This will also start the MkDocs development server which will monitor changes
 on assets, templates and documentation. Point your browser to
-[localhost:8000][10] and you should see this documentation in front of you.
+[localhost:8000][190] and you should see this documentation in front of you.
-
-For example, changing the color palette is as simple as changing the
-`$md-color-primary` and `$md-color-accent` variables in
-`src/assets/stylesheets/_config.scss`:
-
-``` css
-$md-color-primary: $clr-red-400;
-$md-color-accent:  $clr-teal-a700;
-```
 
 !!! warning "Automatically generated files"
 
@@ -225,7 +217,7 @@ $md-color-accent:  $clr-teal-a700;
     directory are automatically generated from the `src` directory and will be
     overridden when the theme is built.
 
-  [10]: http://localhost:8000
+  [9]: http://localhost:8000
 
 ### Build process
 
@@ -236,9 +228,9 @@ npm run build
 ```
 
 This triggers the production-level compilation and minification of all
-stylesheets and JavaScript sources. When the command exits, the final theme is
+stylesheets and JavaScript sources. When the command exits, the final files are
 located in the `material` directory. Add the `theme_dir` variable pointing to
 the aforementioned directory in your original `mkdocs.yml`.
 
 Now you can run `mkdocs build` and you should see your documentation with your
-changes to the original Material theme.
+changes to the original theme.

docs/getting-started.md

@@ -331,11 +331,48 @@ theme:
 
 If the colors are set with these configuration options, an additional CSS file
 that includes the hues of the color palette is automatically included and linked
-from the template. If you want to define a custom color (e.g. your brand color),
+from the template.
-see the [customization guide][13].
+
+??? tip "Custom colors with CSS variables"
+
+    Material for MkDocs defines all colors as CSS variables. If you want to
+    customize the colors beyond the palette (e.g. to use your brand's colors),
+    you can add an [additional stylesheet][13] and override the defaults:
+
+    ``` css
+    :root {
+
+      /* Default color shades */
+      --md-default-fg-color:               ...;
+      --md-default-fg-color--light:        ...;
+      --md-default-fg-color--lighter:      ...;
+      --md-default-fg-color--lightest:     ...;
+      --md-default-bg-color:               ...;
+      --md-default-bg-color--light:        ...;
+      --md-default-bg-color--lighter:      ...;
+      --md-default-bg-color--lightest:     ...;
+
+      /* Primary color shades */
+      --md-primary-fg-color:               ...;
+      --md-primary-fg-color--light:        ...;
+      --md-primary-fg-color--dark:         ...;
+      --md-primary-bg-color:               ...;
+      --md-primary-bg-color--light:        ...;
+
+      /* Accent color shades */
+      --md-accent-fg-color:                ...;
+      --md-accent-fg-color--transparent:   ...;
+      --md-accent-bg-color:                ...;
+      --md-accent-bg-color--light:         ...;
+
+      /* Code block color shades */
+      --md-code-bg-color:                  ...;
+      --md-code-fg-color:                  ...;
+    }
+    ```
 
   [12]: http://www.materialui.co/colors
-  [13]: customization.md
+  [13]: customization.md/#additional-stylesheets
 
 #### Primary color
 

docs/plugins/revision-date.md

@@ -1,9 +1,9 @@
 # Revision date
 
-The [mkdocs-git-revision-date-localized-plugin][1] is an extension that shows
+The [mkdocs-git-revision-date-localized-plugin][1] will add the date on which a
-the date on which a Markdown file was last updated in at the bottom of each
+Markdown file was last updated at the bottom of each page. The date is extracted
-page. The date is extracted at the time of the build, so `mkdocs build` must be
+at the time of the build, so `mkdocs build` must be triggered from within a git
-triggered from within a git repository.
+repository.
 
 !!! success "Bundled with the official Docker image"
 
@@ -74,5 +74,5 @@ page, e.g.:
 ---
 
 <small>
-  Last updated: 9 December, 2019
+  Last updated: 28 November, 2019
 </small>

docs/releases/changelog.md

@@ -670,7 +670,7 @@ pip show mkdocs-material
 * Rewrite of the complete typographical system
 * Rewrite of Gulp asset pipeline in ES6 and separation of tasks
 * Removed Bower as a dependency in favor of NPM
-* Removed custom icon build in favor of the Material Design iconset
+* Removed custom icon build in favor of the Material Design icon set
 * Removed `_blank` targets on links due to vulnerability: http://bit.ly/1Mk2Rtw
 * Removed unversioned assets from build directory
 * Restructured templates into base templates and partials