59 lines
1.9 KiB
Markdown
59 lines
1.9 KiB
Markdown
# MKDocs Static Site Build
|
|
Build a MKDocs site from the config specified in `mkdocs.yml`. _Only runs if `mkdocs.yml` exists in the repository root directory._ This job is designated to run on all branchs so that you can use the artifacts for deployment to `staging` and/or `production` as required.
|
|
|
|
This job provides the following badge:
|
|
|
|
- _None_
|
|
|
|
## Dependencies
|
|
|
|
- **Mandatory** file `mkdocs.yml` in the repository root directory with your MKDocs configuration
|
|
|
|
## your .gitlab-ci.yml changes
|
|
To use this job add the following to your `.gitlab-ci.yml` file
|
|
|
|
``` yaml
|
|
stages:
|
|
- build
|
|
|
|
include:
|
|
- local: CI/build/.gitlab-ci.yml
|
|
|
|
MKDocs build:
|
|
variables:
|
|
MKDOCS_BUILD_PATH: "build"
|
|
extends:
|
|
- .MKDocs_Build
|
|
|
|
```
|
|
|
|
## CI/CD Variables required
|
|
|
|
| var name | Description |
|
|
|:----:|:----|
|
|
| MKDOCS_BUILD_PATH | **Mandatory, if different from default** The path where MKDocs places the build files. Defaults to `build` |
|
|
| MKDOCS_INCLUDE_SOURCE | **Optional** Include the build source files in the artifacts. Default is Not set. Any value in this variable, will include the source files. |
|
|
| MKDOCS_SOURCE_PATH | **Optional, if source files are not to be included** Set to the path where mkdocs uses to build the static html. |
|
|
|
|
## Job Workflow
|
|
|
|
1. install mkdocs
|
|
|
|
1. if file `requirements.txt` exists in the repository root directory, use this fill to also install additional dependencies.
|
|
|
|
1. if no `requirements.txt` file exists, only install mkdocs.
|
|
|
|
1. run mkdocs to build the static pages
|
|
|
|
1. if variable `$MKDOCS_INCLUDE_SOURCE` is set, then copy `$MKDOCS_SOURCE_PATH` to the artifacts location.
|
|
|
|
1. copy directory `$MKDOCS_BUILD_PATH` to the artifacts location.
|
|
|
|
|
|
## Artifacts
|
|
|
|
- files in `"$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME"`
|
|
|
|
## License
|
|
To view the license for this folder and any sub-folders, refer [here](https://gitlab.com/nofusscomputing/projects/gitlab-ci)
|