add site

docs/Makefile

@@ -0,0 +1,29 @@
+.PHONY: docs
+
+default: install
+
+all: install build
+
+
+h help:
+	@grep '^[a-z]' Makefile
+
+
+install:
+	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
+
+d deploy:
+	mkdocs gh-deploy --strict --force

docs/docs/about-mkdocs.md

@@ -0,0 +1,41 @@
+# About MkDocs
+
+
+## What is MkDocs?
+
+The description on the MkDocs site is:
+
+> Project documentation with Markdown.
+
+MkDocs is a Python tool that generates a static site based on content written in Markdown.
+
+If you are new to markdown, see the [Getting Started](https://www.markdownguide.org/getting-started/) page on the Markdown Guide website.
+
+
+## Resources
+
+- [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/) for MkDocs.
+
+
+## Reasons to use MkDocs
+
+- Create an elegant, modern docs site for your project.
+- Create a static site and serve from GitHub Pages easily.
+- Low-code solution
+    - No need to write HTML or learn templating syntax needed
+    - Use your existing markdown files as content.
+    - Configure with a simple YAML file.
+- Customizable.
+    - Add custom HTML if you want.
+    - Plugins available.
+    - Flexible theme choices.
+- Includes search by default.
+- Broken links to files (including from your navbar) will be detected at build time and shown as warnings.
+
+
+## Do I need to know Python?
+
+MkDocs is built in Python (like Sphinx), but you don't have to write Python code. If you set up a [Deploy](deploy) flow right, you don't even have to set it up locally, though then you can't preview.

docs/docs/index.md

@@ -0,0 +1,26 @@
+# MkDocs Quickstart
+>  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.
+
+Follow the tutorial to add an existing project or create a project from scratch. The result will look like this project.
+
+
+## Features
+> How to use this project
+
+- **Follow the tutorial instructions**
+    - Install and configure a new or existing project.
+    - Run it locally.
+    - Deploy it.
+- **Add a copy of this project to your repos**
+    - [![Use this template](https://img.shields.io/badge/Use_this_template-2ea44f?logo=github)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
+- **View the live demo**
+    - This site is hosted on GitHub Pages. See if you like it. Other themes are available - see the tutorial.
+
+
+The aim here is not be complete or explain all concepts. It is to provide a reference for common steps and choices needed when setting up a docs site, but still at a beginner-friendly level.
+
+This guide is based on the [mkdocs.org](https://www.mkdocs.org/) tutorial.

docs/docs/tutorial/advanced.md

@@ -0,0 +1,53 @@
+# Advanced
+> Beyond the basic configuration and content
+
+Once you've got the [Set up Project](setup-project.md) section, you can customize further using this guide. Or skip this and go to [Usage](usage.md).
+
+
+## Navbar nesting
+
+You can add an additional level to your navbar like this:
+
+```yaml
+nav:
+  - Home: index.md
+  - About: about.md
+  - Foo:
+      - Overview: foo/index.md
+      - Bar: foo/bar.md
+```
+
+The value can either be a string (as in the first case) or a map (as in the last case). This seems to be a YAML limitation but see also [issue #1139](https://github.com/mkdocs/mkdocs/issues/1139).
+
+
+## Add config options
+
+See [Configuration](https://www.mkdocs.org/user-guide/configuration/) page on MkDocs site for options.
+
+
+## Separate docs directory approach
+
+You can also structure your project to have the set up above nested inside a `docs` directory. This is useful you have a few other directories and you want to keep the project root clean.
+
+
+- `docs/`
+    - `docs/`
+        - `index.md`
+    - `theme/`
+        - `main.html`
+        - `nav.html`
+        - `toc.html`
+    - `mkdocs.yml`
+
+
+An example of this is the [Poetry](https://github.com/python-poetry/poetry/tree/master/docs) repo. That  project is also how I got into MkDocs in the first place.
+
+## Embedding
+
+To embed a gist, just copy and paste the embed script URL which is provided on a gist.
+
+e.g.
+
+```html
+<script src="https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js"></script>
+```

docs/docs/tutorial/deploy.md

@@ -0,0 +1,59 @@
+# Deploy
+> Build and deploy to a remote public site
+
+
+See [Deploying Your Docs](https://www.mkdocs.org/user-guide/deploying-your-docs/) on the Mkdocs site for more details.
+
+
+## GitHub Pages
+> How to deploy your docs site to GitHub Pages.
+
+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
+> Run a MkDocs CLI command locally to deploy
+
+MkDocs needs to know where to publish commits on GitHub - so make sure you are working with a repo that you cloned, or that you initialize the local repo and add a `remote` repo.
+
+Run this command locally:
+
+```sh
+$ make d
+```
+
+That will use `Makefile` to run the following:
+
+```sh
+$ mkdocs gh-deploy --strict --force
+```
+
+That will do the following:
+
+1. Clean and build to `site` directory.
+2. Force push to `gh-pages` branch, overwriting any changes which were pushed from another build.
+
+Then go to your repo on GitHub, look at the *Environment* tab.
+
+When it is done building, click _View deployment_ to see your site.
+
+e.g. [michaelcurrin.github.io/mkdocs-quickstart/](https://michaelcurrin.github.io/mkdocs-quickstart/)
+
+See deploy options in the help:
+
+```sh
+$ mkdocs gh-deploy --help
+```
+
+### Deploy with GitHub Actions
+>  Set up continuous deployment config to enable deploys on a change to files on GitHub
+
+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.

docs/docs/tutorial/installation.md

@@ -0,0 +1,74 @@
+# Installation
+> How to install MkDocs locally.
+
+
+## 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
+
+<script src="https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js"></script>
+
+
+## Set up a new repo
+
+Follow the Tutorial page to set up a project from scratch.
+
+Or click this 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 your repo.
+
+e.g.
+
+```sh
+$ git clone [email protected]:MichaelCurrin/mkdocs-quickstart.git
+$ cd mkdocs-quickstart
+```
+
+
+## Install project dependencies
+> Install MkDocs locally
+
+For more info, see the [Installation](https://www.mkdocs.org/#installation) page on the MkDocs site.
+
+### Install in a virtual environment
+
+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 the environment.
+
+```sh
+$ source venv/bin/activate
+```
+
+Install `mkdocs` - this is covered in the project requirements file.
+
+```sh
+$ cd docs
+$ 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 instead.
+
+MkDocs is available using package managers like `apt-get`, `homebrew` and `yum`.
+
+Or you can install like this:
+
+```sh
+$ python3 -m pip install mkdocs
+```
+
+If you get prompted for `sudo` use, then cancel and run again with `-U` flag for user-level install.