docs: Update docs

.github/workflows/docs.yml

@@ -6,8 +6,8 @@ on:
       - master
 
 jobs:
-  build:
-    name: Build
+  build-deploy:
+    name: Build and deploy to GH Pages
     runs-on: ubuntu-latest
 
     steps:
@@ -16,8 +16,17 @@ jobs:
       - name: Set up Python 3.x
         uses: actions/setup-python@v2
 
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('docs/requirements.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+            ${{ runner.os }}-
+
       - name: Install dependencies
-        run: make install
+        run: cd docs && make install
 
       - name: Build and deploy
-        run: make deploy
+        run: cd docs && make deploy

README.md

@@ -4,7 +4,6 @@
 [![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/)
 [![Made with GH Actions](https://img.shields.io/badge/Made_with-GH_Actions-blue?logo=github-actions&logoColor=white)](https://github.com/features/actions)
-[![Made with MkDocs Deploy GH Pages](https://img.shields.io/badge/Made_with-MkDocs_Deploy_GH_Pages-blue?logo=github-actions&logoColor=white)](https://github.com/mhausenblas/mkdocs-deploy-gh-pages)
 [![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)
 
@@ -35,12 +34,12 @@ This project uses the _Read the Docs_ theme as seen above. It comes with MkDocs
 
 ## 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.
+- A **markdown-based** docs site which is easy to edit - see the content in the [docs](/docs/docs/) directory.
+- Easy to **configure** - see the short [mkdocs.yml](/docs/mkdocs.yml) file.
 - Use the configured theme or switch to another - no need to write HTML and CSS yourself.
 - Each theme comes with a navbar and you write YAML - Jekyll themes on GH Pages need you to write your own HTML often and each theme handles navbar its own way (sometimes not at all).
 - Uses a deploy pipeline on GH Actions to deploy a GH Pages site - the action actually runs GH Pages deploy command.
-- The static site output is SEO-friendly.
+- The static site output is **SEO-friendly**.
 - Built on Python but you don't need to write any Python code.
 
 ### View live demo site
@@ -77,7 +76,7 @@ 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.
+2. Set up the project locally - follow the instructions on the live tutorial or in the [TL;DR](/docs/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.

docs/docs/about-mkdocs.md

@@ -17,6 +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/)
 
 
 ## Reasons to use MkDocs

docs/docs/index.md

@@ -17,7 +17,7 @@ Follow the tutorial to add an existing project or create a project from scratch.
     - 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)
+    - [![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.
 

docs/docs/tutorial/deploy.md

@@ -11,7 +11,7 @@ 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 Githhub Actions](#deploy-with-github-actions) - Setup continous deployment config to enable deploys on a change to files on GitHub.
+- [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.
 
 
 _Note this is for a Project Page on a subpath and not an Organization or User Page._
@@ -57,8 +57,4 @@ $ 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.
 
-This action is setup to do that for MkDocs and the Material theme:
-
-- [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/docs.yml) file of this MkDocs Quickstart project.
+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

@@ -16,8 +16,21 @@
 
 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.
+
+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.
+
+e.g.
+
+```sh
+$ git clone git@github.com:MichaelCurrin/mkdocs-quickstart.git
+$ cd mkdocs-quickstart
+```
 
 
 ## Install project dependencies
@@ -39,9 +52,10 @@ Activate it.
 $ source venv/bin/activate
 ```
 
-Install `mkdocs` from project dependencies list.
+Install `mkdocs` from the project dependencies list.
 
 ```sh
+$ cd docs
 $ pip install -r requirements.txt
 ```
 

docs/docs/tutorial/tldr.md

@@ -7,10 +7,10 @@
 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)
+    - `mkdocs new .` or [![Use this template](https://img.shields.io/badge/Use_this_template-2ea44f&logo=github)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
 3. [Run](usage.md)
     - `mkdocs serve`
-4. View on [http://localhost:8000](http://localhost:8000)
+4. View on [localhost:8000](http://localhost:8000)
 
 
 ## Deploy to remote site

docs/docs/tutorial/usage.md

@@ -1,6 +1,37 @@
 # Usage
 > Build and preview a site locally
 
+Make sure to run all commands from the `docs` directory.
+
+```sh
+$ cd docs
+```
+
+
+## CLI help
+
+```sh
+$ make help
+```
+```
+.PHONY: docs
+
+default: install
+
+
+h help:
+
+
+install:
+
+
+s serve:
+
+b build:
+
+d deploy:
+```
+
 
 ## Serve docs
 

docs/mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: MkDocs Quickstart
-# For SEO.
+# SEO description.
 site_description: "A concise recipe for setting up a MkDocs docs site on GitHub Pages"
 
 nav:
@@ -15,5 +15,5 @@ nav:
 
 theme: readthedocs
 
-# For the Edit in GitHub button.
+# Target for Edit in GitHub button.
 repo_url: https://github.com/MichaelCurrin/mkdocs-quickstart/

docs/requirements.txt

@@ -0,0 +1 @@
+mkdocs~=1.1

requirements.txt

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