GitHub action to build repositories Markdown files using the slate framework
Table of Contents
The docker image can be used to locally build your markdown files. For this you need, first of all, to build the docker image:
docker build -t decathlon/slate-builder .
Once built run the container using the following command:
docker run -it --rm -v <md files folder>:/usr/src/doc decathlon/slate-builder
The slate build result will be stored into the build subdir of <md files folder>
.
Create a file into your root project directory: .github/workflows/slate-builder-action.yml:
on: push
name: Create Slate Documentation on Push
jobs:
slate-documentation:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@master
- name: Build documentation
uses: docker:https://decathlon/slate-builder-action:2.0.0
env:
DOC_BASE_FOLDER = "."
The DOC_BASE_FOLDER
environement variable is the path, in your gitHub repository, containing the Markdown files you want to build as Slate website.
You can override the default Slate template, providing a repository containing your custom slate template.
on: push
name: Create Slate Documentation on Push
jobs:
slate-documentation:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@master
- name: Build documentation
uses: docker:https://decathlon/slate-builder-action:2.0.0
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
DOC_BASE_FOLDER = "."
TEMPLATE_REPO = "decathlon/custom-slate"
The GITHUB_TOKEN
secrets variable contains the Private Access Token. This secret is mandatory if you want to access to a private repository but you can leave it empty if the template you want to use is opensource.
The result is built into DOC_BASE_FOLDER/build
folder. You have to chain this action with one taking care about deployment, delivery, or whatever you want to do with your built documentation.
To simplify the export, the result is zipped into DOC_BASE_FOLDER/documentation.zip
. You can disable the zipping function providing ZIP_BUILD=false
as environment variable.
on: push
name: Create Slate Documentation on Push
jobs:
slate-documentation:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@master
- name: Build documentation
uses: docker:https://decathlon/slate-builder-action:2.0.0
env:
DOC_BASE_FOLDER = "."
ZIP_BUILD = "false"
Ih this example the workflow is started if we are on the master
branch and an md
file is delivered. In this case:
- the documention is built
- the new version is deployed as GitHub Pages
on: push
name: Create Slate Documentation on Push
jobs:
action-filter:
runs-on: ubuntu-18.04
steps:
- uses: actions/checkout@master
- name: action-filter
uses: actions/bin/filter@master
with:
args: branch master
- name: files-filter
uses: wcchristian/gh-pattern-filter-action@master
with:
args: .*\\.md$
- name: Build documentation
uses: docker:https://decathlon/slate-builder-action:2.0.0
env:
DOC_BASE_FOLDER: .
ZIP_BUILD: false
- name: Deploy to GitHub Pages
uses: docker:https://maxheld83/[email protected]
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BUILD_DIR: test-documentation/build/