diff --git a/README.md b/README.md index e339606..968c380 100644 --- a/README.md +++ b/README.md @@ -29,24 +29,22 @@ Project directory structure pattern: └── requirements.txt # Python requirements file to install MkDocs and MkDocs Plugins ``` -MkDocs provides local hot reload transpiling of Markdown files feature. There is a [Makefile](/Makefile) with this shortcut: +MkDocs provides local hot reload static files build. There is a [Makefile](/Makefile) with this shortcut: ```bash -$ 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 +$ 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/ ## Manual Configurations -### 1. Replace the `mkdocs.yml` +### 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 +### 2. Configure the GitHub Action Permissions The [.github/workflows/deploy-contents-to-github-pages.yml](.github/workflows/deploy-contents-to-github-pages.yml) pipeline need the `${{ secrets.GITHUB_TOKEN }}` variable to allow the static files push in `gh-pages` branch. For this, it is necessary to configure the _Read Write_ permission for GitHub action. Check the following image to configure it. @@ -60,7 +58,7 @@ The [.github/workflows/deploy-contents-to-github-pages.yml](.github/workflows/de ### 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) 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. +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. ![](./.img/how-to-configure-git-pages.png)