docs(mkdocs): moved to pages folder

!25
2023-05-21 15:41:05 +09:30
parent 70dfb826d1
commit 1ec2666e85
1 changed files with 0 additions and 0 deletions
--- a/pages/projects/gitlab-ci/mkdocs-build.md
+++ b/pages/projects/gitlab-ci/mkdocs-build.md
@ -0,0 +1,58 @@
+# 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)