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 }}

.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "python.pythonPath": "venv/bin/python"
+}

.vscode/tasks.json

@@ -0,0 +1,51 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build",
+            "type": "process",
+            "command": "${config:python.pythonPath}",
+            "args": ["-m", "mkdocs", "build"],
+            "problemMatcher": [],
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            }
+        },
+        {
+            "label": "serve",
+            "type": "process",
+            "command": "${config:python.pythonPath}",
+            "args": ["-m", "mkdocs", "serve"],
+            "problemMatcher": [],
+        },
+        {
+            "label": "deploy",
+            "type": "process",
+            "command": "${config:python.pythonPath}",
+            "args": ["-m", "mkdocs", "gh-deploy"],
+            "problemMatcher": [],
+        },
+        // Reference globally-installed MkDocs.
+        {
+            "label": "build-global",
+            "type": "shell",
+            "command": "mkdocs build",
+            "problemMatcher": [],
+        },
+        {
+            "label": "serve-global",
+            "type": "shell",
+            "command": "mkdocs serve",
+            "problemMatcher": [],
+        },
+        {
+            "label": "deploy-global",
+            "type": "shell",
+            "command": "mkdocs gh-deploy",
+            "problemMatcher": [],
+        }
+    ]
+}

README.md

@@ -1,2 +1,74 @@
 # MkDocs Quickstart
-> A brief guide 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

@@ -0,0 +1,40 @@
+# About MkDocs
+
+
+## What is MkDocs?
+
+The description on the MkDocs site is:
+
+> Project documentation with Markdown.
+
+MkDocs is a Python tool 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.
+
+
+## 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 Sphynx), but you don't have to write Python code. If you setup a [Deploy](deloy) flow right, you don't even have to set it up locally, though then you can't preview.

docs/deploy.md

@@ -1,31 +0,0 @@
-# Deploy
-> How to deploy a MkDocs site
-
-
-See [Deploying Your Docs](https://www.mkdocs.org/user-guide/deploying-your-docs/) on the Mkdocs site for more details.
-
-
-## Github Pages
-
-_Note this is for a Project Page and not Organization and User Pages._
-
-How to deploy to Github Pages.
-
-Run this to build to `site` directory, push to `gh-pages` branch and enable Github Pages (if it was not yet enabled). The default option is to clean the site directory first.
-
-```sh
-mkdocs gh-deploy
-```
-
-Then go to your repo on Github, see the *environment* tab and click _View deployment_.
-
-e.g.
-
-- [michaelcurrin.github.io/mkdocs-quickstart/](https://michaelcurrin.github.io/mkdocs-quickstart/)
-
-
-See deploy options:
-
-```sh
-mkdocs gh-deploy --help
-```

docs/index.md

@@ -1,5 +1,27 @@
 # MkDocs Quickstart
-> A brief guide 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)
 
 
-This is based on the [mkdocs.org](https://www.mkdocs.org/) tutorial.
+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)](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/setup_and_run.md

@@ -1,43 +0,0 @@
-# Setup and run
-> How to setup and run the docs site
-
-
-## Install
-
-Install in a virtual environment.
-
-```sh
-pip install mkdocs
-```
-
-
-## Server docs locally
-
-This will build the docs in memory (not to disk) and serve an auto-reloading server.
-
-```sh
-mkdocs serve
-```
-
-Open URL:
-
-- [localhost:8000](http://localhost:8000)
-
-
-
-## Build docs
-
-Build docs site to `site` directory.
-
-```sh
-mkdocs build
-```
-
-Useful for production build or simulating that locally.
-
-
-Remove stale files.
-
-```sh
-mkdocs build --clean
-```

docs/tutorial.md

@@ -1,31 +0,0 @@
-# Tutorial
-> How to create a MkDocs site.
-
-This is a summary of the tutorial on [mkdocs.org](https://www.mkdocs.org/).
-
-
-### Setup site
-
-1. Create pages.
-    1. Create `docs` directory.
-    2. Create `index.md`
-    3. Create other pages.
-2. Setup config.
-    1. Create `mkdocs.yml` at project root.
-    2. Setup navbar in `mkdocs.yml`.
-        ```yaml
-        nav:
-        - Home: index.md
-        - About: about.md
-        ```
-    3. Choose a theme.
-        ```yaml
-        theme: readthedocs
-        ```
-3. Create a favicon.
-    - It will be picked up this path: `docs/img/favicon.ico`.
-
-
-### Further configuration
-
-See [Configuration](https://www.mkdocs.org/user-guide/configuration/) page on MkDocs site for options.

docs/tutorial/advanced.md

@@ -0,0 +1,63 @@
+# Advanced
+> Beyond the basic configuration and content
+
+Once you've got the [Setup 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
+```
+
+However, adding a path when nesting as below is **invalid** and will give an error:
+
+```yaml
+nav:
+    - Home: index.md
+    - About: about.md
+    - Foo: foo/index.md
+        - Bar: foo/bar.md
+```
+
+See [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 setup 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/tutorial/deploy.md

@@ -0,0 +1,58 @@
+# 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 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.
+
+Run this command locally:
+
+```sh
+mkdocs gh-deploy
+```
+
+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.
+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_.
+
+e.g.
+
+- [michaelcurrin.github.io/mkdocs-quickstart/](https://michaelcurrin.github.io/mkdocs-quickstart/)
+
+
+See deploy options:
+
+```sh
+mkdocs gh-deploy --help
+```
+
+### 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 automatically in a remote environment. This is provided for free by Github.
+
+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

@@ -0,0 +1,66 @@
+# Installation
+> How to install MkDocs locally.
+
+
+## Requirements
+
+- [Python 3](https://www.python.org/)
+
+
+## Install system dependencies
+
+<script src="https://gist.github.com/MichaelCurrin/57caae30bd7b0991098e9804a9494c23.js"></script>
+
+
+## Setup repo
+
+Choose or setup a MkDocs project.
+
+- Follow the tutorial page to setup a project.
+- Or click _Use this template_ on this repo to create your own copy of the repo, then clone it.
+
+
+## Install project dependencies
+> Install MkDocs locally
+
+For more info, see the [Installation](https://www.mkdocs.org/#installation) page on the MkDocs site.
+
+### Use a virtual environment
+
+Create a virtual environment at the project root.
+
+```sh
+python3 -m venv venv
+```
+
+Activate it.
+
+```sh
+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 -->
+
+- 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
+    ```
+
+### Install globally
+
+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:
+
+```sh
+python3 -m pip install mkdocs
+```

docs/tutorial/setup-project.md

@@ -0,0 +1,88 @@
+# Setup project
+> How to create a MkDocs site from scratch
+
+This is a summary of the tutorial on [mkdocs.org](https://www.mkdocs.org/).
+
+
+## How to use this guide
+
+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 [Setup 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.
+
+
+### 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 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
+
+_Tip: Optionally use the `new` command covered above to setup the config and index page first and then continue_.
+
+1. Create doc pages.
+    1. Create a `docs` directory.
+    2. Create `index.md` as your homepage.
+    3. Create other markdown pages (optional).
+        - 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. Setup config.
+    1. Create `mkdocs.yml` at project root.
+    2. Setup navbar there. e.g.
+        ```yaml
+        nav:
+            - Home: index.md
+            - About: about.md
+        ```
+    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.
+    - For example:
+    ```
+    site/
+
+    venv
+    ```
+
+You project should now look this this:
+
+- `docs/`
+    - `index.md`
+    - Other pages...
+- `mkdocs.yml`
+- `.gitignore`
+- `venv`
+- `requirements.txt` - optional

docs/tutorial/tldr.md

@@ -0,0 +1,28 @@
+# TL;DR
+> A simplified version of the tutorial.
+
+
+## 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.

docs/tutorial/usage.md

@@ -0,0 +1,33 @@
+# Usage
+> Build and preview a site locally
+
+_Note: If using VS Code, you can use the command palette instead to run the configured tasks - these are setup in `.vscode/tasks.json`._
+
+
+## Serve docs
+
+This will build the docs in memory (not to disk) and serve an auto-reloading server.
+
+```sh
+mkdocs serve
+```
+
+Open URL:
+
+- [localhost:8000](http://localhost:8000)
+
+
+## Build docs
+
+Build docs site to `site` directory. Useful for production build or simulating that locally.
+
+
+```sh
+mkdocs build
+```
+
+Add this flag to remove stale files when building.
+
+```sh
+mkdocs build --clean
+```

mkdocs.yml

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

requirements.txt

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