diff --git a/Makefile b/Makefile index b341915..4133443 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ -venv: - virtualenv -q venv +setup: + python -m venv venv venv/bin/pip3 install -r requirements.txt serve: diff --git a/README.md b/README.md index d8ffed4..199c00e 100644 --- a/README.md +++ b/README.md @@ -1,65 +1,71 @@ +> [!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 to make a web page with: Mkdocs + GitHub Pages. +Template repository for provisioning a document repository with the happiness combo: __Mkdocs__ + __Github Actions__ + __GitHub Pages__. -The content is written in the Markdown file format. Each commit and push on `main` branch trigger a _GitHub Action_ that transpile Markdown files to modern web static files with MkDocs and provides via 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: +Check the web content that your page will reach when you use this template: - https://c-neto.github.io/template-gh-pages-mkdocs/ ## Directory Structure -Project directories structure pattern: +Project directory structure pattern: -```shell -. -├── docs # parente directory of the contents files +```bash +├── docs # Mkdocs content files │ ├── index.md # first site page -| ├──
.md # files separate by subsections according +│ ├──
.md # files separated by subsections according │ └── img # image assets directories │ └── -.* -├── Makefile # scripts to create local mkdocs web server +├── Makefile # scripts to create local Mkdocs web server ├── mkdocs.yml # MkDocs manifest file -└── requirements.txt # python requirements file to install MkDocs and MkDocs Plugins +└── requirements.txt # Python requirements file to install MkDocs and MkDocs Plugins ``` -MkDocs provides local hot reload transpile Markdown files feature. For to configure this feature, install `make` and `python3-virtualenv` and run: +MkDocs provides local hot reload transpiling of Markdown files feature. There is a [Makefile](/Makefile) with this shortcut: ```bash -$ git clone https://github.com/augustoliks/aws-mini-book -$ cd aws-mini-book/ -$ make venv # create python3 virtualenv and install requirements (MkDocs and MkDocs plugins) -$ make serve # run local web server with hot reload feature +$ git clone https://github.com/augustoliks/template-gh-pages-mkdocs +$ cd template-gh-pages-mkdocs +$ make setup # create python3 virtualenv and install requirements (MkDocs and MkDocs plugins) +$ make serve # run local web server with hot reload feature ``` -If the commands above were run with successful, the web content will be accessible: http://127.0.0.1:8000/ +If the commands above were run successfully, the web content will be accessible: http://127.0.0.1:8000/ ## Manual Configurations ### 1. Replace the `mkdocs.yml` -Replace the all variables under `>>> REPLACE THE VALUE` in the [./mkdocs.yml](./mkdocs.yml) with values based on your repo. +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) use the `${{ secrets.GITHUB_TOKEN }}` variable to perform the push of the `gh-pages` branch. For this, it is necessary configure the Read Write permission for GitHub action. Check the following print to configure it. +The [/.github/workflows/deploy-contents-to-github-pages.yml](.github/workflows/deploy-contents-to-github-pages.yml) uses the `${{ secrets.GITHUB_TOKEN }}` variable to push the static files to the `gh-pages` branch. For this, it is necessary to configure the _Read Write_ permission for GitHub action. Check the following image to configure it. -![](./.img/how-to-configure-git-actions.png) - ---- + + + + +
![](./.img/how-to-configure-git-actions.png)
### 3. Enable GitHub Pages Feature -Now, it is necessary configure the GitHub Pages. The GitHub Action [/.github/workflows/deploy-contents-to-github-pages.yml](.github/workflows/deploy-contents-to-github-pages.yml) create a `gh-pages` branch with the static file of the Mkdocs transpilation. Thus, you must configure the GitHub Pages to use the branch `gh-pages` as a source to render the web files. - +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) 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. ![](./.img/how-to-configure-git-pages.png) - ## Where is my GitHub Page Link? -If you correctly configured your repo, the link will be able in the following pattern: +If you have correctly configured your repo, the link will be available in the following pattern: - `https://.github.io//` -> Replace `` and `` based on needs. +> Replace `` and `` based on your needs.