ci: rename branch

.github/workflows/docs.yml

@@ -1,22 +1,24 @@
-name: Deploy docs
+name: Deploy Docs
 
 on:
   push:
     branches:
-      - master
+      - main
 
 jobs:
   build-deploy:
-    name: Build and deploy to GH Pages
+    name: Build and deploy docs
+
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - name: Checkout 🛎️
+        uses: actions/checkout@v2
 
-      - name: Set up Python 3.x
+      - name: Set up Python 3 ⚙️ 🐍
         uses: actions/setup-python@v2
 
-      - name: Cache dependencies
+      - name: Cache dependencies 💾
         uses: actions/cache@v2
         with:
           path: ~/.cache/pip
@@ -25,8 +27,10 @@ jobs:
             ${{ runner.os }}-pip-
             ${{ runner.os }}-
 
-      - name: Install dependencies
+      - name: Install dependencies 🔧
-        run: cd docs && make install
+        working-directory: docs
+        run: make install
 
-      - name: Build and deploy
+      - name: Build and deploy to GitHub Pages 🏗️ 🚀
-        run: cd docs && make deploy
+        working-directory: docs
+        run: make deploy

.gitignore

@@ -1,3 +1,3 @@
-site/
-
 venv
+
+site/

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 MichaelCurrin
+Copyright (c) 2020 - 2021 MichaelCurrin
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,33 +1,54 @@
 # MkDocs Quickstart
-> A template, live demo and tutorial for how to setup a MkDocs docs site on GitHub Pages
+> 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)
+[![CI status](https://github.com/MichaelCurrin/mkdocs-quickstart/workflows/Deploy%20Docs/badge.svg)](https://github.com/MichaelCurrin/mkdocs-quickstart/actions)
-[![Made with MkDocs](https://img.shields.io/badge/Made_with-MkDocs-blue)](https://www.mkdocs.org/)
+[![GitHub tag](https://img.shields.io/github/tag/MichaelCurrin/mkdocs-quickstart?include_prereleases=&sort=semver)](https://github.com/MichaelCurrin/mkdocs-quickstart/releases/)
-[![Made with GH Actions](https://img.shields.io/badge/Made_with-GH_Actions-blue?logo=github-actions&logoColor=white)](https://github.com/features/actions)
+[![License](https://img.shields.io/badge/License-MIT-blue)](#license)
-[![GitHub tag](https://img.shields.io/github/tag/MichaelCurrin/mkdocs-quickstart.svg)](https://GitHub.com/MichaelCurrin/mkdocs-quickstart/tags/)
-[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](#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-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
 
-A low-code way to setup and host a markdown-based docs site with a professional look.
+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.
+
+A GitHub Actions workflow is provided with this template so you can easily deploy to GitHub Pages too.
 
 
 ## Preview
 
-[![Sample screenshot](/sample.png)](https://michaelcurrin.github.io/mkdocs-quickstart/)
+<div align="center">
 
-This project uses the _Read the Docs_ theme as seen 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.
+[![Sample screenshot](/sample.png)](https://michaelcurrin.github.io/mkdocs-quickstart/ "Sample screenshot")
+
+</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
 
 <div align="center">
 
-[![GH Pages](https://img.shields.io/badge/GitHub_Pages-MkDocs_Quickstart-green?style=for-the-badge)](https://michaelcurrin.github.io/mkdocs-quickstart/)
+[![GH Pages](https://img.shields.io/badge/View_site-MkDocs_Quickstart-blue?style=for-the-badge)](https://michaelcurrin.github.io/mkdocs-quickstart/)
-[![Use this template](https://img.shields.io/badge/Use_this_template-2ea44f?style=for-the-badge&logo=github)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
+
+[![Use this template](https://img.shields.io/badge/Generate-Use_this_template-2ea44f?style=for-the-badge)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
 
 </div>
 
@@ -60,9 +81,17 @@ Change the content and theme to suit your needs, based on the tutorial site or t
 To isolate the MkDocs flow from the rest of your code, you can put the configs and the `docs` folder of content inside the `docs` directory. That means you end up having `docs/docs`, which is okay. Just make sure you select the `/docs` directory when setting up GH Pages.
 
 
-## Why use MkDocs?
+## About MkDocs
 
-If you're new to MkDocs, look at the tutorial added on this project's site, otherwise go to the MkDocs documentation.
+### Resources
+
+- Homepage: [mkdocs.org](http://www.mkdocs.org/)
+- Repo: [![mkdocs - mkdocs](https://img.shields.io/static/v1?label=mkdocs&message=mkdocs&color=blue&logo=github)](https://github.com/mkdocs/mkdocs) [![stars - mkdocs](https://img.shields.io/github/stars/mkdocs/mkdocs?style=social)](https://github.com/mkdocs/mkdocs)
+- PyPI package: [mkdocs](https://pypi.org/project/mkdocs/)
+
+### Why MkDocs?
+
+If you're new to MkDocs, look at the tutorial added on this project's site, otherwise go to the MkDocs homepage for documentation.
 
 This project provides a way to write your docs in markdown and build a professional-looking docs site on top of it, without having to write HTML or CSS code and using a selection of themes. While MkDocs CLI has functionality to deploy from a local command-line, this project makes deploying effortless by using GitHub Actions to build and deploy the site to a `gh-pages` branch and GitHub Pages to serve the site.
 
@@ -84,4 +113,4 @@ Or submit a code change:
 
 ## License
 
-Released under [MIT](/LICENSE).
+Released under [MIT](/LICENSE) by [@MichaelCurrin](https://github.com/MichaelCurrin).

docs/Makefile

@@ -2,19 +2,26 @@
 
 default: install
 
+all: install build
+
 
 h help:
-	@egrep '(^\S)|(^$$)|\s+@echo' Makefile
+	@grep '^[a-z]' Makefile
 
 
 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
 
+
 b build:
 	mkdocs build --strict
 

docs/docs/about-mkdocs.md

@@ -17,7 +17,7 @@ If you are new to markdown, see the [Getting Started](https://www.markdownguide.
 - [mkdocs.org](https://www.mkdocs.org) homepage
 - [mkdocs/mkdocs ![Repo stars](https://img.shields.io/github/stars/mkdocs/mkdocs?style=social)](https://github.com/mkdocs/mkdocs)
 - [MkDocs Wiki](https://github.com/mkdocs/mkdocs/wiki) - covering themes, plugins, recipes and more.
-- [Release notes](https://www.mkdocs.org/about/release-notes/)
+- [Release notes](https://www.mkdocs.org/about/release-notes/) for MkDocs.
 
 
 ## Reasons to use MkDocs

docs/docs/index.md

@@ -1,10 +1,9 @@
 # MkDocs Quickstart
-> A template, live demo and tutorial for how to setup a MkDocs docs site on GitHub Pages
+>  Started template for a MkDocs docs site on GH Pages - including CI 
 
 [![Repo stars](https://img.shields.io/github/stars/MichaelCurrin/mkdocs-quickstart?style=social)](https://github.com/MichaelCurrin/mkdocs-quickstart)
 
-
+Use the MkDocs (_make docs_) tool to create build a docs site around markdown docs.
-Use the MkDocs (make docs) tool to create build a docs site around markdown docs.
 
 Follow the tutorial to add an existing project or create a project from scratch. The result will look like this project.
 

docs/docs/tutorial/deploy.md

@@ -11,10 +11,11 @@ See [Deploying Your Docs](https://www.mkdocs.org/user-guide/deploying-your-docs/
 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 workflow to build and deploy to GH Pages on commits pushed to master.
+- [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 and not an Organization or User Page._
+_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
 > Run a MkDocs CLI command locally to deploy
@@ -30,23 +31,21 @@ $ make d
 That will use `Makefile` to run the following:
 
 ```sh
-$ mkdocs gh-deploy --strict
+$ 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, see 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:
-See deploy options:
 
 ```sh
 $ mkdocs gh-deploy --help

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
@@ -12,18 +13,15 @@
 <script src="https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js"></script>
 
 
-## Setup repo
+## Set up a new repo
 
-Choose or setup a MkDocs project.
+Follow the Tutorial page to set up a project from scratch.
 
-
+Or click this create your own copy of the repo.
-Follow the tutorial page to setup a project.
-
-Or click the button on this repo to create your own copy of the repo.
 
 [![Use this template](https://img.shields.io/badge/Use_this_template-2ea44f?style=for-the-badge&logo=github)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
 
-Then clone it.
+Then clone your repo.
 
 e.g.
 
@@ -38,36 +36,39 @@ $ 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.
+Create a virtual environment at the project root - this is used to isolate project packages from the global packages.
 
 ```sh
 $ python3 -m venv venv
 ```
 
-Activate it.
+Activate the environment.
 
 ```sh
 $ source venv/bin/activate
 ```
 
-Install `mkdocs` from the project dependencies list.
+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`.
 
-You can install like this too:
+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/setup-project.md

@@ -11,15 +11,23 @@ Use one of the approaches below:
 - Create a quickstart project with the `new` command covered in [Create a starter site](#create-a-starter-site).
 - Follow the extended guide to create a [Set up up docs site](#setup-a-docs-site) by hand.
 
-
 ### Basic structure
 
 This is the simplest MkDocs site you can make:
 
 - `docs/`
     - `index.md` - Homepage in the `docs` directory (by default).
-- `mkdocs.yml` - Config at the root.
+- `mkdocs.yml`
+    - Config at the root - control appearance and navigation of your site.
+    - See this project's [docs/mkdocs.yml](https://github.com/MichaelCurrin/mkdocs-quickstart/blob/master/docs/mkdocs.yml) file on GitHub.
 
+Notes on fields for the config:
+
+- `site_name` - title of your site.
+- `site_description` - used as a description for SEO and you could use it somewhere in your template.
+- `site_url` - now a _required_ field when running a deploy. Include the subpath on the domain. If your site is not ready to be hosted, set this field to an empty string.
+- `repo_url` - for _Edit on GitHub_ button. See [docs](https://www.mkdocs.org/user-guide/configuration/#repo_url).
+- `edit_uri` - defaults to `edit/master/docs/`, which includes `docs` directory of markdown files inside your repo root. But, if the site's root is in an outer `docs` directory, then you need to _also_ add that, so paths do not break. e.g. `edit/master/docs/docs`. See [docs](https://www.mkdocs.org/user-guide/configuration/#edit_uri)
 
 ### Requirements file
 
@@ -27,7 +35,6 @@ A requirements file is optional but it can make it easier to manage dependencies
 
 If you want to add, then include `requirements.txt` at the root. If your project is already a Python project, you might prefer to add `mkdocs` in `requirements-dev.txt` or at `docs/requirements.txt` to keep it isolated.This file should have `mkdocs` in it and also any themes if needed.
 
-
 ### Create a starter site
 
 Run this command to create a starter site. This make the steps below go quicker.
@@ -50,7 +57,7 @@ _Tip: Optionally use the `new` command covered above to setup the config and ind
         - Use placeholder content if you want to move on and then come back to expand them.
         - If you have any existing markdown docs, these will work too.
 2. Set up config.
-    1. Create `mkdocs.yml` at project root.
+    1. Create `mkdocs.yml` at the project root.
     2. Set up a navbar there.
     3. Choose a theme.
 3. Create a favicon (optional).
@@ -63,7 +70,7 @@ You project should now look this this:
 
 - `docs/`
     - `index.md`
-    - Other pages...
+    - More pages...
 - `mkdocs.yml`
 - `.gitignore`
 - `venv`
@@ -75,7 +82,6 @@ You project should now look this this:
 ### Ignore file
 
 `.gitignore`
-
 ```
 site/
 
@@ -84,6 +90,7 @@ venv
 
 ### Navbar
 
+`mkdocs.yml`
 ```yaml
 nav:
     - Home: index.md
@@ -115,12 +122,13 @@ Find more [supported themes](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
 
 See below using [mkdocs-rtd-dropdown](https://github.com/cjsheets/mkdocs-rtd-dropdown).
 
-`requirements.txt`
+`requirements.txt`:
 ```
 mkdocs-rtd-dropdown
 ```
 
-`mkdocs.yml`
+`mkdocs.yml`:
+
 ```yaml
 theme:
   name: 'rtd-dropdown'
@@ -130,12 +138,12 @@ theme:
 
 See the [MkDocs for Material](https://squidfunk.github.io/mkdocs-material/) homepage. See the Set up page for config options.
 
-`requirements.txt`
+`requirements.txt`:
 ```
 mkdocs-material-extensions>=1.0
 ```
 
-`mkdocs.yml`
+`mkdocs.yml`:
 ```yaml
 theme:
   name: 'material'

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/mkdocs.yml

@@ -1,6 +1,15 @@
+### Site metadata ###
+
 site_name: MkDocs Quickstart
-# SEO description.
+site_description: Starter template for a MkDocs docs site on GH Pages - including CI
-site_description: "A concise recipe for setting up a MkDocs docs site on GitHub Pages"
+site_url: https://michaelcurrin.github.io/mkdocs-quickstart/
+
+repo_url: https://github.com/MichaelCurrin/mkdocs-quickstart
+edit_uri: edit/master/docs/docs
+
+### Build settings ###
+
+theme: readthedocs
 
 nav:
   - Home: index.md
@@ -12,8 +21,3 @@ nav:
       - Advanced: tutorial/advanced.md
       - Usage: tutorial/usage.md
       - Deploy: tutorial/deploy.md
-
-theme: readthedocs
-
-# Target for Edit in GitHub button.
-repo_url: https://github.com/MichaelCurrin/mkdocs-quickstart/

docs/requirements.txt

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