HOWTO mkdocs


 flowchart LR

   A[create folder structure] --> B[setup mkdocs.yml]
   B --> C[add pages to mkdocsn]
   C --> D[customize mkdoc]
   D--> E[update gitlab-ci.yml CI/CD]

Setup

install Mkdocs and materials
```
pip install mkdocs-material
```
create mkdocs structure

project/
┣ EN/
┃ ┣ docs/
┃ ┃ ┣ assets/
┃ ┃ ┃ ┗ ..images..png
┃ ┃ ┣ overrides/
┃ ┃ ┃ ┗ partials/
┃ ┃ ┣ stylesheets/
┃ ┃ ┃ ┗ extra.css
┃ ┃ ┣ ...pages..md
┃ ┗ mkdocs.yml
┗ FR/
  ┣ docs/
  ┣ ...pages..md
  ┗ mkdocs.yml

setup config in mkdocs.yml file

site_name: OBikio
site_dir: 'public/' # target dir for build
docs_dir: './docs'
nav:
  - Home: index.md
  - Nav-title: {{file_name.md}}
theme: material
  features:
  - content.{{option}}
  - navigation.{{option}}
  - ...
  palette:
    scheme: obikio

plugins:
        - ...

markdown_extensions:
  - ...
extra_css:
  - stylesheets/extra.css

3. run a local copy

  # run mkdocs on local port
  mkdocs server

Customize

change color theme

create a docs/stylesheets/extra.css to add a themen
add a new css shema with css directives

  # css
  [data-md-color-scheme="{{palette-name}}"] {
    --md-primary-bg-color:        #022e4b;
    --md-primary-fg-color:        #aac5bc;
  }

3. add palette to mkdocs.yml

theme:
  palette:
    scheme: {{palette-name}}
extra_css:
  - stylesheets/extra.css

4.change icon

theme:
  logo: assets/logo.png

deploy site from gitlab

update gitlab.gitlab-ci.yml to generate and upload site

stages :
    - build-doc

variables:
  SITE_DIR: "./docs/project/EN" # EN folder for src doc
  MKDOCS_CONFIG_FILE: "$SITE_DIR/mkdocs.yml" 
  SITE_GENERATED_DIR: "./public" #   folder for target
  ARTIFACTS_DIR: "public" # folder for site transfer

image: python:3.8-buster ## MkDocs requies python.

build-doc:
  stage: build-doc
  before_script:
    - pip install mkdocs ## install MkDocs.
    - pip install mkdocs-material ## install the theme.
  rules:
    - changes:
      - docs/project/**/**/**


  script:
    - echo "Building MkDocs site..."
    - mv -v $SITE_DIR/$ARTIFACTS_DIR/* $ARTIFACTS_DIR 
  artifacts:
    paths:
      - $ARTIFACTS_DIR

Ressources - https://www.younup.fr/blog/demystifier-gitlab-ci-cd (French) - https://squidfunk.github.io/mkdocs-material/setup/