From 29f21df22c900ba899b7224d812e0cd34f01150b Mon Sep 17 00:00:00 2001 From: Michael Currin Date: Sat, 2 May 2020 23:17:36 +0200 Subject: [PATCH] feat: Update pages --- docs/deploy.md | 24 +++++++++++++++++++++--- docs/index.md | 4 +++- docs/setup_and_run.md | 14 +++++++------- 3 files changed, 31 insertions(+), 11 deletions(-) diff --git a/docs/deploy.md b/docs/deploy.md index d304ab6..daee53f 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -1,22 +1,31 @@ # Deploy -> How to deploy a MkDocs site +> How to deploy a MkDocs site to be served publically 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._ -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. +### Run deploy command + + +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. @@ -29,3 +38,12 @@ 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. diff --git a/docs/index.md b/docs/index.md index 40a4c46..2d4b1fe 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,7 @@ # MkDocs Quickstart -> A brief guide for setting up a MkDocs docs site on Github Pages +> A concise recipe for setting MkDocs docs site on Github Pages This is based on the [mkdocs.org](https://www.mkdocs.org/) 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. diff --git a/docs/setup_and_run.md b/docs/setup_and_run.md index 04f03e8..e751386 100644 --- a/docs/setup_and_run.md +++ b/docs/setup_and_run.md @@ -1,9 +1,12 @@ # Setup and run -> How to setup and run the docs site +> How to setup and run a docs 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`)._ ## Install +Make sure you have Python installed - ideally a recent Python 3 version. + Install in a virtual environment. ```sh @@ -24,19 +27,16 @@ Open URL: - [localhost:8000](http://localhost:8000) - ## Build docs -Build docs site to `site` directory. +Build docs site to `site` directory. Useful for production build or simulating that locally. + ```sh mkdocs build ``` -Useful for production build or simulating that locally. - - -Remove stale files. +Add this flag to remove stale files when building. ```sh mkdocs build --clean