diff --git a/.github/workflows/deploy-contents-to-github-pages.yml b/.github/workflows/deploy-contents-to-github-pages.yml new file mode 100644 index 0000000..4a511b0 --- /dev/null +++ b/.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 }} diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bc4b8ed --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +venv/ +site/ \ No newline at end of file diff --git a/.img/how-to-configure-git-actions.png b/.img/how-to-configure-git-actions.png new file mode 100644 index 0000000..3804321 Binary files /dev/null and b/.img/how-to-configure-git-actions.png differ diff --git a/.img/how-to-configure-git-pages.png b/.img/how-to-configure-git-pages.png new file mode 100644 index 0000000..8ab8cc6 Binary files /dev/null and b/.img/how-to-configure-git-pages.png differ diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..4133443 --- /dev/null +++ b/Makefile @@ -0,0 +1,6 @@ +setup: + python -m venv venv + venv/bin/pip3 install -r requirements.txt + +serve: + venv/bin/mkdocs serve diff --git a/README.md b/README.md new file mode 100644 index 0000000..e59cf0f --- /dev/null +++ b/README.md @@ -0,0 +1,75 @@ +> [!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/ + +## 📝 Project Structure Definition + +The directory structure outlined below serves as the blueprint for organizing Markdown files, which are utilized in the configuration of the [mkdocs.yml](/mkdocs.yml) file to construct documentation comprising distinct sections and subsections. + +```bash +├── docs # Directory containing Mkdocs content files +│ ├── index.md # Main page of the site +│ ├──
.md # Markdown files representing individual sections and subsections +│ └── img # Directory for image assets +│ └── -.* # Naming convention for images +├── Makefile # Script for setting up a local Mkdocs web server +├── mkdocs.yml # Manifest file for MkDocs configuration +└── requirements.txt # File listing Python requirements necessary for installing MkDocs and its plugins +``` + +This structure ensures systematic organization of documentation files, facilitating easy navigation and maintenance. Additionally, it provides clarity on the purpose and location of each file within the project. + +## ⚒️ Local Tests Setup + +Use the [Makefile](/Makefile) shortcuts to install the MkDocs dependencies and provide local web server with hot reload feature. + +```bash +$ make setup # create python3 virtualenv and install requirements (MkDocs and MkDocs plugins) +$ make run # run local web server with hot reload feature +``` + +> [!NOTE] +> 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 repository properties (project URL, site name, author, etc). + +### 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 in the Repository settings. This is necessary for the GitHub Action to create a branch and publish the built files. Check the following image for the configuration steps. + +
+ Image +
+ +### 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. + +
+ Image +
+ +## :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.io//` + +> [!NOTE] +> `` and `` are placeholders. Replace with your properties. diff --git a/docs/01-page-first.md b/docs/01-page-first.md new file mode 100644 index 0000000..670cf87 --- /dev/null +++ b/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. diff --git a/docs/02-page-second.md b/docs/02-page-second.md new file mode 100644 index 0000000..5ca83f3 --- /dev/null +++ b/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. diff --git a/docs/img/logo-here.png b/docs/img/logo-here.png new file mode 100644 index 0000000..6f78131 Binary files /dev/null and b/docs/img/logo-here.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..4ec767a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,11 @@ +# Welcome to my documentation page! + +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](./02-page-second/) +> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean ultrices, nisi id tincidunt sagittis, purus orci tincidunt tortor. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..d52ee7f --- /dev/null +++ b/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 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..ac83e80 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +mkdocs +mkdocs-toc-sidebar-plugin +mkdocs-material +git+https://github.com/carlosperate/mkdocs-awesome-list-plugin