Improved customization guide

docs/customization.md

@@ -5,14 +5,14 @@ template: overrides/main.html
 # Customization
 
 Project documentation is as diverse as the projects themselves and Material for
-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
+MkDocs is a great starting point for making it look beautiful. However, as you
+write your documentation, you may reach a point where small adjustments are
 necessary to preserve your brand's style.
 
 ## Adding assets
 
 [MkDocs][1] provides several ways to customize a theme. In order to make a few
-tweaks to an existing theme, you can just add your stylesheets and JavaScript
+tweaks to Material for MkDocs, you can just add your stylesheets and JavaScript
 files to the `docs` directory.
 
   [1]: https://www.mkdocs.org
@@ -23,9 +23,12 @@ If you want to tweak some colors or change the spacing of certain elements,
 you can do this in a separate stylesheet. The easiest way is by creating a
 new stylesheet file in the `docs` directory:
 
-```
-mkdir docs/stylesheets
-touch docs/stylesheets/extra.css
+``` sh
+.
+├─ docs/
+│  └─ stylesheets/
+│     └─ extra.css
+└─ mkdocs.yml
 ```
 
 Then, add the following line to `mkdocs.yml`:
@@ -46,9 +49,12 @@ The same is true for additional JavaScript. If you want to integrate another
 syntax highlighter or add some custom logic to your theme, create a new
 JavaScript file in the `docs` directory:
 
-```
-mkdir docs/javascripts
-touch docs/javascripts/extra.js
+``` sh
+.
+├─ docs/
+│  └─ javascripts/
+│     └─ extra.js
+└─ mkdocs.yml
 ```
 
 Then, add the following line to `mkdocs.yml`:
@@ -64,16 +70,17 @@ Further assistance can be found in the [MkDocs documentation][3].
 
 ## Extending the theme
 
-If you want to alter the HTML source (e.g. add or remove some part), you can
+If you want to alter the HTML source (e.g. add or remove some parts), you can
 extend the theme. MkDocs supports [theme extension][4], an easy way to override
-parts of a theme without forking and changing the main theme.
+parts of Material for MkDocs without forking from git. This ensures that you
+can update to the latest version more easily.
 
   [4]: https://www.mkdocs.org/user-guide/styling-your-docs/#using-the-theme-custom_dir
 
 ### Setup and theme structure
 
-Reference the original theme as usual in `mkdocs.yml`, and create a new folder
-for `overrides` which you reference using `custom_dir`:
+Enable Material for MkDocs as usual in `mkdocs.yml`, and create a new folder
+for `overrides` which you then reference using the `custom_dir` key:
 
 ``` yaml
 theme:
@@ -130,17 +137,37 @@ The directory layout of the theme is as follows:
 
 ### Overriding partials
 
-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
-`overrides` directory. MkDocs will now use the new partial when rendering the
-theme. This can be done with any file.
+In order to override a partial, we can replace it with a file of the same name
+and location in the `overrides` directory. For example. to replace the original
+`footer.html`, create a `footer.html` file in the `overrides/partials`
+directory:
+
+``` sh
+.
+├─ overrides/
+│  └─ partials/
+│     └─ footer.html
+└─ mkdocs.yml
+```
+
+MkDocs will now use the new partial when rendering the theme. This can be done
+with any file.
 
 ### Overriding blocks
 
-Besides overriding partials, it's also possible to override (and extend) so
-called _blocks_, which are defined inside the templates and wrap specific
-features. To override a block, create a `main.html` inside the `overrides`
-directory and define the block, e.g.:
+Besides overriding partials, it's also possible to override (and extend)
+_template blocks_, which are defined inside the templates and wrap specific
+features. To override a block, create a `main.html` file inside the `overrides`
+directory:
+
+``` sh
+.
+├─ overrides/
+│  └─ main.html
+└─ mkdocs.yml
+```
+
+Then, e.g. to override the site title, add the following line to `main.html`:
 
 ``` html
 {% extends "base.html" %}

mkdocs.yml

@@ -164,7 +164,6 @@ nav:
     - Adding social links: setup/adding-social-links.md
     - Adding a git repository: setup/adding-a-git-repository.md
     - Adding a comment system: setup/adding-a-comment-system.md
-    #- Adding an announcement bar: setup/adding-an-announcement-bar.md
     #- Adding a landing page: setup/adding-a-landing-page.md
   - Reference:
     - Admonitions: reference/admonitions.md