Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/afritzler/mkdocs-gh-pages-action
Github Action to build and release mkdocs as Github Pages
https://github.com/afritzler/mkdocs-gh-pages-action
docs gh-pages github-actions github-enterprise github-page mkdocs mkdocs-material release-mkdocs
Last synced: about 2 months ago
JSON representation
Github Action to build and release mkdocs as Github Pages
- Host: GitHub
- URL: https://github.com/afritzler/mkdocs-gh-pages-action
- Owner: afritzler
- License: mit
- Created: 2021-03-10T15:15:57.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-01T11:55:40.000Z (2 months ago)
- Last Synced: 2024-11-01T12:29:01.868Z (2 months ago)
- Topics: docs, gh-pages, github-actions, github-enterprise, github-page, mkdocs, mkdocs-material, release-mkdocs
- Language: Shell
- Homepage: https://github.com/marketplace/actions/mkdocs-github-pages-releaser
- Size: 205 KB
- Stars: 4
- Watchers: 4
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# mkdocs-gh-pages-action
Github Action to build and release mkdocs as Github pages without using Docker.
At the core this action is using the [Mkdocs Material](https://squidfunk.github.io/mkdocs-material/) project
to build your documentation.
## Why?
There are already a couple of great Github actions out there building your mkdocs project
and publishing it as Github pages such as
*
This project aims to provide a Github action without using a Docker container in the build
and publishing step. It comes handy for people running in a Github Enterprise environment using
`self-hosted` runners which don't have Docker-in-Docker support enabled.
## Usage
Here is an example on how to use this action to publish your project:
```yaml
name: Publish docs via GitHub Pages
on:
push:
branches: [ main ]
jobs:
build:
name: Deploy docs
runs-on: ubuntu-latest
steps:
- name: Checkout main
uses: actions/checkout@v2
- uses: actions/setup-python@v2
with:
python-version: 'pypy-3.6'
- name: Deploy docs
uses: afritzler/mkdocs-gh-pages-action@main
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
#GITHUB_DOMAIN: github.myenterprise.com
```
## Configuration
This action can be configured by setting the following `env` varibles
| **ENV VAR** | **Default Value** | **Notes** |
| ------------------ | --------------------- | ------------------------------------------------------------------------------------------------- |
| **CUSTOM_DOMAIN** | `none` | Custom domain name which is being written into the CNAME file of your gh-pages branch. |
| **CONFIG_FILE** | `mkdocs.yml` | Custom Mkdocs configuration file relative in your project folder structure. |
| **GITHUB_TOKEN** | `none` | Personal Github token which should be used during execution. |
| **PERSONAL_TOKEN** | `none` | Personal access token which should be used during execution. |
| **GITHUB_DOMAIN** | `github.com` | Specify a custom Github domain in case Github Enterprise is used: e.g. `github.myenterprise.com`. |
| **ACTOR** | `author of PR/commit` | Overwrite the author of the PR/commit. |
| **REQUIREMENTS** | `requirements.txt` | Specify a custom `requirements.txt` file to use custom Python modules. |
| **FORCE** | `"true"` | Force defines if the `mkdocs` build artefacts should be force pushed into the `gh-pages` |
## Using custom modules
By default this action is looking for the presents of a `requirements.txt` in your project to install your custom modules.
Example: Lets say you want to install the following modules as they represent Mkdocs plugins used by your project:
```shell
mkdocs-same-dir==v0.1.0
mdx_truly_sane_lists==1.2
```
Create a corresponding file containing a versioned list of those modules (`pip freeze`). You can override the default filename `requirements.txt` by
setting the `REQUIREMENTS` environment variable.
```yaml
- name: Deploy docs
uses: afritzler/mkdocs-gh-pages-action@main
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
REQUIREMENTS: myawesome-requirements.txt
```