mkdocs

Om van markdown bestanden makkelijk een website te kunnen maken zijn er meerdere tools beschikbaar. Een van deze tools is mkdocs.

mkdocs is gebaseerd op Python en als je het hebt geïnstalleerd kan je het gebruiken vanaf de commandline.

graph LR
    A[Markdown\nbestanden] --> B[mkdocs]
    B --> C[Website]

Installatie

Om mkdocs te kunnen gebruiken moet je het eerst installeren. Je kunt mkdocs installeren met behulp van pip. pip is de package manager van Python.

Let op

pip is de package manager van Python. Als je Python installeert, dan wordt pip automatisch mee geïnstalleerd. Als je Python installeert via de Python website, dan moet je tijdens de installatie aangeven dat je pip wilt installeren.

Je kunt mkdocs installeren met behulp van het volgende commando:

pip install mkdocs-material

Een nieuwe website maken

Als je mkdocs hebt geïnstalleerd, dan kun je een nieuwe website maken met behulp van het volgende commando:

mkdocs new mijnwebsite

Dit commando maakt een nieuwe map aan met de naam mijnwebsite. In deze map staan een aantal bestanden. De belangrijkste bestanden zijn:

• mkdocs.yml: Dit is het configuratie bestand van de website. Hierin kun je instellen hoe de website eruit ziet en welke bestanden er worden gebruikt.
• docs/index.md: Dit is het markdown bestand waarin de inhoud van de website staat.

De website lokaal bekijken

Als je een nieuwe website hebt gemaakt, dan kun je deze lokaal bekijken met behulp van het volgende commando:

mkdocs serve

Dit commando start een lokale webserver. Je kunt de website bekijken door naar http://localhost:8000 te gaan.

Oefening: Oefenen met mkdocs

• Maak een nieuwe website met behulp van mkdocs.
• Start de lokale webserver.
• Pas de inhoud van de website aan.
• Pas de configuratie van de website aan.
• Stop de lokale webserver.

De website publiceren met gitlab

Je kan je documentatie website ook publiceren in gitlab. Dit kan je doen door de volgende stappen te volgen:

• maak in je repository een bestand genaamd requirements.txt met de volgende inhoud:

  requirements.txt

  mkdocs ~= 1.4.0
  Jinja2==3.1.0
  mkdocs-material ~= 9.1.12
  mkdocs-video ~= 1.3
  mkdocs-mermaid2-plugin ~= 0.6.0
  mkdocs-macros-plugin ~= 0.7.0
  mkdocs-awesome-pages-plugin ~= 2.8.0
  mkdocs-autolinks-plugin ~= 0.6.0
  mkdocs-section-index ~= 0.3.5
  gitpython ~= 3.1.27
  

• maak ook een bestand genaamd mkdocs.yml met de volgende inhoud:

  mkdocs.yml

  site_name: SE Portfolio
  site_description: HBO-ICT Software Engineering Portfolio
  site_author: HBO-ICT
  copyright: Copyright 2023 Hogeschool van Amsterdam
  
  theme:
      name: material
      features:
          - navigation.sections
          - content.tabs.link
  
  plugins:
      - search
      - mermaid2
      - awesome-pages
      - mkdocs-video
      - section-index
      - autolinks
  

• maak een bestand genaamd .gitlab-ci.yml met de volgende inhoud:

  .gitlab-ci.yml

  image: python:3.9-slim
  
  before_script:
  - time apt update
  - time pip install -r requirements.txt
  - time cd mdocotion && python setup.py install && cd ..
  
  pages:
  stage: deploy
  tags:
      - hva
  script:
      - time mkdocs build --site-dir public
  artifacts:
      paths:
      - public
  rules:
      - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  
  variables:
  GIT_SUBMODULE_STRATEGY: recursive
  

  Bestaande “.gitlab-cy.yml

  Als je al bestaande .gitlab-ci.yml bestand hebt, dan moet je de inhoud van het bestand hierboven samenvoegen aan je bestaande .gitlab-ci.yml bestand.

• maak een map aan met de naam docs en zet hier je markdown bestanden in.

• commit en push je wijzigingen naar gitlab.
• je kan je website vinden via deploy -> pages in je gitlab repository.