Skip to content

Uppsetning MkDocs á GitLab pages

Gitlab býður upp á hýsingu á kyrrum síðum í gegnum CI/CD kerfið þeirra. Í grófum dráttum er þetta ferlið:

  • Kóði er skrifaður í git-lind og ýtt upp til gitlab
  • GitLab hendir upp docker gámi og keyrir vefsíðuna

Gert er ráð fyrir að GitLab aðgangur sé til staðar og tómt verkefni hafi verið stofnað, köllum það pages.

Klónum lindina og setjum upp python umhverfi

Git lind klónuð:

$ git clone git@gitlab.com:$user/pages

Gerum python umhverfi:

$ pip install virtualenv  
$ virtualenv pypages
$ source pypages/bin/activate

Eins og python er ĺíkt þurfum við að setja upp skrilljón pakka til að þetta virki:

$ pip install -r reqs.txt

Þar sem req.txt inniheldur

Jinja2
joblib
jsmin
livereload
lunr
Markdown
MarkupSafe
mkdocs
mkdocs-awesome-pages-plugin
mkdocs-git-revision-date-localized-plugin
mkdocs-material
mkdocs-material-extensions
mkdocs-minify-plugin
nltk
Pygments
pymdown-extensions
pytz
PyYAML
regex
six
smmap
tornado
tqdm

Eftir að þetta hefur vonandi keyrt án vandkvæða getum við stofnað verkefnið:

$ mkdocs new .

Við ættum þá að hafa möppu docs og stillingaskrá mkdocs.yaml. Ef við þurfum að keyra fleiri MkDocs skipanir beint af þjóninum eftir þetta þarf að virkja python umhverfið fyrst.

CI/CD Sett upp

Byrjum á því að gera skrá sem lýsir starfsemi pípunnar, hún þarf að vera í rót lindarinnar og heita .gitlab_ci.yml. Hún inniheldur:

# Skilgreiningin á stiginu
stages:
  - deploy

# Þetta þarf að heita pages til að virka sem síða
pages:
  stage: deploy
  image:
    # Sækjum tilbúna docker mynd, þetta er sótt frá Docker Hub
    name: squidfunk/mkdocs-material
    # Myndin er smá og hefur enga skel, setjum entrypoint="" til að reyna ekki að búa til óþarfa skel
    entrypoint:
      - ""
  # Skipunin sem býr til síðuna, setjum allt í möppu sem heitir public, hana þarf að búa til,
  # en skrárnar fyrir síðuna þurfa að vera í möppu í rót lindarinnar sem heitir public.
  script:
    - mkdocs build -d public
  artifacts:
    # Tilgreinum möppuna sem við erum að vinna með
    paths:
      - public
  # Keyrum bara þegar main er uppfært
  only:
    - main
  # Snýr að 'runnerum'
  tags:
    - docs

Nú þurfum við Runner, en það er það sem sér um CI/CD pípuna. Við keyrum það með Docker, byrjum á að skilgreina disk fyrir stilliskrárnar:

$ docker volume create gitlab-runner-config

Hendum í Docker gám fyrir runner-inn: 

$ docker run -d --name gitlab-runner --restart always \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v gitlab-runner-config:/etc/gitlab-runner \
    gitlab/gitlab-runner:latest

Við þurfum að skrá runner-inn okkar og tengja hann við verkefnið okkar, tókann má fá undir Lind -> Settings -> CI/CD -> Runners

$ docker run --rm -it -v gitlab-runner-config:/etc/gitlab-runner gitlab/gitlab-runner:latest register

Nú koma nokkrar spurningar, látum URL-ið vera https://gitlab.com/ og Registration Token er tókinn úr stillingunum, setjið inn góða lýsingu og verið viss um að setja docs sem merkingu (e. tag). Executor skal vera docker. Default Docker Image má vera hvað sem er, ég setti ubuntu:22.04.

Byrjum að skrifa leiðbeiningar!

Breytum fyrst þemanu með því að hafa eftirfarandi til staðar í mkdocs.yaml:

theme: 
    name: material
    palette:
        # Dark mode
        scheme: slate
        primary: dark grey
        accent: amber

Fyrir hverja síðu gerum við svo síða1.md undir docs möppunni. Staðfestum og hlöðum upp:

$ git add .
$ git commit -a -m "skrifaði mikið"
$ git push origin main

Við seinustu skipunina fer pípan í gang, það má fylgjast með henni undir CI/CD -> Pipelines í verkefninu. Eftir þá keyrslu ætti síðan að vera aðgengileg undir https://{notandi}.gitlab.io/{lind}/gitlab_pages.