Initial commit

.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-deploy:
+    name: Build and deploy docs
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout 🛎️
+        uses: actions/checkout@v2
+
+      - name: Set up Python 3 ⚙️ 🐍
+        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 🔧
+        working-directory: docs
+        run: make install
+
+      - name: Build and deploy to GitHub Pages 🏗️ 🚀
+        working-directory: docs
+        run: make deploy

.gitignore

@@ -0,0 +1,3 @@
+venv
+
+site/

.vscode/settings.json

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

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 - 2021 MichaelCurrin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,116 @@
+# MkDocs Quickstart
+> Starter template for a MkDocs docs site on GH Pages - including CI
+
+[![CI status](https://github.com/MichaelCurrin/mkdocs-quickstart/workflows/Deploy%20Docs/badge.svg)](https://github.com/MichaelCurrin/mkdocs-quickstart/actions)
+[![GitHub tag](https://img.shields.io/github/tag/MichaelCurrin/mkdocs-quickstart?include_prereleases=&sort=semver)](https://github.com/MichaelCurrin/mkdocs-quickstart/releases/)
+[![License](https://img.shields.io/badge/License-MIT-blue)](#license)
+
+[![Made with Python](https://img.shields.io/badge/Python->%3D3.6-blue?logo=python&logoColor=white)](https://python.org)
+[![Made with MkDocs](https://img.shields.io/badge/mkdocs-1-blue)](https://www.mkdocs.org/)
+[![CI - GH Actions](https://img.shields.io/badge/CI-GH_Actions-blue?logo=github-actions&logoColor=white)](https://github.com/features/actions)
+
+A template, live demo and tutorial for how to set up a MkDocs docs site on GH Pages. Using GitHub Actions to automated deploys.
+
+MkDocs is a Python package when turns your docs directory and YAML config into a static website. No Python coding needed. Just Markdown and some light configuration including a theme choice and menu.
+
+<!-- TODO When creating a new project copied from this template, you can delete this README.md and start over -->
+
+
+## Purpose
+
+This project provides low-code content-focused way to set up and host a markdown-based documentation site, with a professional look and themes. Built with MkDocs - a Python package which is a static site generator specializing in documentation.
+
+A GitHub Actions workflow is provided with this template so you can easily deploy to GitHub Pages too.
+
+
+## Preview
+
+<div align="center">
+
+[![Sample screenshot](/sample.png)](https://michaelcurrin.github.io/mkdocs-quickstart/ "Sample screenshot")
+
+</div>
+
+This template project is configured to use the _Read the Docs_ theme, as shown above. 
+
+Thus looks like the the [Read The Docs][] site, but without having to have to overhead of using Sphinx.
+
+[Read The Docs]: https://docs.readthedocs.io
+
+This Read the Docs theme for MkDocs comes with MkDocs already, so you don't need to add to your dependencies. But you can switch to the MkDocs default or install and configure another theme.
+
+You can switch to the default theme or install some others, based on the instructions in this template project.
+
+
+## How to use this project
+
+<div align="center">
+
+[![GH Pages](https://img.shields.io/badge/View_site-MkDocs_Quickstart-blue?style=for-the-badge)](https://michaelcurrin.github.io/mkdocs-quickstart/)
+
+[![Use this template](https://img.shields.io/badge/Generate-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 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**.
+- Built on Python but you don't need to write any Python code.
+
+### 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.
+
+To isolate the MkDocs flow from the rest of your code, you can put the configs and the `docs` folder of content inside the `docs` directory. That means you end up having `docs/docs`, which is okay. Just make sure you select the `/docs` directory when setting up GH Pages.
+
+
+## About MkDocs
+
+### Resources
+
+- Homepage: [mkdocs.org](http://www.mkdocs.org/)
+- Repo: [![mkdocs - mkdocs](https://img.shields.io/static/v1?label=mkdocs&message=mkdocs&color=blue&logo=github)](https://github.com/mkdocs/mkdocs) [![stars - mkdocs](https://img.shields.io/github/stars/mkdocs/mkdocs?style=social)](https://github.com/mkdocs/mkdocs)
+- PyPI package: [mkdocs](https://pypi.org/project/mkdocs/)
+
+### Why MkDocs?
+
+If you're new to MkDocs, look at the tutorial added on this project's site, otherwise go to the MkDocs homepage for 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 set up 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 [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.
+
+
+## License
+
+Released under [MIT](/LICENSE) by [@MichaelCurrin](https://github.com/MichaelCurrin).

docs/Makefile

@@ -0,0 +1,29 @@
+.PHONY: docs
+
+default: install
+
+all: install build
+
+
+h help:
+	@grep '^[a-z]' Makefile
+
+
+install:
+	pip install pip --upgrade
+	pip install -r requirements.txt
+
+upgrade:
+	pip install pip --upgrade
+	pip install -r requirements.txt --upgrade
+
+
+s serve:
+	mkdocs serve --strict
+
+
+b build:
+	mkdocs build --strict
+
+d deploy:
+	mkdocs gh-deploy --strict --force

docs/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 that 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.
+- [Release notes](https://www.mkdocs.org/about/release-notes/) for 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 Sphinx), but you don't have to write Python code. If you set up a [Deploy](deploy) flow right, you don't even have to set it up locally, though then you can't preview.

docs/docs/index.md

@@ -0,0 +1,26 @@
+# MkDocs Quickstart
+>  Started template for a MkDocs docs site on GH Pages - including CI 
+
+[![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.
+
+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?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.
+
+
+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/docs/tutorial/advanced.md

@@ -0,0 +1,53 @@
+# Advanced
+> Beyond the basic configuration and content
+
+Once you've got the [Set up 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
+```
+
+The value can either be a string (as in the first case) or a map (as in the last case). This seems to be a YAML limitation but see also [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 set up 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/docs/tutorial/deploy.md

@@ -0,0 +1,59 @@
+# 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 GitHub Actions](#deploy-with-github-actions) - Use the project's CI workflow in the cloud to build and deploy to GH Pages on commits pushed to master.
+
+Then go to your repo's _Settings_ and _Pages_ then enable _GitHub Pages_ on the `gh-pages` branch's root.
+
+_Note this is for a Project Page on a subpath, you will have to make adjustments to the command below if you want an Organization or User Page on the root path._
+
+### 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
+$ make d
+```
+
+That will use `Makefile` to run the following:
+
+```sh
+$ mkdocs gh-deploy --strict --force
+```
+
+That will do the following:
+
+1. Clean and build to `site` directory.
+2. Force push to `gh-pages` branch, overwriting any changes which were pushed from another build.
+
+Then go to your repo on GitHub, look at the *Environment* tab.
+
+When it is done building, click _View deployment_ to see your site.
+
+e.g. [michaelcurrin.github.io/mkdocs-quickstart/](https://michaelcurrin.github.io/mkdocs-quickstart/)
+
+See deploy options in the help:
+
+```sh
+$ mkdocs gh-deploy --help
+```
+
+### Deploy with GitHub Actions
+>  Set up continuous 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.
+
+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.