feat: Update pages

README.md

@@ -1,2 +1,54 @@
 # MkDocs Quickstart
 > A concise recipe for setting up a MkDocs docs site on Github Pages
+
+[![Made with MkDocs](https://img.shields.io/badge/Made_with-MkDocs-blue.svg)](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)](https://github.com/MichaelCurrin/mkdocs-quickstart/blob/master/LICENSE)
+
+
+<!-- TODO When creating a new project copied from this, you can delete this README.md and start over -->
+
+[![GH pages](https://img.shields.io/badge/Github_Pages-MkDocs_Quickstart-green.svg?style=for-the-badge)](https://michaelcurrin.github.io/mkdocs-quickstart/)
+
+
+[![Use this template](https://img.shields.io/badge/Use_this_template-green.svg?style=for-the-badge)](https://github.com/MichaelCurrin/mkdocs-quickstart/generate)
+
+
+## Preview
+
+![sample](/sample.png)
+
+
+## Live site
+
+This project has a site deployed to Github Pages.
+
+_Note: The deploy is currently manually triggered by a local command, however there are Issues open to setup CI/CI remote deploys with Netlify or Github Actions._
+
+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.
+
+
+## Contributing
+
+Fork this project.
+
+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.
+
+Make any changes you want. Be sure to keep a copy of the original license in the repo. e.g. `cp LICENSE LICENSE-source`.
+
+Create a Pull Request.
+
+
+## License
+
+Released under [MIT](/LICENSE).

docs/index.md

@@ -4,18 +4,22 @@
 [![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**
+- **Follow the tutorial instructions**
-    - Covering installation, setting up and configuring project, running it locally and deploying it.
+    - Install and configure a new or existing project.
-- **Template repo**
+    - Run it locally.
-    - Click *Use this Template* on Github.
+    - Deploy it.
-- **Live demo**
+- **Add a copy of this project to your repos**
-    - Hosted on Github Pages.
+    - [![Use this template](https://img.shields.io/badge/Use_this_template-green.svg)](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/installation.md

@@ -4,7 +4,7 @@
 
 ## Requirements
 
-- [Python](https://www.python.org/)
+- [Python 3](https://www.python.org/)
 
 
 ## Install system dependencies
@@ -35,17 +35,22 @@ python3 -m venv venv
 
 Activate it.
 
-```
+```sh
 source venv/bin/activate
 ```
 
 Install dependencies.
 
-```sh
+- Directly.
-pip install mkdocs
+    ```sh
-```
+    pip install mkdocs
+    ```
+- Or use a `requirements.txt` file with `mkdocs` in it.
+    ```sh
+    pip install -r requirements.txt
+    ```
 
-### Globally
+### Install globally
 
 If you prefer to install MkDocs once and reuse it across projects, you can install it globally.
 

docs/tutorial/setup_project.md

@@ -23,13 +23,15 @@ This is the simplest MkDocs site you can make:
 
 ### 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,10 +51,13 @@ _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.
+    3. Choose a theme. 
-        ```yaml
+        - An example of choosing a theme which is builtin:
-        theme: readthedocs
+            ```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 it 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`.

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_
+## Local setup
-3. `mkdocs serve`
+
-4. `mkdocs gh-deploy`
+1. [Install](installation.md)
-5. View published site at [https://USERNAME.github.io/REPO-NAME/]()
+    - `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.

requirements.txt

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