Accessible content in GitLab
On this page
You write READMEs, wikis, issues and merge requests on gitlab.git.nrw yourself. Whether others can read them with a screen reader, strong magnification or without a mouse therefore depends mostly on you. The following tips apply to everything you write in GitLab with Markdown.
The vendor is responsible for the barriers of the GitLab interface itself. What we know about them is in the accessibility statement.
Headings in order
Screen readers jump through a document by its headings. Start with a first-level heading and do not skip a level. Use headings for structure, not for emphasis.
# Project name
## Installation
### Prerequisites
Images need alternative text
Describe in the square brackets what the image shows and what it is for. When you drag or paste an image into GitLab, GitLab inserts the file name as alternative text. Replace it with a description.
The first line says nothing, the second describes the content. If a screenshot shows code or an error message, add the text as a code block or replace the screenshot altogether.
Link texts that stand on their own
Many people have all links of a page read out as a list. “Here” or “link” means nothing there. Put the target into the link text.
The [installation guide](docs/install.md) describes all steps.
Tables for data only
Markdown tables always have a header row. Fill it with column names so that screen readers can assign each cell to its column. Do not use tables to place text side by side.
Never color alone
Many people can hardly tell red from green. Give labels a name that works without color, for example “bug” instead of only a red marker. In charts and graphics, add captions, patterns or symbols to the color.
Diagrams with a text description
Diagrams from Mermaid or PlantUML appear as graphics. Summarize in the text before or after what the diagram shows, for example the steps of a workflow as a list.
Videos and animated images
Videos with speech need captions. If the picture shows something the sound does not say, describe it in the text. Animated GIFs must not flash more than three times per second.
Websites with GitLab Pages
A website you publish with GitLab Pages is a website of its own. The same principles apply, plus contrast, keyboard operation and display on small screens. Whether it needs an accessibility statement of its own is a question for the responsible office at your university.
Found a barrier?
You can report barriers on gitlab.git.nrw or on this website through the contact form. You do not need a GitLab account.