docs: Update docs

README.md

@@ -39,7 +39,7 @@ This project uses the Read the Docs theme as seen above. It comes with MkDocs so
 - Easy to configure - see the short [mkdocs.yml](/mkdocs.yml) file.
 - Use the configured theme or switch to another - no need to write HTML and CSS yourself.
 - Each theme comes with a navbar and you write YAML - Jekyll themes on GH Pages need you to write your own HTML often and each theme handles navbar its own way (sometimes not at all).
-- Uses a deploy pipeline on GH Actions to deploy a GH Pages site.
+- Uses a deploy pipeline on GH Actions to deploy a GH Pages site - the action actually runs GH Pages deploy command.
 - The static site output is SEO-friendly.
 - Built on Python but you don't need to write any Python code.
 

docs/tutorial/installation.md

@@ -30,31 +30,21 @@ For more info, see the [Installation](https://www.mkdocs.org/#installation) page
 Create a virtual environment at the project root.
 
 ```sh
-python3 -m venv venv
+$ python3 -m venv venv
 ```
 
 Activate it.
 
 ```sh
-source venv/bin/activate
+$ source venv/bin/activate
 ```
 
-Install dependencies using one of these approaches:
-
-<!-- Using `sh` for code block breaks for bullet points at least for read the docs theme. It looks like code can't go in bullet point after all.  -->
-
-Install directly.
+Install `mkdocs` from project dependencies list.
 
 ```sh
-pip install mkdocs
+$ pip install -r requirements.txt
 ```
 
-Create a `requirements.txt` file, add `mkdocs` to it then install from the file.
-
-```sh
-echo 'mkdocs' > requirements.txt
-pip install -r requirements.txt
-```
 
 ### Install globally
 

docs/tutorial/setup-project.md

@@ -83,9 +83,7 @@ site/
 venv
 ```
 
-### Config
-
-#### Sample navbar
+### Navbar
 
 ```yaml
 nav:
@@ -93,19 +91,29 @@ nav:
     - About: about.md
 ```
 
-#### Sample theme
+### Themes
+
+#### Builtin
+
+Use a builtin theme that comes with MkDocs.
+
+The default.
 
-Use a builtin theme.
 ```yaml
 theme: mkdocs
 ```
-Or
+
+Using ReadTheDocs theme and alternative config syntax.
+
 ```yaml
-theme: readthedocs
+theme:
+  name: readthedocs
 ```
 
 Find more [supported themes](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes). If it doesn't immediately, you'll have to use `pip` to install it and add to a `requirements.txt` file.
 
+#### ReadTheDocs Dropdown theme
+
 See below using [mkdocs-rtd-dropdown](https://github.com/cjsheets/mkdocs-rtd-dropdown).
 
 `requirements.txt`
@@ -118,3 +126,18 @@ mkdocs-rtd-dropdown
 theme:
   name: 'rtd-dropdown'
 ```
+
+### Material for MkdDocs theme
+
+See the [MkDocs for Material](https://squidfunk.github.io/mkdocs-material/) homepage. See the Setup page for config options.
+
+`requirements.txt`
+```
+mkdocs-material-extensions>=1.0
+```
+
+`mkdocs.yml`
+```yaml
+theme:
+  name: 'material'
+```

docs/tutorial/usage.md

@@ -9,24 +9,30 @@ _Note: If using VS Code, you can use the command palette instead to run the conf
 This will build the docs in memory (not to disk) and serve an auto-reloading server.
 
 ```sh
-mkdocs serve
+$ make serve
 ```
 
-Open URL:
+That will use `make` to run the following:
+
+```sh
+$ mkdocs serve --strict
+```
+
+Then open in your browser:
 
 - [localhost:8000](http://localhost:8000)
 
 
 ## Build docs
 
-Build docs site to `site` directory. Useful for production build or simulating that locally.
+Build docs site to `site` directory. This is useful for a CI flow.
 
 ```sh
-mkdocs build
+$ make docs
 ```
 
-Add this flag to build in strict mode.
+That will use `make` to run the following:
 
 ```sh
-mkdocs build --strict
+$ mkdocs build --strict
 ```