Skip to content

Add Lychee to Markdown linting image for link checking

What does this MR do and why?

For: technical-writing#979, before we can use Lychee to check for broken links, we need a Docker image with the checker.

There are alternatives to this including:

However, the method of loading up an Docker image with Lychee represents an MVC as we continue discussing how we want to approach Docker images in the future: #1758.

How to set up and validate locally

Numbered steps to set up and validate the change are strongly suggested.

  1. Configure a local GitLab Docs environment: https://gitlab.com/gitlab-org/gitlab-docs/-/blob/main/doc/setup.md.
  2. To build the Docker image, run: docker buildx build --file dockerfiles/gitlab-docs-lint-markdown.Dockerfile . --platform=linux/amd64 --build-arg="ALPINE_VERSION=3.19" --build-arg="VALE_VERSION=3.4.1" --build-arg="MARKDOWNLINT2_VERSION=0.13.0" --build-arg="LYCHEE_VERSION=0.14.3".
  3. Load the Docker image with: docker run --rm -it --platform=linux/amd64 <image SHA> bash
  4. To ensure that the Docker image can still support probably the most challenging job (https://gitlab.com/gitlab-org/gitlab/-/blob/55dd94a4c1c49303caf3a53dc756c46fcb9c7003/.gitlab/ci/docs.gitlab-ci.yml#L63), in the running Docker container:
    1. Run git clone https://gitlab.com/gitlab-org/gitlab.git.
    2. Run cd gitlab.
    3. Run source ./scripts/utils.sh && yarn_install_script && install_gitlab_gem (which feels like a very heavy process)
    4. Run scripts/lint-doc.sh.
    5. Run scripts/lint/check_mermaid.mjs.
    6. Run any other process you feel you should.

Merge request acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Evan Read

Merge request reports