docs: Add mkdocs support to render static documentation site on GitHub (#3070)

* docs: Add `mkdocs` support to render static documentation site on GitHub

* fix: Correct mis-spelled file name

Author: bryantbiggs

.github/workflows/publish-docs.yml

@@ -0,0 +1,41 @@
+name: Publish docs via GitHub Pages
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install mkdocs-material==9.5.26 \
+            mkdocs-include-markdown-plugin==6.2.0 \
+            mkdocs-awesome-pages-plugin==2.9.2
+
+      - name: git config
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+
+      - run: mkdocs gh-deploy --force

docs/.pages

@@ -0,0 +1,3 @@
+nav:
+  - Overview: index.md
+  - Local Develpment: local.md

docs/assets/logo.png

@@ -0,0 +1,3 @@
+# Terraform AWS EKS module
+
+Moar content coming soon!

docs/assets/terraform-aws.png

@@ -0,0 +1,20 @@
+# Local Development
+
+## Documentation Site
+
+In order to run the documentation site locally, you will need to have the following installed locally:
+
+- [Python 3.x](https://www.python.org/downloads/)
+- [mkdocs](https://www.mkdocs.org/user-guide/installation/)
+- The following pip packages for mkdocs (i.e. - `pip install ...`)
+    - `mkdocs-material`
+    - `mkdocs-include-markdown-plugin`
+    - `mkdocs-awesome-pages-plugin`
+
+To run the documentation site locally, run the following command from the root of the repository:
+
+```bash
+mkdocs serve
+```
+
+Opening the documentation at the link posted in the terminal output (i.e. - [http://127.0.0.1:8000/terraform-aws-eks/](http://127.0.0.1:8000/terraform-aws-eks/))

docs/index.md

@@ -0,0 +1,65 @@
+site_name: Terraform AWS EKS
+docs_dir: docs/
+site_url: https://terraform-aws-modules/terraform-aws-eks/
+repo_name: terraform-aws-eks
+repo_url: https://github.com/terraform-aws-modules/terraform-aws-eks
+
+theme:
+  name: material
+  logo: assets/terraform-aws.png
+  favicon: assets/logo.png
+  font:
+    text: ember
+  palette:
+    primary: deep purple
+    accent: indgo
+  icon:
+    repo: fontawesome/brands/github
+    admonition:
+      note: octicons/tag-16
+      abstract: octicons/checklist-16
+      info: octicons/info-16
+      tip: octicons/squirrel-16
+      success: octicons/check-16
+      question: octicons/question-16
+      warning: octicons/alert-16
+      failure: octicons/x-circle-16
+      danger: octicons/zap-16
+      bug: octicons/bug-16
+      example: octicons/beaker-16
+      quote: octicons/quote-16
+  features:
+    - navigation.tabs.sticky
+  highlightjs: true
+  hljs_languages:
+    - yaml
+    - json
+
+plugins:
+  - include-markdown
+  - search:
+      lang:
+        - en
+  - awesome-pages
+
+extra:
+  version:
+    provider: mike
+
+markdown_extensions:
+  - attr_list
+  - admonition
+  - codehilite
+  - footnotes
+  - md_in_html
+  - pymdownx.critic
+  - pymdownx.details
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - toc:
+      permalink: true