Documentation Deployment Guide¶

This guide explains how to integrate your project's documentation into the centralized MkDocs system using GitLab CI/CD and how to test your changes locally.

1. Local Development & Testing¶

You can preview your documentation locally using the provided containerized environment. This ensures your Markdown and plugins (glightbox, mermaid2) render correctly before pushing to GitLab.

Running with Podman/Docker¶

To test your documentation locally, you must use the standard docker-compose configuration available in the DevOps MkDocs Repository.

Download the docker-compose.yml file from the link above and place it in your project root.
Configure the Mount: Open the file and locate the volumes section. You must update the left side of the path to point to your local documentation folder (e.g., src or docs).
```
volumes:
  - ./src:/docs/docs  <-- CHANGE "./src" to your actual folder name
  - ./mkdocs.yml:/docs/mkdocs.yml
```
Run the server:
```
podman-compose up --build
```

The documentation will be accessible at: http://localhost:8000

What this does: * Builds a custom image with glightbox and mermaid2 plugins pre-installed. * Mounts your local mkdocs.yml and documentation source folder into the container. * Serves the site at http://localhost:8000 with live-reloading enabled.

2. Central Registration (Pull Configuration)¶

To include your documentation in the global build, you must register your project in the central repository's configuration by opening a Merge Request (MR).

File to Edit: https://gitlab.fftrader.cz/devops/mkdocs/-/blob/main/.gitlab-ci.yml

Matrix Configuration Example¶

Locate the pull_docs job (around line 12) and add your project to the parallel: matrix section:

pull_docs:
  stage: pull
  parallel:
    matrix:
      - TEAM: "Cloud-Platform"        # Your team name
        PROJECT: "docs"               # Your project name
        PROJECT_PATH: "devops/docs"   # Full path to the GitLab repository
        DROP_MODE: "team"             # Options: "team" or "project" (see below)

Understanding DROP_MODE¶

project: The system creates a dedicated subfolder named after your project. Your documentation will be accessible under that subfolder.
team: The documentation is copied directly under the team folder, omitting a project-specific subfolder.

3. Local Project Setup (Publish Job)¶

In your individual repository, add the following CI/CD job to your .gitlab-ci.yml file. This job prepares and exports your Markdown files to the central system.

CI/CD Snippet¶

include:
  - project: 'devops/cicd-components/gitlab-templates'
    file: 'publish_mkdocs.yml'

stages:
  - publish_docs

publish_mkdocs:
  extends: .publish_mkdocs
  stage: publish_docs
  rules:
    - if: $CI_COMMIT_BRANCH == "main"  # Only runs on the main branch
  before_script:
    - echo "Preparing mkdocs_export from documentation/docs/cloud-platform-team"
    - rm -rf mkdocs_export
    - mkdir -p mkdocs_export
    - # Copy your source Markdown files into the required export folder
    - cp -r documentation/docs/cloud-platform-team/. mkdocs_export/

4. Mandatory Requirements & Best Practices¶

To ensure a successful deployment, you must follow these specific rules:

[!CAUTION] Job Naming: The job name must remain publish_mkdocs. While you are free to name the stage whatever you like, the central pipeline automation is hardcoded to look for a job named publish_mkdocs.

The `mkdocs_export` Workflow¶

The deployment logic specifically targets a folder named mkdocs_export.

Creation: Always run mkdir -p mkdocs_export in your before_script.
Cleaning: It is best practice to run rm -rf mkdocs_export before creation to ensure a clean build without artifacts from previous runs.
Populating: Only the content inside mkdocs_export/ will be synchronized to the central site. Make sure you copy all .md files or your desired folder structure into this directory.