Overview

This Gitlab CI Component is designed to use Material MkDocs to facilitate documentation generation.

Currently this component supports the following mkdocs plugins, as taken from the requirements.txt.

mkdocs
mkdocs-material
mkdocs-git-revision-date-plugin
mkdocs-gen-files
mkdocs-encryptcontent-plugin
mkdocs-simple-hooks

Specification

spec:
  inputs:
    build-docs-stage:
      default: "build" # Optional, defaults to "build" 
    docs-url:
      default: "" # Required
    docs-deploy-command:
      default: "npm run docs-deploy" # Optional, defaults to "npm run docs-deploy"  
    docs-build-command:
      default: "npm run docs-build" # Optional, defaults to "npm run docs-build"
    run-build-and-deploy-override:
      default: "manual" # Optional, options: [ "never", "always", "manual" ] defaults to "manual"
    rule:
      default: $CI_COMMIT_BRANCH == "main" && $CI_PIPELINE_SOURCE != "merge_request_event"  # Optional, defaults push events to main branch      

Usage

A basic usage may look like the following

include:
  - component: gitlab.futurehax.com/ci-components/mk-docs@~latest
    inputs:
      docs-url: "https://docs.futurehax.com/projects/ci-comp-mkdocs" # Required
      docs-build-command:  "npm run docs-build" # Optional, defaults to "npm run docs-build"
      docs-deploy-command: "npm run docs-deploy" # Optional, defaults to "npm run docs-deploy"  

See .gitlab-ci.yml for a full example.

The full documentation can be found online on the documentation server.

---

Last update: 2023-10-31