Update README.md

.github/workflows/main.yml

@@ -0,0 +1,22 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - master
+    paths: 
+      - 'docs/**'
+        
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout master
+        uses: actions/checkout@v1
+
+      - name: Deploy to GH Pages
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -1,2 +1,74 @@
 # MkDocs Quickstart
-> A concise recipe for setting up a MkDocs docs site on Github Pages
+> A template, live demo and tutorial for how to setup a MkDocs docs site on GitHub Pages
+
+![CI status](https://github.com/MichaelCurrin/mkdocs-quickstart/workflows/Deploy%20docs/badge.svg)
+[![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.svg)](https://GitHub.com/MichaelCurrin/mkdocs-quickstart/tags/)
+[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](#license)
+
+
+<!-- TODO When creating a new project copied from this template, you can delete this README.md and start over -->
+
+## Preview
+
+[![Sample screenshot](/sample.png)](https://michaelcurrin.github.io/mkdocs-quickstart/)
+
+## 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/)
+[![Use this template](https://img.shields.io/badge/Use_this_template-2ea44f?style=for-the-badge)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
+
+</div>
+
+
+## Features
+
+- A markdown-based docs site which is easy to edit - see the content [docs](/docs/) directory.
+- 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.
+- Uses a deploy pipeline on GH Actions to deploy a GH Pages site.
+
+
+### View live demo site
+
+This project has a site deployed to GitHub Pages.
+
+Purposes of the site:
+
+- A live demo.
+- Content for a beginner-friendly tutorial on how to setup, run, deploy and customize a MkDocs project like this one.
+
+### Use this template
+
+This repo also doubles as a template to create a new project from. Click the button at the top.
+
+Change the content and theme to suit your needs, based on the tutorial site or the MkDocs site.
+
+
+## Why use MkDocs? 
+
+If you're new to MkDocs, look at the tutorial added on this project's site, otherwise go to the MkDocs 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.
+
+Compared with Jekyll and Docsify, I found the MkDocs code is much lighter to setup and changing themes is much easier than Jekyll. Also you get the benefits SEO which Docsify doesn't have. And it includes a search bar using JS.
+
+
+## Contributing
+
+Submit an issue.
+
+Or submit a code change:
+
+1. Fork this project.
+2. Set up the project locally - follow the instructions on the live tutorial or in the [TLDR](/docs/tutorial/tldr.md) page of the local docs.
+3. Make any changes you want. Be sure to keep a copy of the original license in the repo. 
+    - e.g. `cp LICENSE LICENSE-source`
+4. Create a Pull Request.
+
+
+## License
+
+Released under [MIT](/LICENSE).

docs/about-mkdocs.md

@@ -1,7 +1,6 @@
 # About MkDocs
 
 
-
 ## What is MkDocs?
 
 The description on the MkDocs site is:

docs/index.md

@@ -1,21 +1,25 @@
 # MkDocs Quickstart
-> A concise recipe for setting up a MkDocs docs site on Github Pages
+> A template, live demo and tutorial for how to setup a MkDocs docs site on Github Pages
 
 [![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. Add to an existing project or create a project from scratch.
+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
 
-- **Tutorial**
-    - Covering installation, setting up and configuring project, running it locally and deploying it.
-- **Template repo**
-    - Click *Use this Template* on Github.
-- **Live demo**
-    - Hosted on Github Pages.
+- **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)](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.

docs/tutorial/deploy.md

@@ -8,10 +8,16 @@ See [Deploying Your Docs](https://www.mkdocs.org/user-guide/deploying-your-docs/
 ## Github Pages
 > How to deploy your docs site to Github Pages.
 
-_Note this is for a Project Page and not Organization and User Pages._
+Follow one of the approaches below:
 
+- [Run deploy command](#run-deploy-command) - Run a MkDocs CLI command locally to deploy.
+- [Deploy with Githhub Actions](#deploy-with-github-actions) - Setup continous deployment config to enable deploys on a change to files on Github.
+
+
+_Note this is for a Project Page and not Organization or User Pages._
 
 ### 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.
 
@@ -40,11 +46,13 @@ See deploy options:
 mkdocs gh-deploy --help
 ```
 
-### Remote build
-> How to trigger a rebuild of your docs site on changes
+### Deploy with Github Actions
+>  Setup continous 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 without you running a command. A remote build also means you not need to setup Python or MkDocs on your local machine just to get the docs site to work.
+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.
 
-So setup a Github Action such as this to your project.
+This action is setup to do that for MkDocs:
 
 - [deploy-mkdocs](https://github.com/marketplace/actions/deploy-mkdocs) action in marketplace.
+
+See this implemented in the [workflow](https://github.com/MichaelCurrin/mkdocs-quickstart/blob/master/.github/workflows/main.yml) file of this MkDocs Quickstart project.

docs/tutorial/installation.md

@@ -4,7 +4,7 @@
 
 ## Requirements
 
-- [Python](https://www.python.org/)
+- [Python 3](https://www.python.org/)
 
 
 ## Install system dependencies
@@ -21,7 +21,7 @@ Choose or setup a MkDocs project.
 
 
 ## Install project dependencies
-> Install MkDocs
+> Install MkDocs locally
 
 For more info, see the [Installation](https://www.mkdocs.org/#installation) page on the MkDocs site.
 
@@ -35,21 +35,29 @@ python3 -m venv venv
 
 Activate it.
 
-```
+```sh
 source venv/bin/activate
 ```
 
-Install dependencies.
+Install dependencies using one of these approaches:
 
-```sh
-pip install mkdocs
-```
+<!-- Using `sh` for code block breaks for bullet points at least for read the docs theme -->
 
-### Globally
+- Install directly.
+    ```bash
+    pip install mkdocs
+    ```
+- Create a `requirements.txt` file, add `mkdocs` to it then install from the file.
+    ```bash
+    echo 'mkdocs' > requirements.txt
+    pip install -r requirements.txt
+    ```
 
-If you prefer to install MkDocs once and reuse it across projects, you can install it globally.
+### Install globally
 
-MkDocs is available with package managers like `apt-get`, `homebrew` and `yum`.
+If you prefer to install MkDocs once and reuse it across projects, then you can install it globally.
+
+MkDocs is available using package managers like `apt-get`, `homebrew` and `yum`.
 
 You can install like this too:
 

docs/tutorial/setup-project.md

@@ -21,15 +21,24 @@ This is the simplest MkDocs site you can make:
 - `mkdocs.yml` - Config at the root.
 
 
+### Requirements file
+
+A requirements file is optional but it can make it easier to manage dependencies. If you choose not use the file, make sure `pip install mkdocs` and `pip install THEME` lines are your instructions.
+
+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 `dev-requirements.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 the starter site outline above. This make the steps below go quicker.
+Run this command to create a starter site. This make the steps below go quicker.
 
 ```sh
 cd my-project
 mkdocs new PATH
 ```
 
+The result will be same as the [Basic structure](#basic-structure) defined above and will include minimal text content generated by the MkDocs CLI. This text is defined in the project's [new.py](https://github.com/mkdocs/mkdocs/blob/master/mkdocs/commands/new.py) module.
+
 
 ### Setup a docs site
 
@@ -49,21 +58,24 @@ _Tip: Optionally use the `new` command covered above to setup the config and ind
             - Home: index.md
             - About: about.md
         ```
-    3. Choose a theme. e.g.
-        ```yaml
-        theme: readthedocs
-        ```
+    3. Choose a theme. 
+        - An example of choosing a theme which is builtin:
+            ```yaml
+            theme: 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.
+            
 3. Create a favicon (optional).
     - It will be picked up at this path: `docs/img/favicon.ico`.
 4. Add to your `.gitignore`.
     - Add build directory. This will prevent it from being versioned on `master` branch.
     - Add virtual environment, if using one.
-    - e.g.
-        ```
-        site/
+    - For example:
+    ```
+    site/
 
-        venv
-        ```
+    venv
+    ```
 
 You project should now look this this:
 
@@ -73,3 +85,4 @@ You project should now look this this:
 - `mkdocs.yml`
 - `.gitignore`
 - `venv`
+- `requirements.txt` - optional

docs/tutorial/tldr.md

@@ -1,8 +1,28 @@
-## TL;DR
+# TL;DR
 > A simplified version of the tutorial.
 
-1. `pip install mkdocs`
-2. `mkdocs new .` or click _Use this Template_
-3. `mkdocs serve`
-4. `mkdocs gh-deploy`
-5. View published site at [https://USERNAME.github.io/REPO-NAME/]()
+
+## Local setup
+
+1. [Install](installation.md)
+    - `pip install mkdocs`
+2. [Setup project](setup_project.md)
+    - `mkdocs new .` or [![Use this template](https://img.shields.io/badge/Use_this_template-green.svg)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
+3. [Run](usage.md)
+    - `mkdocs serve`
+4. View on [http://localhost:8000](http://localhost:8000)
+
+
+## Deploy to remote site
+
+### Run deploy command locally
+
+1. [Deploy](deploy.md) to Github Pages
+    - `mkdocs gh-deploy`
+2. View published site on Github Pages at `https://USERNAME.github.io/REPO-NAME/`
+
+### Run continuous integration
+
+For CI/CD deploy, use Github Actions with an action such as [Deploy MkDocs](https://github.com/marketplace/actions/deploy-mkdocs). Or use Netlify.
+
+This is not covered in this tutorial.

mkdocs.yml

@@ -1,16 +1,19 @@
 site_name: MkDocs Quickstart
 # For SEO.
-site_description: 'A concise recipe for setting up a MkDocs docs site on Github Pages'
+site_description: 'A concise recipe for setting up a MkDocs docs site on GitHub Pages'
+
 nav:
     - Home: index.md
-    - About MkDocs: about_mkdocs.md
+    - About MkDocs: about-mkdocs.md
     - Tutorial:
         - TL;DR: tutorial/tldr.md
         - Installation: tutorial/installation.md
-        - Setup project: tutorial/setup_project.md
+        - Setup project: tutorial/setup-project.md
         - Advanced: tutorial/advanced.md
         - Usage: tutorial/usage.md
         - Deploy: tutorial/deploy.md
+        
 theme: readthedocs
-# For adding Edit in Github button.
+
+# URL for the Edit in GitHub button.
 repo_url: https://github.com/MichaelCurrin/mkdocs-quickstart/

requirements.txt

@@ -0,0 +1 @@
+mkdocs