ci: rename branch

.github/workflows/docs.yml

@@ -3,7 +3,7 @@ name: Deploy Docs
 on:
   push:
     branches:
-      - master
+      - main
 
 jobs:
   build-deploy:

README.md

@@ -1,19 +1,21 @@
 # MkDocs Quickstart
-> Started template for a MkDocs docs site on GH Pages - including CI
+> Starter template for a MkDocs docs site on GH Pages - including CI
 
 [![CI status](https://github.com/MichaelCurrin/mkdocs-quickstart/workflows/Deploy%20Docs/badge.svg)](https://github.com/MichaelCurrin/mkdocs-quickstart/actions)
 [![GitHub tag](https://img.shields.io/github/tag/MichaelCurrin/mkdocs-quickstart?include_prereleases=&sort=semver)](https://github.com/MichaelCurrin/mkdocs-quickstart/releases/)
 [![License](https://img.shields.io/badge/License-MIT-blue)](#license)
 
 [![Made with Python](https://img.shields.io/badge/Python->%3D3.6-blue?logo=python&logoColor=white)](https://python.org)
-[![Made with MkDocs](https://img.shields.io/badge/MkDocs-~=1.1-blue)](https://www.mkdocs.org/)
+[![Made with MkDocs](https://img.shields.io/badge/mkdocs-1-blue)](https://www.mkdocs.org/)
 [![CI - GH Actions](https://img.shields.io/badge/CI-GH_Actions-blue?logo=github-actions&logoColor=white)](https://github.com/features/actions)
 
 A template, live demo and tutorial for how to set up a MkDocs docs site on GH Pages. Using GitHub Actions to automated deploys.
 
+MkDocs is a Python package when turns your docs directory and YAML config into a static website. No Python coding needed. Just Markdown and some light configuration including a theme choice and menu.
 
 <!-- TODO When creating a new project copied from this template, you can delete this README.md and start over -->
 
+
 ## Purpose
 
 This project provides low-code content-focused way to set up and host a markdown-based documentation site, with a professional look and themes. Built with MkDocs - a Python package which is a static site generator specializing in documentation.
@@ -23,9 +25,21 @@ A GitHub Actions workflow is provided with this template so you can easily deplo
 
 ## Preview
 
+<div align="center">
+
 [![Sample screenshot](/sample.png)](https://michaelcurrin.github.io/mkdocs-quickstart/ "Sample screenshot")
 
-This project uses the _Read the Docs_ theme, as shown above. It comes with MkDocs so you don't need to add to your dependencies. But you can switch to the MkDocs default or install and configure another theme.
+</div>
+
+This template project is configured to use the _Read the Docs_ theme, as shown above. 
+
+Thus looks like the the [Read The Docs][] site, but without having to have to overhead of using Sphinx.
+
+[Read The Docs]: https://docs.readthedocs.io
+
+This Read the Docs theme for MkDocs comes with MkDocs already, so you don't need to add to your dependencies. But you can switch to the MkDocs default or install and configure another theme.
+
+You can switch to the default theme or install some others, based on the instructions in this template project.
 
 
 ## How to use this project

docs/Makefile

@@ -10,9 +10,13 @@ h help:
 
 
 install:
-	pip install --upgrade pip
+	pip install pip --upgrade
 	pip install -r requirements.txt
 
+upgrade:
+	pip install pip --upgrade
+	pip install -r requirements.txt --upgrade
+
 
 s serve:
 	mkdocs serve --strict

docs/docs/tutorial/deploy.md

@@ -13,6 +13,8 @@ Follow one of the approaches below:
 - [Run deploy command](#run-deploy-command) - Run a MkDocs CLI command locally to deploy.
 - [Deploy with GitHub Actions](#deploy-with-github-actions) - Use the project's CI workflow in the cloud to build and deploy to GH Pages on commits pushed to master.
 
+Then go to your repo's _Settings_ and _Pages_ then enable _GitHub Pages_ on the `gh-pages` branch's root.
+
 _Note this is for a Project Page on a subpath, you will have to make adjustments to the command below if you want an Organization or User Page on the root path._
 
 ### Run deploy command
@@ -35,14 +37,13 @@ $ mkdocs gh-deploy --strict --force
 That will do the following:
 
 1. Clean and build to `site` directory.
-2. Push to `gh-pages` branch. Note: You must _not_ edit this branch directly.
+2. Force push to `gh-pages` branch, overwriting any changes which were pushed from another build.
-3. Enable GitHub Pages if it was not yet enabled
 
-Then go to your repo on GitHub, look at the *environment* tab and click _View deployment_.
+Then go to your repo on GitHub, look at the *Environment* tab.
 
-e.g.
+When it is done building, click _View deployment_ to see your site.
 
-- [michaelcurrin.github.io/mkdocs-quickstart/](https://michaelcurrin.github.io/mkdocs-quickstart/)
+e.g. [michaelcurrin.github.io/mkdocs-quickstart/](https://michaelcurrin.github.io/mkdocs-quickstart/)
 
 See deploy options in the help:
 
@@ -56,11 +57,3 @@ $ mkdocs gh-deploy --help
 When you make changes to your docs config or the docs directory, especially editing on GitHub directly, it's often useful to have the docs site build and deploy automatically in a remote environment. This is provided for free by GitHub.
 
 See the [docs.yml](https://github.com/MichaelCurrin/mkdocs-quickstart/blob/master/.github/workflows/docs.yml) workflow provided with this project. You don't have to change anything there. The token will be generated for you by GitHub Actions.
-
-### Mixing deploy approaches
-
-Warning - even though using the `--force` flag to force push, I _still_ got an error on the CI that I need to pull in changes first. This failing state was _caused_ by doing manual local deploy.
-
-Deleting the branch and rerunning the CI fixed it.
-
-But otherwise, avoid mixing the deploy command locally and other times doing it with CI. Maybe MkDocs needs to make a fix on the force flag.

docs/docs/tutorial/installation.md

@@ -5,6 +5,7 @@
 ## Requirements
 
 - [Python 3](https://www.python.org/)
+- [Make](https://www.gnu.org/software/make/) - standard on macOS and Linux but can be installed on Windows too.
 
 
 ## Install system dependencies
@@ -35,7 +36,7 @@ $ cd mkdocs-quickstart
 
 For more info, see the [Installation](https://www.mkdocs.org/#installation) page on the MkDocs site.
 
-### Use a virtual environment
+### Install in a virtual environment
 
 Create a virtual environment at the project root - this is used to isolate project packages from the global packages.
 
@@ -49,23 +50,25 @@ Activate the environment.
 $ source venv/bin/activate
 ```
 
-Install `mkdocs` - this is covered in the project dependencies file.
+Install `mkdocs` - this is covered in the project requirements file.
 
 ```sh
 $ cd docs
-$ pip install -r requirements.txt
+$ make install
 ```
 
+Note - `mkdocs` 1.2 causes a break on force pushes, so this is excluded in the requirements. See issue [#2447](https://github.com/mkdocs/mkdocs/issues/2447).
+
 ### Install globally
 
-If you prefer to install MkDocs once and reuse it across projects, then you can install it globally.
+If you prefer to install MkDocs once and reuse it across projects, then you can install it globally instead.
 
 MkDocs is available using package managers like `apt-get`, `homebrew` and `yum`.
 
-Or you can install like this.
+Or you can install like this:
 
 ```sh
-python3 -m pip install mkdocs
+$ python3 -m pip install mkdocs
 ```
 
 If you get prompted for `sudo` use, then cancel and run again with `-U` flag for user-level install.

docs/docs/tutorial/usage.md

@@ -1,7 +1,7 @@
 # Usage
 > Build and preview a site locally
 
-Make sure to run all commands from the `docs` directory.
+Make sure to run all commands from the `docs` directory, as that is where `Makefile` is.
 
 ```sh
 $ cd docs
@@ -14,21 +14,13 @@ $ cd docs
 $ make help
 ```
 ```
-.PHONY: docs
-
 default: install
-
+all: install build
-
 h help:
-
-
 install:
-
+upgrade:
-
 s serve:
-
 b build:
-
 d deploy:
 ```
 
@@ -38,13 +30,7 @@ d deploy:
 This will build the docs in memory (not to disk) and serve an auto-reloading server.
 
 ```sh
-$ make s
+$ make serve
-```
-
-That will use `Makefile` to run the following:
-
-```sh
-$ mkdocs serve --strict
 ```
 
 Then open in your browser:
@@ -57,11 +43,5 @@ Then open in your browser:
 Build docs site to `site` directory. This is useful for a CI flow.
 
 ```sh
-$ make b
+$ make build
-```
-
-That will use `Makefile` to run the following:
-
-```sh
-$ mkdocs build --strict
 ```

docs/requirements.txt

@@ -1 +1 @@
-mkdocs~=1.1
+mkdocs~=1.1,!=1.2