Folder structure for documentation
The documentation is separated by top-level audience folders user
,
administration
,
and development
(contributing) folders.
Beyond that, we primarily follow the structure of the GitLab user interface or API.
Our goal is to have a clear hierarchical structure with meaningful URLs like
docs.gitlab.com/user/project/merge_requests/
. With this pattern, you can
immediately tell that you are navigating to user-related documentation about
project features; specifically about merge requests. Our site’s paths match
those of our repository, so the clear structure also makes documentation easier
to update.
Put files for a specific product area into the related folder:
Directory | Contents |
---|---|
doc/user/ | Documentation for users. Anything that can be done in the GitLab user interface goes here, including usage of the /admin interface. |
doc/administration/ | Documentation that requires the user to have access to the server where GitLab is installed. Administrator settings in the GitLab user interface are under doc/administration/ . |
doc/api/ | Documentation for the API. |
doc/development/ | Documentation related to the development of GitLab, whether contributing code or documentation. Related process and style guides should go here. |
doc/legal/ | Legal documents about contributing to GitLab. |
doc/install/ | Instructions for installing GitLab. |
doc/update/ | Instructions for updating GitLab. |
doc/tutorials/ | Tutorials for how to use GitLab. |
The following are legacy or deprecated folders. Do not add new content to these folders:
/gitlab-basics/
/topics/
/university/
Work with directories and files
When working with directories and files:
- When you create a new directory, always start with an
index.md
file. Don’t use another filename and do not createREADME.md
files. - Do not use special characters and spaces, or capital letters in file names, directory names, branch names, and anything that generates a path.
- When creating or renaming a file or directory and it has more than one word
in its name, use underscores (
_
) instead of spaces or dashes. For example, proper naming would beimport_project/import_from_github.md
. This applies to both image files and Markdown files. - Do not upload video files to the product repositories. Link or embed videos instead.
- In the
doc/user/
directory:doc/user/project/
should contain all project related documentation.doc/user/group/
should contain all group related documentation.doc/user/profile/
should contain all profile related documentation. Every page you would navigate under/profile
should have its own document, for example,account.md
,applications.md
, oremails.md
.
- In the
doc/administration/
directory: all administrator-related documentation for administrators, including admin tasks done in both the UI and on the backend servers.
If you’re unsure where to place a document or a content addition, this shouldn’t stop you from authoring and contributing. Use your best judgment, and then ask the reviewer of your MR to confirm your decision. You can also ask a technical writer at any stage in the process. The technical writing team reviews all documentation changes, regardless, and can move content if there is a better place for it.
Avoid duplication
Do not include the same information in multiple places. Link to a single source of truth instead.
For example, if you have code in a repository other than the primary repositories, and documentation in the same repository, you can keep the documentation in that repository.
Then you can either:
- Publish it to https://docs.gitlab.com.
- Link to it from https://docs.gitlab.com by adding an entry in the global navigation. View an example.
References across documents
- Give each folder an
index.md
page that introduces the topic, and both introduces and links to the child pages, including to the index pages of any next-level sub-paths. - To ensure discoverability, ensure each new or renamed doc is linked from its higher-level index page and other related pages.
- When making reference to other GitLab products and features, link to their respective documentation, at least on first mention.
- When making reference to third-party products or technologies, link out to their external sites, documentation, and resources.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support