project done!

.github/workflows/deploy-contents-to-github-pages.yml

@@ -0,0 +1,19 @@
+name: Github Pages
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip3 install -r requirements.txt
+      - run: mkdocs gh-deploy --force
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

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

Makefile

@@ -0,0 +1,6 @@
+setup:
+	python -m venv venv
+	venv/bin/pip3 install -r requirements.txt
+
+serve:
+	venv/bin/mkdocs serve       

README.md

@@ -0,0 +1,70 @@
+> [!WARNING]
+> __DO NOT FORK THIS PROJECT!__
+>
+> This project is meant to be used from [Use this template](https://github.com/c-neto/template-gh-pages-mkdocs/generate) feature.
+
+---
+
+# template-gh-pages-mkdocs
+
+Template repository for provisioning a document repository with the happiness combo: __MkDocs__ + __Github Actions__ + __GitHub Pages__.
+
+Each commit on the `main` branch triggers a [GitHub Action Pipeline](/.github/workflows/deploy-contents-to-github-pages.yml) that transpiles Markdown files to modern web static files with [MkDocs](https://github.com/mkdocs/mkdocs) and provides them via GitHub Pages.
+
+Check the web content that your page will reach when you use this template:
+- https://c-neto.github.io/template-gh-pages-mkdocs/
+
+## 📝 Document Structure Definition
+
+Project directory structure pattern:
+
+```bash
+├── docs                             # Mkdocs content files 
+│   ├── index.md                     # first site page
+│   ├── <SECTION>.md                 # files separated by subsections according
+│   └── img                          # image assets directories
+│       └── <SECTION-NUMBER-PREFIX>-<IMAGE-NAME>.*  
+├── Makefile                         # scripts to create local Mkdocs web server   
+├── mkdocs.yml                       # MkDocs manifest file
+└── requirements.txt                 # Python requirements file to install MkDocs and MkDocs Plugins
+```
+
+MkDocs provides local hot reload static files build. There is a [Makefile](/Makefile) with this shortcut:
+
+```bash
+$ make setup     # create python3 virtualenv and install requirements (MkDocs and MkDocs plugins)
+$ make run       # run local web server with hot reload feature
+```
+
+If the commands above were run successfully, the web content will be accessible: http://127.0.0.1:8000/
+
+## :gear: Repository Setup
+
+### 1. Configure the `mkdocs.yml` Parameters
+
+Replace all variables under `>>> REPLACE THE VALUE` in the [./mkdocs.yml](./mkdocs.yml) with values based on your repo.
+
+### 2. Configure the GitHub Action Permissions
+
+The [.github/workflows/deploy-contents-to-github-pages.yml](.github/workflows/deploy-contents-to-github-pages.yml) pipeline use the special variable `${{ secrets.GITHUB_TOKEN }}` to allow push action in the `gh-pages` branch. To achieve this, you need to configure the __Read Write__ permission for the GitHub action. This is necessary for the GitHub Action to create a branch and publish the built files. Check the following image for the configuration steps.
+
+<table style="margin: 0 auto;"> <tr> <td style="text-align: center;">
+  <img src="./.img/how-to-configure-git-actions.png" alt="Image" />
+</td> </tr> </table>
+
+### 3. Enable GitHub Pages Feature
+
+Now, it is necessary to configure GitHub Pages. The GitHub Action [.github/workflows/deploy-contents-to-github-pages.yml](.github/workflows/deploy-contents-to-github-pages.yml) pipeline creates a `gh-pages` branch with the static files transpiled by MkDocs. Thus, you need to configure GitHub Pages to use the `gh-pages` branch as a source to render the web files.
+
+<table style="margin: 0 auto;"> <tr> <td style="text-align: center;">
+  <img src="./.img/how-to-configure-git-pages.png" alt="Image" />
+</td> </tr> </table>
+
+## :rocket: Done! But... Where is my GitHub Page Link?
+
+If you have correctly configured your repo, the link will be available in the following pattern:
+
+- `https://<GITHUB-USERNAME>.github.io/<GITHUB-REPO>/`
+
+> [!NOTE]
+> `<GITHUB-USERNAME>` and `<GITHUB-REPO>` are placeholders. Replace with your properties.

docs/01-page-first.md

@@ -0,0 +1,25 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+
+### Section 1
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+
+### Section 2
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+
+#### Subsection
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+
+- Lorem ipsum dolor sit amet
+- Consectetur adipiscing elit
+- Sed do eiusmod tempor incididunt
+
+1. Lorem ipsum dolor sit amet
+2. Consectetur adipiscing elit
+3. Sed do eiusmod tempor incididunt
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+
+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.

docs/02-page-second.md

@@ -0,0 +1,27 @@
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+
+## Lorem Ipsum Example
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur commodo ultrices purus, a ullamcorper sapien blandit ac.
+
+- Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae;
+- Integer quis turpis ut nulla interdum efficitur nec in sem.
+- Sed a urna vel mi lobortis vehicula.
+
+### Section 1
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc vitae metus ac metus blandit ultricies vel a leo. 
+
+#### Subsection A
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce et turpis in tortor posuere facilisis nec sit amet justo.
+
+#### Subsection B
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec a tortor nec purus congue cursus.
+
+### Section 2
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed et felis sit amet nisl luctus malesuada. 
+
+> Lorem ipsum dolor sit amet, consectetur adipiscing elit.

docs/index.md

@@ -0,0 +1,11 @@
+# Welcome to `my-blog`
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras bibendum efficitur mi, et vehicula metus malesuada in :smile: :rocket:
+
+**Topics**
+
+- [01. Page First](./01-page-first/)
+> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur eu arcu vel sapien efficitur feugiat. 
+
+- [02. Page Second](./01-page-second/)
+> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean ultrices, nisi id tincidunt sagittis, purus orci tincidunt tortor.

mkdocs.yml

@@ -0,0 +1,67 @@
+# >>> REPLACE THE VALUE
+site_name: template-gh-pages-mkdocs
+
+# >>> REPLACE THE VALUE
+site_url: https://github.com/c-neto/template-gh-pages-mkdocs
+
+# >>> REPLACE THE VALUE
+site_description: template-gh-pages-mkdocs
+
+# >>> REPLACE THE VALUE
+site_author: Carlos Neto | @c-neto
+
+# >>> REPLACE THE VALUE
+repo_name: c-neto/template-gh-pages-mkdocs
+
+# >>> REPLACE THE VALUE
+repo_url: https://github.com/c-neto/template-gh-pages-mkdocs
+
+# >>> REPLACE THE VALUE
+edit_uri: ''
+
+# >>> REPLACE THE VALUE
+nav:
+  - template-gh-pages-mkdocs: index.md
+  - 01. Page First: 01-page-first.md
+  - 02. Page Second: 02-page-second.md
+
+theme:
+  language: en
+  name: material
+  logo: img/logo-here.png
+  favicon: img/logo-here.png
+  palette:
+    - scheme: default
+      primary: teal
+      accent: amber
+      toggle:
+        icon: material/lightbulb
+        name: Dark Mode
+    - scheme: slate
+      primary: teal
+      accent: amber
+      toggle:
+        icon: material/lightbulb-outline
+        name: Light Mode
+  features:
+    - search.suggest
+    - search.highlight
+    - navigation.top
+extra:
+  social:
+
+    - icon: fontawesome/brands/github-alt
+      # >>> REPLACE THE VALUE
+      link: https://github.com/c-neto
+
+    - icon: fontawesome/brands/linkedin
+      # >>> REPLACE THE VALUE
+      link: https://linkedin.com/in/c-neto
+
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - admonition
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg

requirements.txt

@@ -0,0 +1,4 @@
+mkdocs
+mkdocs-toc-sidebar-plugin
+mkdocs-material
+git+https://github.com/carlosperate/mkdocs-awesome-list-plugin