feat: Add badges

.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,2 @@
 # MkDocs Quickstart
-> A brief guide for setting up a MkDocs docs site on Github Pages
+> A concise recipe for setting up a MkDocs docs site on Github Pages

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 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,23 @@
 # MkDocs Quickstart
-> A brief guide for setting up a MkDocs docs site on Github Pages
+> A concise recipe for setting up 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. Add to an existing project or create a project from scratch.
+
+
+## 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.
+
+
+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,50 @@
+# 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.
+
+_Note this is for a Project Page and not Organization and User Pages._
+
+
+### Run deploy command
+
+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
+```
+
+### Remote build
+> How to trigger a rebuild of your docs site on changes
+
+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.
+
+So setup a Github Action such as this to your project.
+
+- [deploy-mkdocs](https://github.com/marketplace/actions/deploy-mkdocs) action in marketplace.

docs/tutorial/installation.md

@@ -0,0 +1,58 @@
+# Installation
+> How to install MkDocs locally.
+
+
+## Requirements
+
+- [Python](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
+
+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.
+
+```
+source venv/bin/activate
+```
+
+Install dependencies.
+
+```sh
+pip install mkdocs
+```
+
+### Globally
+
+If you prefer to install MkDocs once and reuse it across projects, you can install it globally.
+
+MkDocs is available with 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,75 @@
+# 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.
+
+
+### Create a starter site
+
+Run this command to create the starter site outline above. This make the steps below go quicker.
+
+```sh
+cd my-project
+mkdocs new PATH
+```
+
+
+### 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. e.g.
+        ```yaml
+        theme: readthedocs
+        ```
+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/
+
+        venv
+        ```
+
+You project should now look this this:
+
+- `docs/`
+    - `index.md`
+    - Other pages...
+- `mkdocs.yml`
+- `.gitignore`
+- `venv`

docs/tutorial/tldr.md

@@ -0,0 +1,8 @@
+## 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/]()

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,16 @@
 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
+# For adding Edit in Github button.
 repo_url: https://github.com/MichaelCurrin/mkdocs-quickstart/