Skip to content
Commit f6c40ca3 authored by Lingkai Dong's avatar Lingkai Dong
Browse files

mkdocs: Introduce a plugin to convert file links to GitLab links



In plain markdown, a link can be a relative path to another local file
which may not necessarily be another markdown page. For example, the
Open IoT SDK documentation contains links to C code and CMakeLists.txt
files. This is not an issue when viewing markdown pages directly in
the GitLab repository, but when MkDocs converts the markdown pages into
HTML pages, non-page links in HTML usually become broken because they
are not part of the website.

To fix this, this commit introduces a plugin for MkDocs to convert non-
page file links into full URLs in the Open IoT SDK's GitLab repository.
A GitLab URL consists of the following parts:
* the project's base HTTPS URL
* the sha1 for which the documentation website is built
* the path to the linked file

The first two parts are by default taken from GitLab CI's predefined
environment variables `CI_PROJECT_URL` and `CI_COMMIT_SHA`. If those
variables are unset (e.g. when running MkDocs on a local machine), then
the plugin attempts to get the information from the local git
repository.

Signed-off-by: Lingkai Dong's avatarLingkai Dong <lingkai.dong@arm.com>
parent 8d2cc258
Loading
Loading
Loading
Loading
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment