feat: Restructure and add content

.vscode/tasks.json

@@ -5,8 +5,9 @@
     "tasks": [
         {
             "label": "build",
-            "type": "shell",
+            "type": "process",
-            "command": "mkdocs build",
+            "command": "${config:python.pythonPath}",
+            "args": ["-m", "mkdocs", "build"],
             "problemMatcher": [],
             "group": {
                 "kind": "build",
@@ -15,13 +16,36 @@
         },
         {
             "label": "serve",
-            "type": "shell",
+            "type": "process",
-            "command": "mkdocs serve"
+            "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 gh-deploy"
+            "command": "mkdocs build",
+            "problemMatcher": [],
+        },
+        {
+            "label": "serve-global",
+            "type": "shell",
+            "command": "mkdocs serve",
+            "problemMatcher": [],
+        },
+        {
+            "label": "deploy-global",
+            "type": "shell",
+            "command": "mkdocs gh-deploy",
+            "problemMatcher": [],
         }
     ]
 }

docs/about_mkdocs.md

@@ -0,0 +1,22 @@
+# About MkDocs
+
+
+## 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/advanced.md

@@ -0,0 +1,52 @@
+# Advanced configuration
+
+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.

docs/deploy.md

@@ -1,5 +1,5 @@
 # Deploy
-> How to deploy a MkDocs site to be served publically
+> 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.

docs/index.md

@@ -2,26 +2,20 @@
 > A concise recipe for setting up a MkDocs docs site on Github Pages
 
 
-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 of this project
 
-- Quickstart tutorial
+## Features
-- Live demo on Github Pages
+> How to use this project
-- Template repo
+
+- **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.
-## Reasons to use MdDocs
-
-- Create an elegant, modern docs site for your project.
-- Create a static site and serve from Github Pages easily.
-- Flexible theming.
-- No coding in HTML or templating langauge needed - use your existing markdown files and a YAML config.
-- Customizable.
-- Plugins available.
-- Includes search by default.
-
-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/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/setup_and_run.md

@@ -1,60 +0,0 @@
-# Inst and run
-> How to setup and run a docs site locally
-
-
-## Install
-
-Make sure you have Python installed - ideally a recent Python 3 version.
-
-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.
-
-
-Create a virtual environment at the project root.
-
-```sh
-python3 -m venv venv
-```
-
-Install dependencies.
-
-```sh
-pip install mkdocs
-```
-
-
-## Usage
-
-
-_Note: If using VS Code, you can use the command palette instead to run the configured tasks - these are setup in `.vscode/tasks.json`._
-
-
-### 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. Useful for production build or simulating that locally.
-
-
-```sh
-mkdocs build
-```
-
-Add this flag to remove stale files when building.
-
-```sh
-mkdocs build --clean
-```

docs/setup_project.md

@@ -0,0 +1,76 @@
+# 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.
+- Click *Use this Template* button on the Github repo to get your own copy.
+
+
+### 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/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.md

@@ -1,58 +0,0 @@
-# Tutorial
-> How to create a MkDocs site
-
-This is a summary of the tutorial on [mkdocs.org](https://www.mkdocs.org/).
-
-
-### Basic structure
-
-This is the simplest MkDocs site you can make:
-
-- `mkdocs.yml` - Config at the root.
-- `docs/index.md` - Homepage in the `docs` directory (by default).
-
-
-The steps below start with that and extend it to more pages.
-
-
-Run this command to create the starter site above. This make the steps below go quicker.
-
-```sh
-cd my-project
-mkdocs new PATH
-```
-
-### Setup site
-
-1. Create docs pages.
-    1. Create `docs` directory.
-    2. Create `index.md`
-    3. Create other pages (optional).
-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
-        ```
-
-
-### Further configuration
-
-See [Configuration](https://www.mkdocs.org/user-guide/configuration/) page on MkDocs site for options.

docs/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

@@ -3,9 +3,14 @@ site_name: MkDocs Quickstart
 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
+    - About MkDocs: about_mkdocs.md
-    - Tutorial: tutorial.md
+    - Tutorial:
-    - Deploy: deploy.md
+        - TL;DR: tldr.md
+        - Installation: installation.md
+        - Setup project: setup_project.md
+        - Advanced configuration: advanced.md
+        - Usage: usage.md
+        - Deploy: deploy.md
 theme: readthedocs
 # For adding Edit in Github button.
 repo_url: https://github.com/MichaelCurrin/mkdocs-quickstart/