docs: Instructions for using mkdocs

docs/tools/mkdocs.md

@@ -0,0 +1,31 @@
+# MkDocs
+
+## Introduction
+
+We are using MkDocs to generate our documentation. See [Docker-mkdocs repo](https://hackforla.github.io/docker-mkdocs/) for information about MkDocs and the image we're using.
+
+## MkDocs docker image
+
+### How it works
+
+#### Work on docs locally
+
+1. It should already be running with the peopledepot django server. If not, run the mkdocs container.
+
+    ```bash
+    docker-compose up mkdocs # (1)!
+    ```
+
+    1. Optionally use the `-d` flag to run the container in the background
+
+1. Open a browser to [`http://localhost:8005/`](https://localhost:8005/) to view the documentation locally.
+
+1. Modify the files in the `docs` directory. The site will auto-update when the files are saved.
+
+1. Quit
+
+    ++ctrl+c++ to quit the local server and stop the container
+
+#### Auto-generated docs
+
+We have a [GitHub Action](https://github.com/hackforla/peopledepot/blob/main/.github/workflows/deploy-docs.yml) set up to generate and host the documentation on a [GitHub Pages site](https://hackforla.github.io/peopledepot/)

mkdocs.yml

@@ -28,6 +28,7 @@ markdown_extensions:
       line_spans: __span
       pygments_lang_class: true
   - pymdownx.inlinehilite
+  - pymdownx.keys
   - pymdownx.snippets
   - pymdownx.superfences
   - pymdownx.tabbed:
@@ -50,10 +51,11 @@ nav:
       - architecture/Notes.md
   - Developer Guides:
       - how-to/add-model-and-api-endpoints.md
-  - Tools:
-      - tools/scripts.md
-      - Code Quality:
-          - tools/code-quality/pre-commit.md
+      - Tools:
+          - tools/scripts.md
+          - tools/mkdocs.md
+          - Code Quality:
+              - tools/code-quality/pre-commit.md
   - LICENSE.md
 
 watch: